Filtrar dados Catalog usando parâmetros de consulta

A API Catalog Service permite que os dados de resposta sejam filtrados por meio do uso de parâmetros de consulta de solicitação. Parte das práticas recomendadas para Catalog é usar filtros em todas as chamadas de API, pois eles reduzem a carga na API e ajudam a melhorar o desempenho geral.

Este documento descreve os métodos mais comuns para filtrar Catalog objetos na API. É recomendável que você faça referência a este documento ao ler o Guia do desenvolvedor do catálogo para saber mais sobre como interagir com a API Catalog. Para obter informações mais gerais sobre Catalog Service, consulte a Catalog visão geral.

Limitar objetos retornados

O parâmetro de consulta limit restringe o número de objetos retornados em uma resposta. Catalog respostas são automaticamente medidas de acordo com os limites configurados:

Formato da API

GET /{OBJECT_TYPE}?limit={LIMIT}

Solicitação

A solicitação a seguir recupera uma lista de conjuntos de dados enquanto limita a resposta a três objetos.

curl -X GET \
  https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna uma lista de conjuntos de dados, limitada ao número indicado pelo parâmetro de consulta limit.

{
    "5ba9452f7de80400007fc52a": {
        "name": "Sample Dataset 1",
        "description": "Description of dataset.",
        "files": "@/dataSetFiles?dataSetId=5ba9452f7de80400007fc52a"
    },
    "5bb276b03a14440000971552": {
        "name": "Sample Dataset 2",
        "description": "Description of dataset.",
        "files": "@/dataSetFiles?dataSetId=5bb276b03a14440000971552"
    },
    "5bceaa4c26c115000039b24b": {
        "name": "Sample Dataset 3"
    }
}

Limitar propriedades exibidas

Mesmo ao filtrar o número de objetos retornados usando o parâmetro limit, os próprios objetos retornados geralmente podem conter mais informações do que você realmente precisa. Para reduzir ainda mais a carga no sistema, é prática recomendada filtrar as respostas para incluir apenas as propriedades necessárias.

O parâmetro properties filtra objetos de resposta para retornar apenas um conjunto de propriedades especificadas. O parâmetro pode ser definido para retornar uma ou várias propriedades.

O parâmetro properties pode aceitar qualquer propriedade de objeto de nível. sampleKey pode ser extraído usando ?properties=subItem.sampleKey.

{
  "5ba9452f7de80400007fc52a": {
      "name": "Sample Dataset",
      "description": "Sample dataset containing important data",
      "subitem": {
          "sampleKey": "sampleValue"
      }
  }
}

Formato da API

GET /{OBJECT_TYPE}?properties={PROPERTY}
GET /{OBJECT_TYPE}?properties={PROPERTY_1},{PROPERTY_2},{PROPERTY_3}
GET /{OBJECT_TYPE}/{OBJECT_ID}?properties={PROPERTY_1},{PROPERTY_2},{PROPERTY_3}

Solicitação

A solicitação a seguir recupera uma lista de conjuntos de dados. A lista separada por vírgulas de nomes de propriedades fornecida sob o parâmetro properties indica as propriedades a serem retornadas na resposta. Um parâmetro limit também está incluído, o que limita o número de conjuntos de dados retornados. Se a solicitação não incluísse um parâmetro limit, a resposta conteria no máximo 20 objetos.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?limit=4&properties=name,schemaRef' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna uma lista de Catalog objetos com apenas as propriedades solicitadas exibidas.

