Filtrado de datos Catalog mediante parámetros de consulta

La API Catalog Service permite filtrar los datos de respuesta mediante el uso de parámetros de consulta de solicitud. Parte de las prácticas recomendadas para Catalog es utilizar filtros en todas las llamadas a la API, ya que reducen la carga en la API y ayudan a mejorar el rendimiento general.

Este documento describe los métodos más comunes para filtrar los objetos Catalog en la API. Se recomienda hacer referencia a este documento mientras lee la Guía para desarrolladores del catálogo para obtener más información sobre cómo interactuar con la API Catalog. Para obtener información más general sobre Catalog Service, consulte Catalog overview.

Limitar objetos devueltos

El parámetro de consulta limit restringe el número de objetos devueltos en una respuesta. Catalog las respuestas se miden automáticamente según los límites configurados:

• Si no se especifica un parámetro limit, el número máximo de objetos por carga útil de respuesta es de 20.
• Para consultas de conjuntos de datos, si se solicita observableSchema utilizando el parámetro de consulta properties , el número máximo de conjuntos de datos devueltos es 20.
• El límite global para todas las demás consultas de Catálogo es de 100 objetos.
• Los parámetros limit no válidos (incluido limit=0) dan como resultado respuestas de error de 400 niveles que describen los intervalos adecuados.
• Los límites o desplazamientos que se pasan como parámetros de consulta tienen prioridad sobre los que se pasan como encabezados.

Formato de API

GET /{OBJECT_TYPE}?limit={LIMIT}

Solicitud

La siguiente solicitud recupera una lista de conjuntos de datos mientras 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta devuelve una lista de conjuntos de datos, limitada al número indicado por el parámetro de consulta limit.

{
    "5ba9452f7de80400007fc52a": {
        "name": "Sample Dataset 1",
        "description": "Description of dataset.",
        "files": "@/dataSets/5ba9452f7de80400007fc52a/views/5ba9452f7de80400007fc52b/files"
    },
    "5bb276b03a14440000971552": {
        "name": "Sample Dataset 2",
        "description": "Description of dataset.",
        "files": "@/dataSets/5bb276b03a14440000971552/views/5bb276b01250b012f9acc75b/files"
    },
    "5bceaa4c26c115000039b24b": {
        "name": "Sample Dataset 3"
    }
}

Limitar las propiedades mostradas

Incluso cuando se filtra el número de objetos devueltos mediante el parámetro limit, los propios objetos devueltos suelen contener 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 solo un conjunto de propiedades especificadas. El parámetro se puede configurar para que devuelva una o varias propiedades.

El parámetro properties solo acepta propiedades de objeto de nivel superior, lo que significa que para el siguiente objeto de ejemplo, puede aplicar filtros para name, description y subItem, pero NO para 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 de nombres de propiedad separados por comas que se proporciona 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta devuelve una lista de objetos Catalog 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"
        }
    }
}

En función de la respuesta anterior, se puede inferir lo siguiente:

• Si a un objeto le faltan propiedades solicitadas, solo se mostrarán las propiedades solicitadas que incluye. (Dataset1)
• Si un objeto no incluye ninguna de las propiedades solicitadas, aparecerá como objeto vacío. (Dataset2)
• Un conjunto de datos puede devolver una propiedad solicitada como un objeto vacío si contiene la propiedad pero no hay ningún valor. (Dataset3)
• De lo contrario, el conjunto de datos mostrará el valor completo de todas las propiedades solicitadas. (Dataset4)

Índice inicial de desplazamiento de la lista de respuestas

El parámetro de consulta start desplaza hacia delante la lista de respuestas en un número especificado mediante la numeración basada en cero. Por ejemplo, start=2 desví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, compensando con el 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: {IMS_ORG}' \
  -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 cambia por cuatro (start=4), lo que significa que los conjuntos de datos mostrados son los números 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 luego utilizarse más adelante para recuperarlo. La elección de las etiquetas que se deben utilizar y cómo aplicarlas depende de los procesos de organización.

Hay algunas limitaciones que hay que tener en cuenta al utilizar etiquetas:

• Los únicos objetos de catálogo que admiten etiquetas actualmente son conjuntos de datos, lotes y conexiones.
• Los nombres de las etiquetas son exclusivos de su organización de IMS.
• Los procesos de Adobe pueden aprovechar las etiquetas para ciertos comportamientos. A los nombres de estas etiquetas se les agregará el prefijo "adobe" como estándar. Por lo tanto, debe evitar esta convención al declarar nombres de etiquetas.
• Los siguientes nombres de etiquetas están reservados para su uso en Experience Platform y, por lo tanto, no se pueden declarar como nombre de etiqueta para su organización:
  • unifiedProfile: Este nombre de etiqueta está reservado para que Real-time Customer Profile ingrese conjuntos de datos.
  • unifiedIdentity: Este nombre de etiqueta está reservado para que Identity Service ingrese conjuntos de datos.

