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 Experience 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 look-up

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

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: {ORG_ID}' \
  -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": "{ORG_ID}",
    "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" ]
      }
    ]
  }
}

Appliquer des libellés à un jeu de données apply

Vous pouvez appliquer un ensemble de libellés pour un jeu de données entier en les fournissant dans la payload dʼune requête POST ou PUT à lʼAPI Dataset Service. Le corps de la requête est le même pour les deux appels. Vous ne pouvez pas ajouter de libellés à des champs de jeu de données individuels.

Format d’API

POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

Requête

L’exemple de requête POST ci-dessous met à jour l’ensemble du jeu de données avec un libellé C1. Les champs fournis dans la payload sont identiques à ceux requis pour une requête PUT.

Lors dʼappels API mettant à jour les libellés existants dʼun jeu de données (PUT), un en-tête If-Match indiquant la version actuelle de lʼentité libellé-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.

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 de libellés de jeux de données existants, il est recommandé dʼeffectuer dʼabord une requête 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 ultérieure.

curl -X POST \
  '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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
        "entityId": {
          "namespace": "AEP",
          "id": "test-ds-id",
          "type": "dataset"
        },
        "labels": [
          "C1"
        ],
        "parents": []
      } '

Réponse

Une réponse réussie renvoie le jeu de libellés mis à jour pour le jeu de données.

{
  "parents": [
      {
        "id": "_ddgduleint.schemas.4a95cdba7d560e3bca7d8c5c7b58f00ca543e2bb1e4137d6",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-201",
  "message": "POST Successful"
}

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

Pour supprimer des libellés du champ précédemment appliqués, mettez à jour la ou les valeurs optionalLabels existantes avec un sous-ensemble des libellés du champ existants ou une liste vide pour les supprimer entièrement. Envoyez une requête PUT à l’API Dataset Service pour mettre à jour ou supprimer les libellés précédemment appliqués.

Format d’API

PUT /datasets/{DATASET_ID}/labels

Requête

Dans le jeu de données ci-dessous sur lequel l’opération PUT est appliquée, le paramètre optionalLabel possède la valeur C1 dans le champ propriétés/personne/propriétés/addresse et le paramètre optionalLabels possède les valeurs C1 et C2 dans le champ /propriétés/personne/propriétés/nom/propriétés/NomComplet. Suite à l’opération PUT, le premier champ n’a pas de libellé (le libellé C1 a été supprimé) et le second champ n’a qu’un libellé C1 (le libellé C2 a été supprimé).

Dans l’exemple de scénario ci-dessous, une requête PUT est envoyée pour supprimer les libellés ajoutés à des champs individuels. Avant que la demande ne soit effectuée, le champ fullName disposait des libellés C1 et C2 et le champ address possédait déjà un libellé C1. La requête PUT remplace les libellés C1, C2 existants du champ fullName par un libellé C1 à l’aide du paramètre optionalLabels.labels. La requête remplace également le libellé C1 du champ address par un ensemble vide de libellés de champ.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -d '{
        "entityId": {
          "namespace": "AEP",
          "id": "646b814d52e1691c07b41032",
          "type": "dataset"
        },
        "labels": [
          "C1"
        ],
        "parents": [
          {
            "id": "_xdm.context.identity-graph-flattened-export",
            "type": "schema",
            "namespace": "AEP"
          }
        ],
        "optionalLabels": [
          {
            "option": {
              "id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/person/properties/name/properties/fullName"
            },
            "labels": [
              "C1"
            ]
          },
          {
            "option": {
              "id": "https://ns.adobe.com/xdm/context/identity-graph-flattened-export",
              "contentType": "application/vnd.adobe.xed-full+json;version=1",
              "schemaPath": "/properties/person/properties/address"
            },
            "labels": []
          }
        ]
      }'

Réponse

Une réponse réussie renvoie le jeu de libellés mis à jour pour le jeu de données.

{
  "parents": [
      {
        "id": "_xdm.context.identity-graph-flattened-export",
        "type": "schema",
        "namespace": "AEP"
      }
  ],
  "optionalLabels": [],
  "labels": [
      "C1"
  ],
  "code": "PES-200",
  "message": "PUT Successful"
}

Étapes suivantes

En lisant ce document, vous avez appris la gestion des libellés dʼutilisation des données pour les jeux de données et les champs à lʼaide de lʼAPI Dataset Service. Vous pouvez maintenant définir les politiques d’utilisation des données et les politiques de contrôle d’accès selon les libellés que vous avez appliqués.

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