Filtrar datos de Catalog mediante parámetros de consulta

Para mejorar el rendimiento y recuperar los resultados relevantes, utilice parámetros de consulta para filtrar Catalog Service datos de respuesta de API.

Obtenga información acerca de métodos de filtrado comunes para objetos Catalog en la API. Utilice este documento junto con la Guía para desarrolladores de catálogos para obtener más información sobre las interacciones de API. Para obtener información general sobre Catalog Service, consulte la Catalog descripción general.

Límite de objetos devueltos limit-returned-objects

El parámetro de consulta limit restringe el número de objetos devueltos en una respuesta. Catalog respuestas siguen límites predefinidos:

Formato de API

GET /{OBJECT_TYPE}?limit={LIMIT}

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos y limita la respuesta a tres 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}'

Respuesta

Una respuesta correcta devuelve una lista de conjuntos de datos, limitados al número indicado por el 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 propiedades mostradas limit-displayed-properties

Incluso cuando se filtra el número de objetos devueltos mediante el parámetro limit, los propios objetos devueltos pueden contener con frecuencia más información de la que realmente necesita. Para reducir aún más la carga en el sistema, se recomienda filtrar las respuestas para incluir solo las propiedades que necesite.

El parámetro properties filtra los objetos de respuesta para devolver solamente un conjunto de propiedades especificadas. El parámetro se puede establecer para que devuelva una o varias propiedades.

El parámetro properties puede aceptar cualquier propiedad de objeto de nivel. sampleKey se puede extraer usando ?properties=subItem.sampleKey.

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

Formato de 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}

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos. La lista separada por comas de los nombres de propiedad proporcionados en el parámetro properties indica las propiedades que se van a devolver en la respuesta. También se incluye un parámetro limit, que limita el número de conjuntos de datos devueltos. Si la solicitud no incluía un parámetro limit, la respuesta contendría un máximo de 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}'

Respuesta

Una respuesta correcta devuelve una lista de Catalog objetos con solo las propiedades solicitadas mostradas.

{
    "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"
        }
    }
}

Sobre la base de la respuesta anterior, se puede inferir lo siguiente:

Desplazamiento del índice inicial de la lista de respuestas offset-starting-index

El parámetro de consulta start desplaza la lista de respuestas un número especificado, utilizando la numeración basada en cero. Por ejemplo, start=2 desplazaría la respuesta para comenzar en el tercer objeto de la lista.

Si el parámetro start no está emparejado con un parámetro limit, el número máximo de objetos devueltos es 20.

Formato de API

GET /{OBJECT_TYPE}?start={OFFSET}

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos, desplazándose al quinto objeto (start=4) y limitando la respuesta a dos conjuntos de datos devueltos (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}'

Respuesta

La respuesta incluye un objeto JSON que contiene dos elementos de nivel superior (limit=2), uno para cada conjunto de datos y sus detalles (los detalles se han resumido en el ejemplo). La respuesta se desplaza en cuatro (start=4), lo que significa que los conjuntos de datos mostrados son el número cinco y seis cronológicamente.

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

Filtrar por etiqueta

Algunos objetos Catalog admiten el uso de un atributo tags. Las etiquetas pueden adjuntar información a un objeto y utilizarla más adelante para recuperarlo. La elección de las etiquetas que se van a utilizar y cómo aplicarlas depende de los procesos de organización.

Hay algunas limitaciones que se deben tener en cuenta al utilizar etiquetas:

A continuación se muestra un ejemplo de un conjunto de datos que contiene una propiedad tags. Las etiquetas dentro de esa propiedad toman la forma de pares clave-valor, y cada valor de etiqueta aparece como una matriz que contiene una sola cadena:

{
    "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 de API

Los valores del parámetro tags toman la forma de pares clave-valor, con el formato {TAG_NAME}:{TAG_VALUE}. Se pueden proporcionar varios pares de clave-valor en forma de lista separada por comas. Cuando se proporcionan varias etiquetas, se asume una relación AND.

El parámetro admite caracteres comodín (*) para los valores de etiqueta. Por ejemplo, una cadena de búsqueda de test* devuelve cualquier objeto donde el valor de la etiqueta comience por "test". Se puede utilizar una cadena de búsqueda formada únicamente por un comodín para filtrar objetos en función de si contienen o no una etiqueta específica, independientemente de su 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}:*

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos, filtrando por una etiqueta que tiene un valor específico Y la segunda etiqueta que está 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}'

Respuesta

Una respuesta correcta devuelve una lista de conjuntos de datos que contienen sampleTag con el valor "123456" Y secondTag con cualquier valor. A menos que también se especifique un límite, la respuesta contiene un máximo de 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 fechas

Algunos extremos de la API Catalog tienen parámetros de consulta que permiten consultas de intervalo, la mayoría de las veces en el caso de las fechas.

Formato de API

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

Solicitud

La siguiente solicitud recupera una lista de lotes creados durante el mes 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}'

Respuesta

Una respuesta correcta contiene una lista de Catalog objetos que se encuentran dentro del intervalo de fechas especificado. A menos que también se especifique un límite, la respuesta contiene un máximo de 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}",
    }
}

Ordenar por propiedad

El parámetro de consulta orderBy le permite ordenar los datos de respuesta en función de un valor de propiedad especificado. Este parámetro requiere una "dirección" (asc para ascendente o desc para descendente), seguida de dos puntos (:) y, a continuación, una propiedad por la que ordenar los resultados. Si no se especifica una dirección, la dirección predeterminada es ascendente.

