Show Menu
ARGOMENTI×

Gestione delle etichette di utilizzo dei dati tramite API

In questo documento sono descritti i passaggi necessari per gestire le etichette di utilizzo dei dati utilizzando l' Policy Service API e l' Dataset Service API.
Sono Policy Service API disponibili diversi endpoint che consentono di creare e gestire le etichette di utilizzo dei dati per la propria organizzazione.
L' Dataset Service API consente di applicare e modificare le etichette di utilizzo per i set di dati. Fa parte funzionalità catalogo dati, ma è separata dall' Catalog Service API che gestisce i metadati del set di dati.

Introduzione

Prima di leggere questa guida, segui i passaggi descritti nella sezione Catalog Service guida per sviluppatori introduttiva della guida per gli sviluppatori del catalogo per raccogliere le credenziali necessarie per effettuare chiamate alle Platform API.
Per effettuare chiamate agli Dataset Service endpoint descritti in questo documento, è necessario disporre del valore univoco id per un set di dati specifico. Se non hai questo valore, consulta la guida sull’ elenco degli oggetti catalogo per trovare gli ID dei set di dati esistenti.

Elenca tutte le etichette

Utilizzando l' Policy Service API, potete elencare tutte core o custom le etichette effettuando una richiesta di GET a /labels/core o, rispettivamente, /labels/custom .
Formato API
GET /labels/core
GET /labels/custom

Richiesta
Nella richiesta seguente sono elencate tutte le etichette personalizzate create all'interno dell'organizzazione.
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}'

Risposta
Una risposta corretta restituisce un elenco di etichette personalizzate recuperate dal sistema. Poiché la richiesta di esempio sopra è stata inoltrata a /labels/custom , la risposta riportata di seguito mostra solo le etichette personalizzate.
{
    "_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"
                }
            }
        }
    ]
}

Cercare un'etichetta

Potete cercare un'etichetta specifica includendo la name proprietà dell'etichetta nel percorso di una richiesta di GET all' Policy Service API.
Formato API
GET /labels/core/{LABEL_NAME}
GET /labels/custom/{LABEL_NAME}

Parametro
Descrizione
{LABEL_NAME}
La name proprietà dell'etichetta personalizzata che si desidera cercare.
Richiesta
La richiesta seguente recupera l'etichetta personalizzata L2 , come indicato nel percorso.
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}'

Risposta
Una risposta corretta restituisce i dettagli dell'etichetta personalizzata.
{
    "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"
        }
    }
}

Creare o aggiornare un'etichetta personalizzata

Per creare o aggiornare un'etichetta personalizzata, dovete effettuare una richiesta di PUT all' Policy Service API.
Formato API
PUT /labels/custom/{LABEL_NAME}

Parametro
Descrizione
{LABEL_NAME}
La name proprietà di un'etichetta personalizzata. Se non esiste un'etichetta personalizzata con questo nome, verrà creata una nuova etichetta. Se ne esiste uno, l'etichetta verrà aggiornata.
Richiesta
La seguente richiesta crea una nuova etichetta L3 , che ha lo scopo di descrivere i dati che contengono informazioni relative ai piani di pagamento selezionati dai clienti.
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."
      }'

Proprietà
Descrizione
name
Identificatore stringa univoco per l'etichetta. Questo valore viene utilizzato a scopo di ricerca e l'etichetta viene applicata a set di dati e campi, pertanto si consiglia di utilizzarlo in modo breve e conciso.
category
La categoria dell'etichetta. Sebbene sia possibile creare categorie personalizzate per le etichette personalizzate, è comunque consigliabile utilizzarle Custom se si desidera che l'etichetta venga visualizzata nell'interfaccia utente.
friendlyName
Un nome descrittivo per l'etichetta, utilizzato a scopo di visualizzazione.
description
(Facoltativo) Una descrizione dell'etichetta per fornire ulteriore contesto.
Risposta
Una risposta corretta restituisce i dettagli dell'etichetta personalizzata, con codice HTTP 200 (OK) se un'etichetta esistente è stata aggiornata, oppure 201 (Creato) se è stata creata una nuova etichetta.
{
  "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"
    }
  }
}

