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.
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.
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. |
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.
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 entityId de 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.
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"
}
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 entityId de 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 :option objet contenant les attributs Experience Data Model (XDM) du champ. Les trois propriétés suivantes sont requises :
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"
}
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.