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

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

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

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

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

REMARQUE

Si des libellés existent actuellement pour le jeu de données en question, de nouveaux libellés ne peuvent être ajoutés que par le biais d’une requête de PUT, ce qui nécessite une If-Match en-tête . Une fois que des libellés ont été ajoutés à un jeu de données, le plus récent etag est requise 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 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": []
      } '
Propriété Description
entityId Cela identifie l’entité spécifique au jeu de données à mettre à jour.
entityId.namespace Elle est utilisée pour éviter les collisions d’identifiants. Le namespace is AEP.
entityId.id L’identifiant de la ressource mise à jour. Cela fait référence à la variable datasetId.
entityId.type Type de la ressource mise à jour. Cette variable sera toujours dataset.
labels Liste des libellés d’utilisation des données que vous souhaitez ajouter à l’ensemble du jeu de données.
parents Le parents contient une liste de entityIdde sorte que ce jeu de données hérite des libellés. Les jeux de données peuvent hériter des libellés des schémas et/ou des jeux de données.

Réponse

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

IMPORTANT

Le optionalLabels a été abandonnée pour être utilisée avec les demandes de POST. Il n’est plus possible d’ajouter des libellés de données aux champs du jeu de données. Une opération de POST renvoie une erreur si un optionalLabel est présente. Cependant, vous pouvez supprimer des libellés de champs individuels à l’aide d’une requête de PUT et de la variable optionalLabels . Pour plus d’informations, reportez-vous à la section sur suppression de libellés d’un 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

Vous pouvez supprimer les libellés de champ précédemment appliqués en mettant à jour le optionalLabels des valeurs avec un sous-ensemble des libellés de champ existants ou une liste vide pour les supprimer entièrement. Envoyez une requête de PUT au Dataset Service API permettant de mettre à jour ou de supprimer les libellés précédemment appliqués.

Format d’API

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

Le jeu de données ci-dessous sur lequel l’opération de PUT est appliquée comportait C1 optionalLabel sur les propriétés/person/properties/address field et C1, C2 optionalLabels sur le champ /properties/person/properties/name/properties/fullName . Après l’opération de mise, le premier champ n’aura pas de libellé (étiquette C1 supprimée) et le second champ n’aura qu’une étiquette C1 (étiquette C2 supprimée).

Dans l’exemple de scénario ci-dessous, une requête de PUT est utilisée pour supprimer les libellés ajoutés à des champs individuels. Avant que la demande ne soit effectuée, la variable fullName avait la propriété C1 et C2 les libellés appliqués et la variable address avait déjà un champ C1 libellé appliqué. La requête du PUT remplace les libellés existants C1, C2 des étiquettes fullName avec un champ C1 à l’aide du libellé optionalLabels.labels . La requête remplace également la fonction C1 à partir du libellé address avec un ensemble vide d’étiquettes 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": [],
        "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": []
          }
        ]
      }'
Paramètre Description
entityId Cela identifie l’entité spécifique au jeu de données à mettre à jour. Le entityId doit inclure les trois valeurs suivantes :

namespace: Elle est utilisée pour éviter les collisions d’identifiants. Le namespace is AEP.
id: L’identifiant de la ressource mise à jour. Cela fait référence à la variable datasetId.
type: Type de la ressource mise à jour. Cette variable sera toujours dataset.
labels Liste des libellés d’utilisation des données que vous souhaitez ajouter à l’ensemble du jeu de données.
parents Le parents contient une liste de entityIdde sorte que ce jeu de données hérite des libellés. Les jeux de données peuvent hériter des libellés des schémas et/ou des jeux de données.
optionalLabels Ce paramètre est utilisé pour supprimer les libellés précédemment appliqués à un champ de jeu de données. Liste des champs individuels du jeu de données duquel vous souhaitez supprimer les libellés. 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: Cette valeur doit contenir un sous-ensemble des libellés de champ existants appliqués ou être vide pour supprimer tous les libellés de champ existants. Les méthodes de PUT ou de POST renvoient désormais une erreur si la variable optionalLabels contient des étiquettes nouvelles ou modifiées.

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.

Sur cette page