Cerca etichette per un set di dati

Potete cercare le etichette di utilizzo dei dati applicate a un dataset esistente effettuando una richiesta di GET all' Dataset Service API.
Formato API
GET /datasets/{DATASET_ID}/labels

Parametro
Descrizione
{DATASET_ID}
Il id valore univoco del set di dati di cui si desidera cercare le etichette.
Richiesta
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}'

Risposta
Una risposta corretta restituisce le etichette di utilizzo dei dati applicate al set di dati.
{
  "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" ]
      }
    ]
  }
}

Proprietà
Descrizione
labels
Elenco di etichette di utilizzo dati applicate al set di dati.
optionalLabels
Elenco di singoli campi all’interno del dataset a cui sono applicate etichette di utilizzo dei dati.

Applicare etichette a un dataset

Potete creare un set di etichette per un set di dati inserendole nel payload di una richiesta di POST o PUT all' Dataset Service API. L’utilizzo di uno di questi metodi sovrascrive tutte le etichette esistenti e le sostituisce con quelle fornite nel payload.
Formato API
POST /datasets/{DATASET_ID}/labels
PUT /datasets/{DATASET_ID}/labels

Parametro
Descrizione
{DATASET_ID}
Il id valore univoco del set di dati per il quale si creano le etichette.
Richiesta
La seguente richiesta di POST aggiunge una serie di etichette al set di dati, oltre a un campo specifico all'interno del set di dati. I campi forniti nel payload sono gli stessi richiesti per una richiesta di 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" ]
          }
        ]
      }'

Proprietà
Descrizione
labels
Elenco di etichette di utilizzo dati da aggiungere al dataset.
optionalLabels
Un elenco di tutti i singoli campi all'interno del set di dati a cui si desidera aggiungere etichette. Ogni elemento di questa matrice deve avere le seguenti proprietà:
option : Un oggetto che contiene gli attributi Experience Data Model (XDM) del campo. Sono richieste le tre proprietà seguenti:
  • id: Il valore URI $id dello schema associato al campo.
  • contentType: Il tipo di contenuto e il numero di versione dello schema. Questo deve assumere la forma di una delle intestazioni Cercare una risorsa Accetta valide per una richiesta di ricerca XDM.
  • schemaPath: Percorso del campo all'interno dello schema del set di dati.
labels : Elenco di etichette di utilizzo dati da aggiungere al campo.
Risposta
Una risposta corretta restituisce le etichette aggiunte al set di dati.
{
  "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" ]
    }
  ]
}

Rimozione di etichette da un dataset

Potete rimuovere le etichette applicate a un dataset effettuando una richiesta di DELETE all' Dataset Service API.
Formato API
DELETE /datasets/{DATASET_ID}/labels

Parametro
Descrizione
{DATASET_ID}
Il id valore univoco del set di dati di cui si desidera rimuovere le etichette.
Richiesta
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}'

Risposta
Risposta corretta: stato HTTP 200 (OK), a indicare che le etichette sono state rimosse. Potete cercare le etichette esistenti per il set di dati in una chiamata separata per confermarlo.

Passaggi successivi

Leggendo questo documento, hai imparato a gestire le etichette di utilizzo dei dati utilizzando le API.
Dopo aver aggiunto le etichette di utilizzo dei dati a livello di set di dati e di campo, è possibile iniziare a assimilare i dati in Experience Platform. Per saperne di più, leggi la documentazione sull’inserimento dei dati.
È inoltre possibile definire criteri di utilizzo dei dati in base alle etichette applicate. Per ulteriori informazioni, vedere la panoramica dei criteri di utilizzo dei dati.
Per ulteriori informazioni sulla gestione dei set di dati in Experience Platform, vedere la panoramica dei set di dati.