{
    "Dataset1": {
        "name": "Dataset 1",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/bc82c518380478b59a95c63e0f843121",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "Dataset2": {},
    "Dataset3": {
        "name": {},
    },
    "Dataset4": {
        "name": "Dataset 4",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Com base na resposta acima, pode-se inferir o seguinte:

Índice de início de deslocamento da lista de respostas

O parâmetro de consulta start desloca a lista de respostas em direção a um número especificado, usando uma numeração baseada em zero. Por exemplo, start=2 deslocaria a resposta para iniciar no terceiro objeto listado.

Se o parâmetro start não estiver emparelhado com um parâmetro limit, o número máximo de objetos retornados será 20.

Formato da API

GET /{OBJECT_TYPE}?start={OFFSET}

Solicitação

A solicitação a seguir recupera uma lista de conjuntos de dados, deslocando para o quinto objeto (start=4) e limitando a resposta a dois conjuntos de dados retornados (limit=2).

curl -X GET \
  https://platform.adobe.io/data/foundation/catalog/dataSets?start=4&limit=2 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

A resposta inclui um objeto JSON contendo dois itens de nível superior (limit=2), um para cada conjunto de dados e seus detalhes (os detalhes foram condensados no exemplo). A resposta é deslocada em quatro (start=4), o que significa que os conjuntos de dados mostrados são os números cinco e seis cronologicamente.

{
    "Dataset5": {},
    "Dataset6": {}
}

Filtrar por tag

Alguns objetos de Catálogo oferecem suporte ao uso de um atributo tags. As tags podem anexar informações a um objeto e ser usadas posteriormente para recuperá-lo. A escolha de quais tags usar e como aplicá-las depende dos processos organizacionais.

Há algumas limitações a serem consideradas ao usar tags:

Veja abaixo um exemplo de um conjunto de dados que contém uma propriedade tags. As tags nessa propriedade assumem a forma de pares de valores chave, com cada valor de tag aparecendo como uma matriz contendo uma única string:

{
    "5be1f2ecc73c1714ceba66e2": {
        "imsOrg": "{ORG_ID}",
        "tags": {
            "sampleTag": [
                "123456"
            ],
            "secondTag": [
                "sample_tag_value"
            ]
        },
        "name": "Sample Dataset",
        "description": "Same dataset containing sample data.",
        "createdUser": "{CREATED_USER}",
        "createdClient": "{CREATED_CLIENT}",
        "updatedUser": "{UPDATED_USER}",
        "version": "1.0.0",
        "created": 1541534444286,
        "updated": 1541534444286
    }
}

Formato da API

Os valores do parâmetro tags tomam a forma de pares de valores chave, usando o formato {TAG_NAME}:{TAG_VALUE}. Vários pares de valores-chave podem ser fornecidos no formato de uma lista separada por vírgulas. Quando várias tags são fornecidas, uma relação AND é presumida.

O parâmetro dá suporte a caracteres curingas (*) para valores de marca. Por exemplo, uma cadeia de caracteres de pesquisa de test* retorna qualquer objeto em que o valor da marca comece com "test". Uma string de pesquisa que consiste apenas em um curinga pode ser usada para filtrar objetos com base no fato de eles conterem ou não uma tag específica, independentemente do valor.

GET /{OBJECT_TYPE}?tags={TAG_NAME}:{TAG_VALUE}
GET /{OBJECT_TYPE}?tags={TAG_NAME_1}:{TAG_VALUE_1},{TAG_NAME_2}:{TAG_VALUE_2}
GET /{OBJECT_TYPE}?tags={TAG_NAME}:{TAG_VALUE}*
GET /{OBJECT_TYPE}?tags={TAG_NAME}:*

Solicitação

A solicitação a seguir recupera uma lista de conjuntos de dados, filtrando por uma tag com um valor específico E a segunda tag presente.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?tags=sampleTag:123456,secondTag:* \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida retorna uma lista de conjuntos de dados que contêm sampleTag com o valor "123456", E secondTag com qualquer valor. A menos que um limite também seja especificado, a resposta conterá no máximo 20 objetos.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 1",
            "created": 1533539550237,
            "updated": 1533539552416,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "tags": {
                "sampleTag": [
                    "123456"
                ],
                "secondTag": [
                    "Example tag value"
                ]
            },
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.0",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 2",
            "created": 1533539550237,
            "updated": 1533539552416,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "tags": {
                "sampleTag": [
                    "123456"
                ],
                "secondTag": [
                    "A different tag value"
                ],
                "anotherTag": [
                    "2.0"
                ]
            },
    }
}

Filtrar por intervalo de datas

Alguns pontos de extremidade na API Catalog têm parâmetros de consulta que permitem consultas de intervalo, com mais frequência no caso de datas.

Formato da API

GET /batches?createdAfter={TIMESTAMP_1}&createdBefore={TIMESTAMP_2}

Solicitação

A solicitação a seguir recupera uma lista de lotes criados durante o mês de abril de 2019.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/batches?createdAfter=1554076800000&createdBefore=1556668799000' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida contém uma lista de Catalog objetos que estão dentro do intervalo de datas especificado. A menos que um limite também seja especificado, a resposta conterá no máximo 20 objetos.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 1",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.0",
            "imsOrg": "{ORG_ID}",
            "name": "Example Dataset 2",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Classificar por propriedade

O parâmetro de consulta orderBy permite classificar (ordenar) dados de resposta com base em um valor de propriedade especificado. Este parâmetro requer uma "direção" (asc para crescente ou desc para decrescente), seguido por dois-pontos (:) e uma propriedade para classificar os resultados. Se uma direção não for especificada, a direção padrão será ascendente.

Várias propriedades de classificação podem ser fornecidas em uma lista separada por vírgulas. Se a primeira propriedade de classificação produzir vários objetos que contêm o mesmo valor para essa propriedade, a segunda propriedade de classificação será usada para classificar ainda mais esses objetos correspondentes.

Por exemplo, considere a seguinte consulta: orderBy=name,desc:created. Os resultados são classificados em ordem crescente com base na primeira propriedade de classificação, name. Nos casos em que vários registros compartilham a mesma propriedade name, esses registros correspondentes são classificados pela segunda propriedade de classificação, created. Se nenhum registro retornado compartilhar o mesmo name, a propriedade created não será considerada na classificação.

Formato da API

GET /{OBJECT_TYPE}?orderBy=asc:{PROPERTY_NAME}
GET /{OBJECT_TYPE}?orderBy=desc:{PROPERTY_NAME}
GET /{OBJECT_TYPE}?orderBy={PROPERTY_NAME_1},desc:{PROPERTY_NAME_2}

Solicitação

A solicitação a seguir recupera uma lista de conjuntos de dados classificados por sua propriedade name. Se algum conjunto de dados compartilhar o mesmo name, ele será ordenado por sua propriedade updated em ordem decrescente.

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?orderBy=name,desc:updated' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida contém uma lista de Catalog objetos que estão classificados de acordo com o parâmetro orderBy. A menos que um limite também seja especificado, a resposta conterá no máximo 20 objetos.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "0405",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.3",
            "imsOrg": "{ORG_ID}",
            "name": "AAM Dataset",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5cd3a129ec106214b722a939": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "AAM Dataset",
            "created": 1554028394852,
            "updated": 1554130582960,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Filtrar por propriedade

Catalog fornece dois métodos de filtragem por propriedade, que são descritos nas seções a seguir:

Utilização de filtros simples using-simple-filters

Filtros simples permitem filtrar respostas com base em valores de propriedade específicos. Um filtro simples toma a forma de {PROPERTY_NAME}={VALUE}.

Por exemplo, a consulta name=exampleName retorna somente objetos cuja propriedade name contenha um valor de "exampleName". Por outro lado, a consulta name=!exampleName retorna somente objetos cuja propriedade name é não "exampleName".

Além disso, filtros simples suportam a capacidade de consultar vários valores para uma única propriedade. Quando vários valores são fornecidos, a resposta retorna objetos cuja propriedade corresponde a qualquer dos valores na lista fornecida. Você pode inverter uma consulta de vários valores prefixando um caractere ! à lista, retornando apenas objetos cujo valor de propriedade é não na lista fornecida (por exemplo, name=!exampleName,anotherName).

Formato da API

GET /{OBJECT_TYPE}?{PROPERTY_NAME}={VALUE}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}=!{VALUE}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}={VALUE_1},{VALUE_2},{VALUE_3}
GET /{OBJECT_TYPE}?{PROPERTY_NAME}=!{VALUE_1},{VALUE_2},{VALUE_3}

