Show Menu
SUJETS×

Gérer les étiquettes d’utilisation des données à l’aide d’API

Ce document décrit la procédure à suivre pour gérer les étiquettes d’utilisation des données à l’aide de l’ Policy Service API et de l’ Dataset Service API.
Le Policy Service API fournit plusieurs points de terminaison qui vous permettent de créer et de gérer des étiquettes d’utilisation des données pour votre entreprise.
L’ Dataset Service API vous permet d’appliquer et de modifier des étiquettes d’utilisation pour les jeux de données. Il fait partie des fonctionnalités de catalogue de données d’Adobe Experience Platform, mais est distinct de l’ Catalog Service API qui gère les métadonnées des jeux de données.

Prise en main

Avant de lire ce guide, suivez les étapes décrites dans la section Catalog Service guide du développeur Prise en main du guide du développeur de catalogue afin de rassembler les informations d’identification requises pour appeler Platform les API.
Pour effectuer des appels vers les Dataset Service points de terminaison décrits dans ce document, vous devez disposer de la valeur unique id pour un jeu de données spécifique. Si vous ne disposez pas de cette valeur, consultez le guide de la liste des objets Catalog pour trouver les ID de vos jeux de données existants.

Liste de toutes les étiquettes

A l’aide de l’ Policy Service API, vous pouvez liste toutes les core étiquettes ou custom les étiquettes en faisant une demande GET à /labels/core ou /labels/custom , respectivement.
Format d’API
GET /labels/core
GET /labels/custom

Requête
La requête suivante liste tous les libellés personnalisés créés dans votre organisation.
curl -X GET \
  'https://platform.adobe.io/data/foundation/dulepolicy/labels/custom' \
  -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 une liste d'étiquettes personnalisées récupérées du système. L’exemple de demande ci-dessus ayant été envoyé à /labels/custom , la réponse ci-dessous affiche uniquement les étiquettes personnalisées.
{
    "_page": {
        "count": 2
    },
    "_links": {
        "page": {
            "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/labels/custom?{?limit,start,property}",
            "templated": true
        }
    },
    "children": [
        {
            "name": "L1",
            "category": "Custom",
            "friendlyName": "Banking Information",
            "description": "Data containing banking information for a customer.",
            "imsOrg": "{IMS_ORG}",
            "sandboxName": "{SANDBOX_NAME}",
            "created": 1594396718731,
            "createdClient": "{CLIENT_ID}",
            "createdUser": "{USER_ID}",
            "updated": 1594396718731,
            "updatedClient": "{CLIENT_ID}",
            "updatedUser": "{USER_ID}",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/labels/custom/L1"
                }
            }
        },
        {
            "name": "L2",
            "category": "Custom",
            "friendlyName": "Purchase History Data",
            "description": "Data containing information on past transactions",
            "imsOrg": "{IMS_ORG}",
            "sandboxName": "{SANDBOX_NAME}",
            "created": 1594397415663,
            "createdClient": "{CLIENT_ID}",
            "createdUser": "{USER_ID}",
            "updated": 1594397728708,
            "updatedClient": "{CLIENT_ID}",
            "updatedUser": "{USER_ID}",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/labels/custom/L2"
                }
            }
        }
    ]
}

Rechercher une étiquette

Vous pouvez rechercher une étiquette spécifique en incluant la name propriété de cette étiquette dans le chemin d’une requête GET à l’ Policy Service API.
Format d’API
GET /labels/core/{LABEL_NAME}
GET /labels/custom/{LABEL_NAME}

Paramètre
Description
{LABEL_NAME}
The name property of the custom label you want to look up.
Requête
La requête suivante récupère le libellé personnalisé L2 , comme indiqué dans le chemin d’accès.
curl -X GET \
  'https://platform.adobe.io/data/foundation/dulepolicy/labels/custom/L2' \
  -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 détails de l’étiquette personnalisée.
{
    "name": "L2",
    "category": "Custom",
    "friendlyName": "Purchase History Data",
    "description": "Data containing information on past transactions",
    "imsOrg": "{IMS_ORG}",
    "sandboxName": "{SANDBOX_NAME}",
    "created": 1594397415663,
    "createdClient": "{CLIENT_ID}",
    "createdUser": "{USER_ID}",
    "updated": 1594397728708,
    "updatedClient": "{CLIENT_ID}",
    "updatedUser": "{USER_ID}",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/labels/custom/L2"
        }
    }
}

