Filtrer Catalog données à l’aide de paramètres de requête

Pour améliorer les performances et récupérer des résultats pertinents, utilisez les paramètres de requête pour filtrer les données de réponse de l’API Catalog Service.

Découvrez les méthodes de filtrage courantes pour les objets Catalog dans l’API. Utilisez ce document avec le Guide du développeur du catalogue pour plus d’informations sur les interactions d’API. Pour obtenir des informations Catalog Service générales, consultez la Catalog présentation.

Limiter les objets renvoyés limit-returned-objects

Le paramètre de requête limit limite le nombre d’objets renvoyés dans une réponse. Catalog réponses suivent des limites prédéfinies :

Format d’API

GET /{OBJECT_TYPE}?limit={LIMIT}

Requête

La requête suivante récupère une liste de jeux de données en limitant la réponse à trois objets.

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

Réponse

Une réponse réussie renvoie une liste de jeux de données, limitée au nombre indiqué par le paramètre de requête 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"
    }
}

Limiter les propriétés affichées limit-displayed-properties

Même lorsque le nombre d’objets renvoyés est filtré à l’aide du paramètre limit, les objets renvoyés eux-mêmes peuvent souvent contenir plus d’informations que nécessaire. Pour réduire davantage la charge sur le système, il est recommandé de filtrer les réponses afin d’inclure uniquement les propriétés dont vous avez besoin.

Le paramètre properties filtre les objets de réponse pour renvoyer uniquement un ensemble de propriétés spécifiées. Ce paramètre peut être défini pour renvoyer une ou plusieurs propriétés.

Le paramètre properties peut accepter n'importe quelle propriété d'objet de niveau. Les sampleKey peuvent être extraites à l’aide de ?properties=subItem.sampleKey.

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

Format d’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}

Requête

La requête suivante récupère une liste de jeux de données. La liste de noms de propriétés séparés par des virgules fournie sous le paramètre properties indique les propriétés à renvoyer dans la réponse. Un paramètre limit est également inclus pour limiter le nombre de jeux de données renvoyés. Si la requête n’incluait pas de paramètre limit, la réponse contiendrait 20 objets maximum.

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

Réponse

Une réponse réussie renvoie une liste d’objets Catalog avec seulement les propriétés demandées affichées.

{
    "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 fonction de la réponse ci-dessus, vous pouvez en déduire ce qui suit :

Décalage de l’index de départ de la liste de réponses offset-starting-index

Le paramètre de requête start décale la liste de réponses vers l’avant d’un nombre spécifié, en utilisant une numérotation à partir de zéro. Par exemple, start=2 décalerait la réponse pour qu’elle commence à partir du troisième objet répertorié.

Si le paramètre start n’est associé à aucun paramètre limit, le nombre maximal d’objets renvoyés est de 20.

Format d’API

GET /{OBJECT_TYPE}?start={OFFSET}

Requête

La requête suivante récupère une liste de jeux de données, décalée au cinquième objet (start=4) et qui limite la réponse à deux jeux de données renvoyés (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}'

Réponse

La réponse comprend un objet JSON contenant deux éléments de niveau supérieur (limit=2), un pour chaque jeu de données ainsi que leurs détails (les détails ont été condensés dans l’exemple). La réponse est décalée de quatre (start=4), ce qui signifie que les jeux de données affichés sont chronologiquement les cinquième et sixième.

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

Filtrage par balise

Certains objets Catalog prennent en charge l’utilisation d’un attribut tags. Les balises peuvent joindre des informations à un objet, puis être utilisées ultérieurement pour récupérer cet objet. Le choix des balises à utiliser et la manière de les appliquer dépendent de vos processus organisationnels.

Quelques limites doivent être prises en compte lors de l’utilisation de balises :

Vous trouverez ci-dessous un exemple de jeu de données contenant une propriété tags. Les balises de cette propriété prennent la forme de paires clé-valeur, où chaque valeur de balise apparaît sous la forme d’une matrice contenant une seule chaîne :

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

Format d’API

Les valeurs du paramètre tags prennent la forme de paires clé-valeur sous le format {TAG_NAME}:{TAG_VALUE}. Plusieurs paires clé-valeur peuvent être fournies sous la forme d’une liste dont les valeurs sont séparées par des virgules. Lorsque plusieurs balises sont fournies, l’existence d’une relation ET est supposée.

Le paramètre prend en charge les caractères génériques (*) pour les valeurs de balise. Par exemple, une chaîne de recherche de test* renvoie tout objet dont la valeur de balise commence par « test ». Une chaîne de recherche composée uniquement d’un caractère générique peut être utilisée pour filtrer les objets selon qu’ils contiennent ou non une balise spécifique, quelle que soit sa valeur.

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}:*

Requête

La requête suivante récupère une liste de jeux de données, filtrée à l’aide d’une balise ayant une valeur spécifique ET d’une deuxième balise présente.

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

Réponse

Une réponse réussie renvoie une liste de jeux de données qui contiennent sampleTag d’une valeur de « 123456 », ET secondTag de n’importe quelle valeur. À moins qu’une limite ne soit également spécifiée, la réponse contient 20 objets maximum.

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

Filtrage par période

Certains points d’entrée de l’API Catalog disposent de paramètres de requête qui permettent les requêtes à intervalles de temps, le plus souvent dans le cas de dates.

Format d’API

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

Requête

La requête suivante récupère une liste de lots créés au cours du mois d’avril 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}'

Réponse

Une réponse réussie contient une liste d’objets Catalog qui se trouvent dans la période spécifiée. À moins qu’une limite ne soit également spécifiée, la réponse contient 20 objets maximum.

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

Tri par propriété