Se pueden proporcionar varias propiedades de ordenación en una lista separada por comas. Si la primera propiedad de ordenación produce varios objetos que contienen el mismo valor para esa propiedad, la segunda propiedad de ordenación se utiliza para ordenar aún más esos objetos coincidentes.

Por ejemplo, considere la siguiente consulta: orderBy=name,desc:created. Los resultados se ordenan en orden ascendente según la primera propiedad de ordenación, name. En los casos en que varios registros comparten la misma propiedad name, esos registros coincidentes se ordenan por la segunda propiedad de ordenación, created. Si ningún registro devuelto comparte el mismo(a) name, la propiedad created no se tiene en cuenta en la ordenación.

Formato de 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}

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos ordenados por su propiedad name. Si algún conjunto de datos comparte el mismo(a) name, esos conjuntos de datos a su vez se ordenarán por su propiedad updated en orden descendente.

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}'

Respuesta

Una respuesta correcta contiene una lista de Catalog objetos que se ordenan según el parámetro orderBy. A menos que también se especifique un límite, la respuesta contiene un máximo de 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 propiedad

Catalog proporciona dos métodos de filtrado por propiedad, que se describen con más detalle en las secciones siguientes:

Uso de filtros simples using-simple-filters

Los filtros simples le permiten filtrar las respuestas en función de valores de propiedad específicos. Un filtro simple adopta la forma de {PROPERTY_NAME}={VALUE}.

Por ejemplo, la consulta name=exampleName devuelve únicamente objetos cuya propiedad name contiene el valor "exampleName". Por el contrario, la consulta name=!exampleName devuelve solamente objetos cuya propiedad name sea no "exampleName".

Además, los filtros simples admiten la capacidad de consultar varios valores para una sola propiedad. Cuando se proporcionan varios valores, la respuesta devuelve objetos cuya propiedad coincide con cualquiera de los valores de la lista proporcionada. Puede invertir una consulta de varios valores prefiriendo un carácter ! a la lista y devolviendo únicamente objetos cuyo valor de propiedad sea no en la lista proporcionada (por ejemplo, name=!exampleName,anotherName).

Formato de 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}

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos, filtrados para incluir solo conjuntos de datos cuya propiedad name tiene el valor "exampleName" u "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}'

Respuesta

Una respuesta correcta contiene una lista de conjuntos de datos, que excluye cualquier conjunto de datos cuyo name sea "exampleName" u "anotherName". A menos que también se especifique un límite, la respuesta contiene un máximo de 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 el parámetro property using-the-property-parameter

El parámetro de consulta property proporciona más flexibilidad para el filtrado basado en propiedades que los filtros simples. Además del filtrado basado en si una propiedad tiene un valor específico, el parámetro property puede utilizar otros operadores de comparación (como "más que" (>) y "menos que" (<)), así como expresiones regulares para filtrar por valores de propiedad. También puede filtrar por si existe o no una propiedad, independientemente de su valor.

Use un signo & (&) para combinar varios filtros y restringir la consulta en una única solicitud. Cuando filtra por varios campos, se aplica una relación AND de forma predeterminada.

GET /datasets?property=id==abc123&property=name!=test

Si usa varios parámetros property en el mismo campo, solo surtirá efecto el último parámetro especificado.

El parámetro property puede aceptar cualquier propiedad de objeto de nivel. sampleKey se puede usar para filtrar con ?properties=subItem.sampleKey.

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

Formato de API

GET /{OBJECT_TYPE}?property={CONDITION}

El valor del parámetro property admite varios tipos diferentes de expresiones condicionales. En la tabla siguiente se describe la sintaxis básica de las expresiones admitidas:

Solicitud

La siguiente solicitud devolverá cualquier conjunto de datos con un número de versión mayor que 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}'

Respuesta

Una respuesta correcta contiene una lista de conjuntos de datos cuyos números de versión son superiores a 1.0.3. A menos que también se especifique un límite, la respuesta contiene un máximo de 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}",
    }
}

Filtrar matrices con el parámetro de propiedad filter-arrays

Utilice operadores de igualdad y desigualdad para incluir o excluir valores específicos al filtrar los resultados en función de propiedades de matriz.

Filtros de igualdad equality-filters

Para filtrar un campo de matriz por varios valores, utilice parámetros de propiedad independientes para cada valor. Utilice los filtros de igualdad para devolver únicamente las entradas de la matriz de datos que coincidan con los valores especificados.

La consulta de ejemplo siguiente solo devuelve los resultados de la matriz que incluye val1 y val2.

Formato de API

GET /{OBJECT_TYPE}?property=arrayField=val1&property=arrayField=val2

Filtros de desigualdad inequality-filters

Utilice operadores de desigualdad (!=) en un campo de matriz para excluir cualquier entrada de los datos donde la matriz contenga los valores especificados.

Formato de API

GET /{OBJECT_TYPE}?property=arrayField!=val1&property=arrayField!=val2

Esta consulta devuelve documentos donde arrayField no contiene val1 ni val2.

Limitaciones del filtro de igualdad y desigualdad equality-inequality-limitations

No se pueden aplicar igualdad (=) y desigualdad (!=) al mismo campo en una sola consulta.