A continuación se muestra un ejemplo de un conjunto de datos que contiene una propiedad tags . Las etiquetas 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": "{IMS_ORG}",
        "tags": {
            "sampleTag": [
                "123456"
            ],
            "secondTag": [
                "sample_tag_value"
            ]
        },
        "name": "Sample Dataset",
        "description": "Same dataset containing sample data.",
        "dule": {
            "identity": [
                "I1"
            ]
        },
        "statsCache": {},
        "state": "DRAFT",
        "lastBatchId": "ca12b29612bf4052872edad59573703c",
        "lastBatchStatus": "success",
        "lastSuccessfulBatch": "ca12b29612bf4052872edad59573703c",
        "namespace": "{NAMESPACE}",
        "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, utilizando 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 valores de etiqueta. Por ejemplo, una cadena de búsqueda test* devuelve cualquier objeto donde el valor de la etiqueta comience por "test". Una cadena de búsqueda que consiste únicamente en un comodín puede utilizarse 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta devuelve una lista de conjuntos de datos que contienen sampleTag con un valor de "123456", AND 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": "{IMS_ORG}",
            "name": "Example Dataset 1",
            "created": 1533539550237,
            "updated": 1533539552416,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "tags": {
                "sampleTag": [
                    "123456"
                ],
                "secondTag": [
                    "Example tag value"
                ]
            },
            "dule": {},
            "statsCache": {}
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.0",
            "imsOrg": "{IMS_ORG}",
            "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"
                ]
            },
            "dule": {},
            "statsCache": {}
    }
}

Filtrar por intervalo de fechas

Algunos extremos de la API Catalog tienen parámetros de consulta que permiten consultas de rango, la mayoría de las veces en el caso de 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta contiene una lista de objetos Catalog 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": "{IMS_ORG}",
            "name": "Example Dataset 1",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.0",
            "imsOrg": "{IMS_ORG}",
            "name": "Example Dataset 2",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    }
}

Ordenar por propiedad

El parámetro de consulta orderBy 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 luego una propiedad para 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, se utilizará la segunda propiedad de ordenación para ordenar aún más los 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 clasificación, name. En los casos en los que varios registros comparten la misma propiedad name , los registros coincidentes se ordenan por la segunda propiedad de clasificación, created. Si ningún registro devuelto comparte el mismo name, la propiedad created no tiene en cuenta el orden.

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 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta contiene una lista de objetos Catalog 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": "{IMS_ORG}",
            "name": "0405",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.3",
            "imsOrg": "{IMS_ORG}",
            "name": "AAM Dataset",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    },
    "5cd3a129ec106214b722a939": {
            "version": "1.0.2",
            "imsOrg": "{IMS_ORG}",
            "name": "AAM Dataset",
            "created": 1554028394852,
            "updated": 1554130582960,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    }
}

Filtrar por propiedad

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

• Uso de filtros simples: Filtre por si una propiedad específica coincide con un valor específico.
• Uso del parámetro de propiedad: Utilice expresiones condicionales para filtrar en función de si existe una propiedad o si el valor de una propiedad coincide, se aproxima o compara con otro valor especificado o expresión regular.

Uso de filtros simples

Los filtros simples le permiten filtrar 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 solo devuelve objetos cuya propiedad name contiene el valor "exampleName". Por el contrario, la consulta name=!exampleName solo devuelve objetos cuya propiedad name es no "exampleName".

Además, los filtros simples admiten la capacidad de realizar consultas de varios valores para una sola propiedad. Cuando se proporcionan varios valores, la respuesta devuelve objetos cuya propiedad coincide con any de los valores de la lista proporcionada. Puede invertir una consulta de varios valores prefiriendo un carácter ! a la lista, devolviendo solo los 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 "otherName".

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta contiene una lista de conjuntos de datos, excluyendo cualquier conjunto de datos cuyo name sea "exampleName" u "otherName". 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": "{IMS_ORG}",
            "name": "exampleName",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.3",
            "imsOrg": "{IMS_ORG}",
            "name": "anotherName",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    }
}

Uso del parámetro property

El parámetro de consulta property proporciona más flexibilidad para el filtrado basado en propiedades que los filtros simples. Además de filtrar en función de si una propiedad tiene un valor específico, el parámetro property puede utilizar otros operadores de comparación (como "more-than" (>) y "less-than" (<), 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.

El parámetro property solo acepta propiedades de objeto de nivel superior, lo que significa que para el siguiente objeto de ejemplo, puede filtrar por propiedad para name, description y subItem, pero NO para 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. La siguiente tabla 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 bueno a la 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta contiene una lista de conjuntos de datos cuyos números de versión son buenos 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": "{IMS_ORG}",
            "name": "sampleDataset",
            "created": 1554930967705,
            "updated": 1554931119718,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    },
    "5b1e3c867e6d2600003d5b49": {
            "version": "1.0.6",
            "imsOrg": "{IMS_ORG}",
            "name": "exampleDataset",
            "created": 1554974386247,
            "updated": 1554974386268,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    },
    "5cd3a129ec106214b722a939": {
            "version": "1.0.4",
            "imsOrg": "{IMS_ORG}",
            "name": "anotherDataset",
            "created": 1554028394852,
            "updated": 1554130582960,
            "createdClient": "{API_KEY}",
            "createdUser": "{USER_ID}",
            "updatedUser": "{USER_ID}",
            "dule": {},
            "statsCache": {}
    }
}

Combinación de varios filtros

Con un símbolo & (&), se pueden combinar varios filtros en una única solicitud. Cuando se agregan condiciones adicionales a una solicitud, se asume una relación AND.

Formato de API

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