Classificação e filtragem de respostas na API do Serviço de fluxo

Ao executar solicitações de listagem (GET) na API de Serviço de Fluxo, você pode usar parâmetros de consulta para classificar e filtrar respostas. Este guia fornece uma referência sobre como usar esses parâmetros para casos de uso diferentes.

Classificação

Você pode classificar respostas usando um parâmetro de consulta orderby. Os seguintes recursos podem ser classificados na API:

Para usar o parâmetro, você deve definir seu valor para a propriedade específica pela qual deseja classificar (por exemplo, ?orderby=name). Você pode anexar o valor com um sinal de mais (+) em ordem crescente ou com um sinal de menos (-) em ordem decrescente. Se nenhum prefixo de ordenação for fornecido, a lista será classificada em ordem crescente por padrão.

GET /flows?orderby=name
GET /flows?orderby=-name

Você também pode combinar um parâmetro de classificação com um parâmetro de filtragem usando um símbolo "and" (&).

GET /flows?property=state==enabled&orderby=createdAt

Filtragem

Você pode filtrar respostas usando um parâmetro property com uma expressão de valor-chave. Por exemplo, ?property=id==12345 retorna apenas recursos cuja propriedade id seja exatamente igual a 12345.

A filtragem pode ser aplicada genericamente em qualquer propriedade em uma entidade, desde que o caminho válido para essa propriedade seja conhecido.

Retorna todas as conexões de origem em que o nome da tabela de origem é lead:

GET /sourceConnections?property=params.tableName==lead

Retornar todos os fluxos para uma ID de segmento específica:

GET /flows?property=transformations[].params.segmentSelectors.selectors[].value.id==5722a16f-5e1f-4732-91b6-3b03943f759a

Combinação de filtros

Vários filtros property podem ser incluídos em uma consulta, desde que sejam separados por caracteres "e" (&). Uma relação AND é presumida ao combinar filtros, o que significa que uma entidade deve satisfazer todos os filtros para ser incluída na resposta.

Retornar todos os fluxos habilitados para uma ID de segmento:

GET /flows?property=transformations[].params.segmentSelectors.selectors[].value.id==5722a16f-5e1f-4732-91b6-3b03943f759a&property=state==enabled

Filtragem nas propriedades da matriz arrays

Você pode filtrar com base nas propriedades dos itens dentro das matrizes, anexando [] ao nome da propriedade de matriz.

Retornar fluxos associados a conexões de origem específicas:

GET /flows?property=sourceConnectionIds[]==9874984,6980696

Fluxos de retorno que têm uma transformação contendo uma ID de valor de seletor específica:

GET /flows?property=transformations[].params.segmentSelectors.selectors[].value.id==5722a16f-5e1f-4732-91b6-3b03943f759a

Retorne conexões de origem que tenham uma coluna com um valor name específico:

GET /sourceConnections?property=params.columns[].name==firstName

Procure a ID de execução do fluxo para um destino filtrando a ID do segmento:

GET /runs?property=metrics.recordSummary.targetSummaries[].entitySummaries[].id==segment:068d6e2c-b546-4c73-bfb7-9a9d33375659

count

Qualquer consulta de filtragem pode ser anexada ao parâmetro de consulta count com um valor de true para retornar a contagem dos resultados. A resposta da API contém uma propriedade count cujo valor representa a contagem do total de itens filtrados. Os itens reais filtrados não são retornados nesta chamada.

Retorna a contagem de fluxos habilitados no sistema:

GET /flows?property=state==enabled&count=true

A resposta à consulta acima seria semelhante ao seguinte:

{
  "count": 95
}

Propriedades filtráveis por recurso

Dependendo da entidade do Serviço de Fluxo que você está recuperando, propriedades diferentes podem ser usadas para filtragem. As tabelas abaixo detalham os campos de nível raiz de cada recurso normalmente empregado na filtragem de casos de uso.

connectionSpec

flowSpec

connection

sourceConnection

targetConnection

flow

run

Casos de uso use-cases

Leia esta seção para obter alguns exemplos específicos de como você pode usar a filtragem e a classificação para retornar informações sobre determinados conectores ou para ajudá-lo a resolver problemas de depuração. Se houver algum caso de uso adicional que você queira que o Adobe adicione, use as Opções de feedback detalhadas na página para enviar uma solicitação.

Filtrar para retornar conexões somente a um determinado destino

Você pode usar filtros para retornar conexões somente a determinados destinos. Primeiro, consulte o ponto de extremidade connectionSpecs como abaixo:

GET /connectionSpecs

Em seguida, pesquise o connectionSpec desejado, inspecionando o parâmetro name. Por exemplo, pesquise por Amazon Ads, Pega, SFTP etc. no parâmetro name. O id correspondente é o connectionSpec pelo qual você pode pesquisar na próxima chamada de API.

Por exemplo, filtre seus destinos para retornar apenas conexões existentes com conexões do Amazon S3:

GET /connections?property=connectionSpec.id==4890fc95-5a1f-4983-94bb-e060c08e3f81

Filtrar para retornar fluxos de dados somente a destinos

Ao consultar o ponto de extremidade /flows, em vez de retornar todos os fluxos de dados de origens e destinos, você pode usar um filtro para retornar fluxos de dados somente a destinos. Para fazer isso, use isDestinationFlow como parâmetro de consulta, desta forma:

GET /flows?property=inheritedAttributes.properties.isDestinationFlow==true

Filtrar para retornar fluxos de dados somente a uma determinada origem ou destino

Você pode filtrar fluxos de dados para retornar fluxos de dados a um determinado destino ou somente a partir de uma determinada origem. Por exemplo, filtre seus destinos para retornar apenas conexões existentes com conexões do Amazon S3:

GET /flows?property=inheritedAttributes.targetConnections[].connectionSpec.id==4890fc95-5a1f-4983-94bb-e060c08e3f81

Filtrar para obter todas as execuções de um fluxo de dados por um período específico

É possível filtrar as execuções de fluxo de dados de um fluxo de dados para observar apenas as execuções em um determinado intervalo de tempo, como abaixo:

GET /runs?property=flowId==<flow-id>&property=metrics.durationSummary.startedAtUTC>1593134665781&property=metrics.durationSummary.startedAtUTC<1653134665781

Filtro para retornar somente fluxos de dados com falha

Para fins de depuração, você pode filtrar e ver todas as execuções de fluxo de dados com falha para um determinado fluxo de dados de origem ou destino, como abaixo:

GET /runs?property=flowId==<flow-id>&property=metrics.statusSummary.status==Failed

Próximas etapas

Este guia abordou como usar os parâmetros de consulta orderby e property para classificar e filtrar respostas na API do Serviço de Fluxo. Para obter guias passo a passo sobre como usar a API para fluxos de trabalho comuns na Platform, consulte os tutoriais da API contidos na documentação de fontes e destinos.