Gestion des étiquettes dʼutilisation des données pour les jeux de données à lʼaide dʼAPI

Dataset Service API vous permet dʼappliquer et de modifier des étiquettes dʼutilisation pour les jeux de données. LʼAPI fait partie des fonctionnalités de catalogue de données dʼAdobe Experience Platform, mais est distinct de lʼAPI Catalog Service qui gère les métadonnées du jeu de données.

Ce document explique la gestion des étiquettes pour les jeux de données et les champs à lʼaide de Dataset Service API. Pour obtenir des instructions sur la gestion des étiquettes dʼutilisation des données elles-mêmes à lʼaide dʼappels API, consultez le guide de point d’entrée des étiquettes pour Policy Service API.

Prise en main

Avant de lire ce guide, suivez les étapes décrites dans la section Prise en main du guide de développement de Catalogue pour rassembler les informations dʼidentification nécessaires afin de réaliser des appels aux API de Platform.

Pour réaliser des appels vers les points d’entrée décrits dans ce document, vous devez disposer de la valeur id unique pour un jeu de données spécifique. Si vous ne possédez pas cette valeur, consultez le guide qui répertorie les objets de Catalogue afin de trouver les identifiants de vos jeux de données existants.

Recherche dʼétiquettes pour un jeu de données

Vous pouvez rechercher les étiquettes dʼutilisation des données qui ont été appliquées à un jeu de données existant en envoyant une requête GET à lʼAPI Dataset Service.

Format d’API

GET /datasets/{DATASET_ID}/labels
Paramètre Description
{DATASET_ID} Valeur id unique du jeu de données dont vous souhaitez rechercher les étiquettes.

Requête

curl -X GET \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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}'

Réponse

Une réponse réussie renvoie les étiquettes dʼutilisation des données qui ont été appliquées au jeu de données.

{
  "AEP:dataset:5abd49645591445e1ba04f87": {
    "imsOrg": "{IMS_ORG}",
    "labels": [ "C1", "C2", "C3", "I1", "I2" ],
    "optionalLabels": [
      {
        "option": {
          "id": "https://ns.adobe.com/{TENANT_ID}/schemas/c6b1b09bc3f2ad2627c1ecc719826836",
          "contentType": "application/vnd.adobe.xed-full+json;version=1",
          "schemaPath": "/properties/repositoryCreatedBy"
        },
        "labels": [ "S1", "S2" ]
      }
    ]
  }
}
Propriété Description
labels Liste dʼétiquettes dʼutilisation des données qui ont été appliquées au jeu de données.
optionalLabels Liste de champs individuels au sein du jeu de données auxquels sont appliquées des étiquettes dʼutilisation de données.

Application dʼétiquettes à un jeu de données

Vous pouvez créer un ensemble dʼétiquettes pour un jeu de données en les fournissant dans la payload dʼune requête POST ou PUT à lʼAPI Dataset Service. Lʼutilisation de lʼune ou lʼautre de ces méthodes supprime les étiquettes existantes et les remplace par celles fournies dans la payload.

Format d’API

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels
Paramètre Description
{DATASET_ID} Valeur id unique du jeu de données pour lequel vous créez des étiquettes.

Requête

La requête PUT suivante met à jour les étiquettes existantes pour un jeu de données, ainsi quʼun champ spécifique dans ce jeu de données. Les champs fournis dans la payload sont identiques à ceux requis pour une requête POST.

IMPORTANT

Un en-tête If-Match valide doit être fourni lors de lʼexécution de requêtes PUT au point d’entrée /datasets/{DATASET_ID}/labels. Pour plus dʼinformations sur lʼutilisation de lʼen-tête requis, consultez la section Annexe.

curl -X PUT \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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}' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -d '{
        "labels": [ "C1", "C2", "C3", "I1", "I2" ],
        "optionalLabels": [
          {
            "option": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/c6b1b09bc3f2ad2627c1ecc719826836",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/repositoryCreatedBy"
            },
            "labels": [ "S1", "S2" ]
          }
        ]
      }'
Propriété Description
labels Liste dʼétiquettes dʼutilisation des données que vous souhaitez ajouter au jeu de données.
optionalLabels Liste de tous les champs individuels dans le jeu de données auxquels vous souhaitez ajouter des étiquettes. Chaque élément de ce tableau doit avoir les propriétés suivantes :