Solicitação

A solicitação a seguir recupera uma lista de conjuntos de dados, filtrada para incluir apenas conjuntos de dados cuja propriedade name tenha um valor de "exampleName" ou "anotherName".

curl -X GET \
  'https://platform.adobe.io/data/foundation/catalog/dataSets?name=exampleName,anotherName' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida contém uma lista de conjuntos de dados, excluindo todos os conjuntos de dados cujo name seja "exampleName" ou "anotherName". A menos que um limite também seja especificado, a resposta conterá no máximo 20 objetos.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.0.2",
            "imsOrg": "{ORG_ID}",
            "name": "exampleName",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.3",
            "imsOrg": "{ORG_ID}",
            "name": "anotherName",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Usando o parâmetro property using-the-property-parameter

O parâmetro de consulta property oferece mais flexibilidade para filtragem baseada em propriedade do que filtros simples. Além de filtrar com base no fato de uma propriedade ter ou não um valor específico, o parâmetro property pode usar outros operadores de comparação (como "maior que" (>) e "menor que" (<)), bem como expressões regulares para filtrar por valores de propriedade. Também pode filtrar se uma propriedade existe ou não, independentemente do seu valor.

O parâmetro property pode aceitar qualquer propriedade de objeto de nível. sampleKey pode ser usado para filtragem usando ?properties=subItem.sampleKey.

{
  "5ba9452f7de80400007fc52a": {
      "name": "Sample Dataset",
      "description": "Sample dataset containing important data",
      "subitem": {
          "sampleKey": "sampleValue"
      }
  }
}

Formato da API

GET /{OBJECT_TYPE}?property={CONDITION}

O valor do parâmetro property dá suporte a vários tipos diferentes de expressões condicionais. A tabela a seguir descreve a sintaxe básica para expressões suportadas:

Solicitação

A solicitação a seguir retornará qualquer conjunto de dados com um número de versão superior a 1.0.3.

curl -X GET \
  https://platform.adobe.io/data/foundation/catalog/dataSets?property=version>1.0.3 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Resposta

Uma resposta bem-sucedida contém uma lista de conjuntos de dados cujos números de versão são maiores que 1.0.3. A menos que um limite também seja especificado, a resposta conterá no máximo 20 objetos.

{
    "5b67f4dd9f6e710000ea9da4": {
            "version": "1.1.2",
            "imsOrg": "{ORG_ID}",
            "name": "sampleDataset",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.6",
            "imsOrg": "{ORG_ID}",
            "name": "exampleDataset",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    },
    "5cd3a129ec106214b722a939": {
            "version": "1.0.4",
            "imsOrg": "{ORG_ID}",
            "name": "anotherDataset",
            "created": 1554028394852,
            "updated": 1554130582960,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
    }
}

Combinar vários filtros

Usando um E comercial (&), você pode combinar vários filtros em uma única solicitação. Quando condições adicionais são adicionadas a uma solicitação, uma relação AND é presumida.

Formato da API

GET /{OBJECT_TYPE}?{FILTER_1}={VALUE}&{FILTER_2}={VALUE}&{FILTER_3}={VALUE}