Création ou mise à jour d’une étiquette personnalisée

Pour créer ou mettre à jour une étiquette personnalisée, vous devez envoyer une requête PUT à l’ Policy Service API.
Format d’API
PUT /labels/custom/{LABEL_NAME}

Paramètre
Description
{LABEL_NAME}
Propriété name d’une étiquette personnalisée. Si aucune étiquette personnalisée portant ce nom n’existe, une nouvelle étiquette est créée. S'il en existe un, cette étiquette sera mise à jour.
Requête
La demande suivante crée une nouvelle étiquette L3 , qui vise à décrire des données contenant des informations relatives aux plans de paiement sélectionnés par les clients.
curl -X PUT \
  'https://platform.adobe.io/data/foundation/dulepolicy/labels/custom/L3' \
  -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}' \
  -d '{
        "name": "L3",
        "category": "Custom",
        "friendlyName": "Payment Plan",
        "description": "Data containing information on selected payment plans."
      }'

Propriété
Description
name
Identifiant de chaîne unique pour l’étiquette. Cette valeur est utilisée à des fins de recherche et d’application de l’étiquette aux jeux de données et aux champs. Il est donc recommandé qu’elle soit courte et concise.
category
catégorie de l'étiquette. Bien que vous puissiez créer vos propres catégories pour les étiquettes personnalisées, il est vivement recommandé de les utiliser Custom si vous souhaitez qu’elles apparaissent dans l’interface utilisateur.
friendlyName
Nom convivial de l’étiquette, utilisé à des fins d’affichage.
description
(Facultatif) Description de l’étiquette afin de fournir un contexte plus poussé.
Réponse
Une réponse réussie renvoie les détails d'une étiquette personnalisée, avec le code HTTP 200 (OK) si une étiquette existante a été mise à jour, ou 201 (Créée) si une nouvelle étiquette a été créée.
{
  "name": "L3",
  "category": "Custom",
  "friendlyName": "Payment Plan",
  "description": "Data containing information on selected payment plans.",
  "imsOrg": "{IMS_ORG}",
  "sandboxName": "{SANDBOX_NAME}",
  "created": 1529696681413,
  "createdClient": "{CLIENT_ID}",
  "createdUser": "{USER_ID}",
  "updated": 1529697651972,
  "updatedClient": "{CLIENT_ID}",
  "updatedUser": "{USER_ID}",
  "_links": {
    "self": {
      "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/labels/custom/L3"
    }
  }
}

Rechercher des é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 adressant une requête GET à l’ Dataset Service API.
Format d’API
GET /datasets/{DATASET_ID}/labels

Paramètre
Description
{DATASET_ID}
Valeur unique id 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 positive 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 des é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 des étiquettes d’utilisation de données sont appliquées.

Appliquer des étiquettes à un jeu de données

Vous pouvez créer un ensemble de libellés pour un jeu de données en les fournissant dans la charge utile d’une requête POST ou PUT à l’ Dataset Service API. L’utilisation de l’une ou l’autre de ces méthodes remplace les étiquettes existantes et les remplace par celles fournies dans la charge utile.
Format d’API
POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

Paramètre
Description
{DATASET_ID}
Valeur unique id du jeu de données pour lequel vous créez des étiquettes.
Requête
La demande POST suivante ajoute une série d’étiquettes au jeu de données, ainsi qu’un champ spécifique dans ce jeu de données. Les champs fournis dans la charge utile sont identiques à ceux requis pour une demande de test de performances (PUT).
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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -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 du jeu de données auxquels vous souhaitez ajouter des étiquettes. Chaque élément de ce tableau doit avoir les propriétés suivantes :
option : Objet 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. Cette opération doit prendre la forme d’un des en-têtes Recherche d’une ressource Accepter 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 d’étiquettes d’un jeu de données

Vous pouvez supprimer les étiquettes appliquées à un jeu de données en adressant une requête de DELETE à l’ Dataset Service API.
Format d’API
DELETE /datasets/{DATASET_ID}/labels

Paramètre
Description
{DATASET_ID}
Valeur unique id du jeu de données dont vous souhaitez supprimer les étiquettes.
Requête
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}'

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 distinct pour le confirmer.

Étapes suivantes

En lisant ce document, vous avez appris à gérer les étiquettes d’utilisation des données à l’aide d’API.
Once you have added data usage labels at the dataset- and field-level, you can begin to ingest data into 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 l'aperçu des jeux de données.