Show Menu
ARGOMENTI×

Gestione delle etichette di utilizzo dei dati per i set di dati tramite API

L'API Dataset Service API consente di applicare e modificare le etichette di utilizzo per i set di dati. Fa parte delle funzionalità dei cataloghi di dati di Adobe Experience Platform, ma è separata dall' Catalog Service API che gestisce i metadati dei set di dati.
Questo documento descrive come gestire le etichette per set di dati e campi utilizzando l' Dataset Service API. Per i passaggi su come gestire direttamente le etichette di utilizzo dei dati utilizzando le chiamate API, consultate la guida dell'endpoint delle etichette per l' Policy Service API.

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 endpoint descritti in questo documento, è necessario disporre del id valore univoco 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.

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 PUT aggiorna le etichette esistenti per un set di dati, nonché un campo specifico all'interno di tale set di dati. I campi forniti nel payload sono gli stessi richiesti per una richiesta di POST.
È necessario fornire un' If-Match intestazione valida quando si effettuano richieste di PUT all' /datasets/{DATASET_ID}/labels endpoint. Per ulteriori informazioni sull’utilizzo dell’intestazione richiesta, consultate la sezione If-Match header appendice.
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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000' \
  -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
La seguente richiesta rimuove le etichette per il set di dati specificato nel percorso.
È necessario fornire un' If-Match intestazione valida quando si effettuano richieste di DELETE all' /datasets/{DATASET_ID}/labels endpoint. Per ulteriori informazioni sull’utilizzo dell’intestazione richiesta, consultate la sezione If-Match header appendice.
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}' \
  -H 'If-Match: 8f00d38e-0000-0200-0000-5ef4fc6d0000'

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 per set di dati e campi utilizzando l' Dataset Service 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.

Appendice

La sezione seguente contiene informazioni aggiuntive sull'utilizzo delle etichette tramite l'API del servizio DataSet.

If-Match header

Quando si effettuano chiamate API che aggiornano le etichette esistenti di un dataset (PUT e DELETE), è necessario includere un' If-Match intestazione che indichi la versione corrente dell'entità dell'etichetta del set di dati in Servizio DataSet. Per evitare conflitti di dati, il servizio aggiornerà l'entità dataset solo se la If-Match stringa inclusa corrisponde al tag versione più recente generato dal sistema per quel dataset.
Se al momento non esistono etichette per il set di dati in questione, è possibile aggiungere nuove etichette solo tramite una richiesta di POST, che non richiede un' If-Match intestazione. Una volta aggiunte le etichette a un set di dati, viene assegnato un etag valore che può essere utilizzato per aggiornare o rimuovere le etichette in un secondo momento.
Per recuperare la versione più recente dell'entità dataset-label, effettuate una richiesta di GET all' /datasets/{DATASET_ID}/labels endpoint. Il valore corrente viene restituito nella risposta sotto un' etag intestazione. Quando si aggiornano le etichette del set di dati esistenti, si consiglia di eseguire prima una richiesta di ricerca per il set di dati, in modo da recuperare il etag valore più recente prima di utilizzare tale valore nell' If-Match intestazione della richiesta PUT o DELETE successiva.