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

Le Catalog Service L’API permet de filtrer les données de réponse à l’aide de paramètres de requête de requête de requête. Une partie des bonnes pratiques pour Catalog est d’utiliser des filtres dans tous les appels API, car ils réduisent la charge de l’API et contribuent à améliorer les performances globales.

Ce document décrit les méthodes de filtrage les plus courantes Catalog dans l’API. Il vous est recommandé de vous référer à ce document lors de la lecture du guide de développement du catalogue pour en savoir plus sur la manière d’interagir avec l’API Catalog Pour plus d’informations générales sur Catalog Service, reportez-vous à la section Catalog aperçu.

Limiter les objets renvoyés

Le paramètre de requête limit limite le nombre d’objets renvoyés dans une réponse. Catalog les réponses sont automatiquement mesurées selon les limites configurées :

• Si aucun paramètre limit n’est spécifié, le nombre maximal d’objets par payload de réponse est de 20.
• Pour les requêtes des jeux de données, si observableSchema est demandé en utilisant le paramètre de requête properties, le nombre maximal de jeux de données renvoyés est de 20.
• La limite globale pour toutes les autres requêtes de catalogue est de 100 objets.
• Des paramètres limit non valides (y compris limit=0) génèrent des réponses d’erreur de niveau 400 qui indiquent les plages appropriées.
• Les limites ou les décalages transmis en tant que paramètres de requête ont priorité sur ceux transmis en tant qu’en-têtes.

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": "@/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"
    }
}

Limiter les propriétés affichées

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 properties peut accepter n’importe quelle propriété d’objet de niveau. 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 de Catalog avec uniquement 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 :

• Si une ou plusieurs propriétés demandées sont absentes d’un objet, seules les propriétés demandées qu’il inclut seront affichées. (Dataset1)
• Si un objet n’inclut aucune des propriétés demandées, il apparaîtra comme un objet vide. (Dataset2)
• Un jeu de données peut renvoyer une propriété demandée en tant qu’objet vide s’il contient la propriété, mais sans aucune valeur. (Dataset3)
• Sinon, le jeu de données affichera la valeur complète de toutes les propriétés demandées. (Dataset4)

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

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 :

• Les seuls objets Catalog qui prennent actuellement en charge les balises sont les jeux de données, les lots et les connexions.
• Les noms de balise sont propres à votre organisation.
• Les processus Adobe peuvent se servir de balises pour certains comportements. Le préfixe standard « adobe » est ajouté au nom de ces balises. Par conséquent, vous devriez éviter cette pratique lors de la déclaration des noms de balise.
• Les noms de balise suivants sont réservés à l’ensemble de Experience Platform, et ne peuvent donc pas être déclarés comme nom de balise pour votre organisation :
  • unifiedProfile : ce nom de balise est réservé à l’ingestion des jeux de données par Real-Time Customer Profile.
  • unifiedIdentity : ce nom de balise est réservé à l’ingestion des jeux de données par Identity Service.

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 de terminaison dans la variable Catalog Les API possèdent des paramètres de requête qui permettent des requêtes de plage, 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 de Catalog qui se trouvent dans la plage de dates 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 de Catalog les objets triés en fonction des 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é, décrites plus en détail dans les sections suivantes :

• Utilisation de filtres simples : filtrez pour qu’une propriété spécifique corresponde à une valeur spécifique.
• Utilisation du paramètre de propriété : utilisez des expressions conditionnelles pour un filtre se basant sur l’existence ou non d’une propriété ou sur la correspondance, la ressemblance ou la possibilité de comparer ou non la valeur d’une propriété à une autre valeur spécifiée ou à une expression régulière.

Utilisation de filtres simples

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

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.

Le property peut accepter n’importe quelle propriété d’objet de niveau. sampleKey peut ê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}",
    }
}

Combinaison de plusieurs filtres

A l’aide d’une esperluette (&), vous pouvez combiner plusieurs filtres dans une même requête. Lorsque des conditions supplémentaires sont ajoutées à une requête, une relation ET est présumée.

Format d’API

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

Ressources Business.Adobe.com

Multivariate Testing Personalized Experiences Audio Analytics Anomaly Detection Attribution Programmatic Advertising