optionobjet contenant les attributs Experience Data Model (XDM) du champ. Les trois propriétés suivantes sont requises :
  • id: valeur URI $id du schéma associé au champ.
  • contentType: type de contenu et numéro de version du schéma. Cela doit prendre la forme dʼun des en-têtes « Accept » valides pour une demande de recherche XDM.
  • schemaPath: chemin dʼaccès au champ dans le schéma du jeu de données.
labels : liste dʼétiquettes dʼutilisation des données que vous souhaitez ajouter au champ.

Réponse

Une réponse réussie renvoie les étiquettes qui ont été ajoutées au jeu de données.

{
  "labels": [ "C1", "C2", "C3", "I1", "I2" ],
  "optionalLabels": [
    {
      "option": {
        "id": "https://ns.adobe.com/{TENANT_ID}/schemas/c6b1b09bc3f2ad2627c1ecc719826836",
        "contentType": "application/vnd.adobe.xed-full+json;version=1",
        "schemaPath": "/properties/repositoryCreatedBy"
      },
      "labels": [ "S1", "S2" ]
    }
  ]
}

Suppression des étiquettes dʼun jeu de données

Vous pouvez supprimer les étiquettes appliquées à un jeu de données en envoyant une requête DELETE à lʼAPI Dataset Service.

Format d’API

DELETE /datasets/{DATASET_ID}/labels
Paramètre Description
{DATASET_ID} Valeur id unique du jeu de données dont vous souhaitez supprimer les étiquettes.

Requête

La requête suivante supprime les étiquettes pour le jeu de données spécifié dans le chemin dʼaccès.

IMPORTANT

Un en-tête If-Match valide doit être fourni lors de lʼexécution de requêtes DELETE au point d’entrée /datasets/{DATASET_ID}/labels. Pour plus dʼinformations sur lʼutilisation de lʼen-tête requis, consultez la section Annexe.

curl -X DELETE \
  'https://platform.adobe.io/data/foundation/dataset/datasets/5abd49645591445e1ba04f87/labels' \
  -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}' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000'

Réponse

Réponse réussie état HTTP 200 (OK), indiquant que les étiquettes ont été supprimées. Vous pouvez rechercher les étiquettes existantes pour le jeu de données dans un appel séparé pour confirmer cela.

Étapes suivantes

En lisant ce document, vous avez appris la gestion des étiquettes dʼutilisation des données pour les jeux de données et les champs à lʼaide de lʼAPI Dataset Service.

Une fois que vous avez ajouté des étiquettes dʼutilisation des données au niveau du jeu de données et du champ, vous pouvez commencer à ingérer des données dans Experience Platform. Pour en savoir plus, commencez par lire la documentation sur l’ingestion de données.

Désormais, vous pouvez également définir des stratégies d’utilisation des données en fonction des libellés que vous avez appliqués. Pour plus d’informations, consultez la présentation des stratégies d’utilisation des données.

Pour plus dʼinformations sur la gestion des jeux de données dans Experience Platform, consultez la présentation des jeux de données.

Annexe

La section suivante contient des informations supplémentaires sur lʼutilisation des étiquettes à lʼaide de lʼAPI Dataset Service.

En-tête If-Match

Lors dʼappels API mettant à jour les étiquettes existantes dʼun jeu de données (PUT et DELETE), un en-tête If-Match indiquant la version actuelle de lʼentité étiquette-jeu de données dans Dataset Service doit être inclus. Afin dʼéviter les collisions de données, le service ne mettra à jour lʼentité jeu de données que si la chaîne If-Match incluse correspond à la dernière balise de version générée par le système pour ce jeu de données.

REMARQUE

Si aucune étiquette nʼexiste actuellement pour le jeu de données en question, de nouvelles étiquettes ne peuvent être ajoutées que par le biais dʼune requête POST, qui ne nécessite pas un en-tête If-Match. Une fois que des étiquettes ont été ajoutées à un jeu de données, une valeur etag est attribuée qui peut être utilisée pour mettre à jour ou supprimer les étiquettes ultérieurement.

Pour récupérer la version la plus récente de lʼentité étiquette-jeu de données, envoyez une requête GET au point d’entrée /datasets/{DATASET_ID}/labels. La valeur actuelle est renvoyée dans la réponse sous un en-tête etag. Lors de la mise à jour dʼétiquettes de jeux de données existants, il est recommandé dʼeffectuer dʼabord une demande de recherche pour le jeu de données afin de récupérer sa valeur etag la plus récente avant dʼutiliser cette valeur dans lʼen-tête If-Match de votre requête PUT ou DELETE ultérieure.

Sur cette page