Le paramètre de requête orderBy vous permet de trier (organiser) les données de réponse en fonction d’une valeur de propriété spécifiée. Ce paramètre requiert une « direction » (asc pour un ordre croissant ou desc pour un ordre décroissant), suivie par deux points (:) puis une propriété selon laquelle trier les résultats. Si aucune direction n’est spécifiée, l’ordre par défaut est croissant.

Plusieurs propriétés de tri peuvent être fournies dans une liste aux valeurs séparées par des virgules. Si la première propriété de tri génère plusieurs objets qui contiennent la même valeur pour cette propriété, la deuxième propriété de tri est ensuite utilisée pour trier les objets correspondants.

Prenons pour exemple la requête suivante : orderBy=name,desc:created. Les résultats sont triés par ordre croissant en fonction de la première propriété de tri name. Dans les cas où plusieurs enregistrements partagent la même propriété name, ces enregistrements correspondants sont ensuite triés par la deuxième propriété de tri created. Si aucun enregistrement renvoyé ne partage le même name, la propriété created n’a aucune influence sur le tri.

Format d’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}

Requête

La requête suivante récupère une liste de jeux de données triés par leur propriété name. Si des jeux de données partageaient le même name, ces jeux de données seraient à leur tour classés selon leur propriété updated dans l’ordre décroissant.

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

Réponse

Une réponse réussie contient une liste d’objets Catalog qui sont triés en fonction du paramètre orderBy . À moins qu’une limite ne soit également spécifiée, la réponse contient 20 objets maximum.

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

Filtrage par propriété

Catalog propose deux méthodes de filtrage par propriété, qui sont décrites plus en détail dans les sections suivantes :

Utilisation de filtres simples using-simple-filters

Les filtres simples vous permettent de filtrer les réponses en fonction de valeurs de propriété spécifiques. Un filtre simple prend la forme {PROPERTY_NAME}={VALUE}.

Par exemple, la requête name=exampleName renvoie uniquement les objets dont la propriété name contient une valeur « exampleName ». En revanche, la requête name=!exampleName renvoie uniquement les objets dont la propriété name n’est pas « exampleName ».

En outre, les filtres simples prennent en charge la capacité de formuler des requêtes pour récupérer plusieurs valeurs pour une seule propriété. Lorsque plusieurs valeurs sont fournies, la réponse renvoie des objets dont la propriété correspond à n’importe quelle valeur de la liste fournie. Vous pouvez inverser une requête à plusieurs valeurs en ajoutant un caractère ! en préfixe à la liste, ce qui renverra uniquement les objets dont la valeur de propriété n’est pas dans la liste fournie (par exemple name=!exampleName,anotherName).

Format d’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}

Requête

La requête suivante récupère une liste de jeux de données filtrée pour inclure uniquement les jeux de données dont la propriété name possède une valeur « 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}'

Réponse

Une réponse réussie contient une liste de jeux de données excluant ceux dont le name est « exampleName » ou « anotherName ». À moins qu’une limite ne soit également spécifiée, la réponse contient 20 objets maximum.

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

Utilisation du paramètre property using-the-property-parameter

Le paramètre de requête property offre plus de flexibilité pour le filtrage basé sur les propriétés que les filtres simples. En complément du filtrage selon qu’une propriété possède ou non une valeur spécifique, le paramètre propertypeut utiliser d’autres opérateurs de comparaison (tels que « more-than »,>, et « less-than », <), ainsi que des expressions régulières pour filtrer selon les valeurs de propriété. Il peut également filtrer selon l’existence ou l’absence d’une propriété, quelle que soit sa valeur.

Utilisez une esperluette (&) pour combiner plusieurs filtres et affiner votre requête dans une seule requête. Lorsque vous filtrez par plusieurs champs, une relation de AND est appliquée par défaut.

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

Si vous utilisez plusieurs paramètres de property sur le même champ, seul le dernier paramètre spécifié prend effet.

Le paramètre property peut accepter n'importe quelle propriété d'objet de niveau. sampleKey pouvez être utilisé pour le filtrage à l’aide de ?properties=subItem.sampleKey.

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

Format d’API

GET /{OBJECT_TYPE}?property={CONDITION}

La valeur du paramètre property prend en charge plusieurs types différents d’instructions conditionnelles. Le tableau suivant décrit la syntaxe de base pour les instructions prises en charge :

Requête

La requête suivante renvoie tous les jeux de données dont le numéro de version est supérieur à 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}'

Réponse

Une réponse réussie contient une liste de jeux de données dont les numéros de version sont supérieurs à 1.0.3. Si aucune limite n’est spécifiée, la réponse contient 20 objets maximum.

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

Filtrer des tableaux avec le paramètre de propriété filter-arrays

Utilisez des opérateurs d’égalité et d’inégalité pour inclure ou exclure des valeurs spécifiques lors du filtrage des résultats en fonction des propriétés du tableau.

Filtres d’égalité equality-filters

Pour filtrer un champ de tableau selon plusieurs valeurs, utilisez des paramètres de propriété distincts pour chaque valeur. Utilisez des filtres d’égalité pour renvoyer uniquement les entrées des données du tableau qui correspondent aux valeurs spécifiées.

L’exemple de requête ci-dessous renvoie uniquement les résultats du tableau qui comprend à la fois val1 et val2.

Format d’API

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

Filtres d’inégalité inequality-filters

Utilisez des opérateurs d’inégalité (!=) sur un champ de tableau pour exclure toute entrée dans les données où le tableau contient les valeurs spécifiées.

Format d’API

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

Cette requête renvoie des documents où arrayField ne contient ni val1 ni val2.

Égalité et limites des filtres d’inégalité equality-inequality-limitations

Vous ne pouvez pas appliquer à la fois l’égalité (=) et l’inégalité (!=) au même champ dans une seule requête.