Gestire le etichette di utilizzo dei dati per i set di dati tramite API

Il Dataset Service API ti consente di applicare e modificare le etichette di utilizzo per i set di dati. Fa parte delle funzionalità del catalogo dati di Adobe Experience Platform, ma è separato dall’ Catalog Service API che gestisce i metadati del set di dati.

Questo documento illustra come gestire le etichette per i set di dati e i campi utilizzando Dataset Service API. Per i passaggi su come gestire direttamente le etichette di utilizzo dei dati utilizzando le chiamate API, consulta la guida all'endpoint delle etichette per il tag Policy Service API.

Introduzione

Prima di leggere questa guida, segui i passaggi descritti nella sezione guida introduttiva nella guida per gli sviluppatori del catalogo per raccogliere le credenziali necessarie per effettuare chiamate alle API Platform .

Per effettuare chiamate agli endpoint descritti in questo documento, è necessario disporre del valore univoco id per un set di dati specifico. Se non disponi di questo valore, consulta la guida in elenco degli oggetti del catalogo per trovare gli ID dei set di dati esistenti.

Cercare etichette per un set di dati

Puoi cercare le etichette di utilizzo dei dati applicate a un set di dati esistente effettuando una richiesta di GET all’ Dataset Service API.

Formato API

GET /datasets/{DATASET_ID}/labels
Parametro Descrizione
{DATASET_ID} Valore univoco id 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 dei dati applicate al set di dati.
optionalLabels Elenco di singoli campi all’interno del set di dati a cui sono applicate etichette di utilizzo dei dati.

Applicare etichette a un set di dati

Puoi creare un set di etichette per un set di dati fornendo loro nel payload di una richiesta di POST o PUT all’ API Dataset Service . L’utilizzo di uno di questi metodi sovrascrive 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} Valore id univoco del set di dati per cui si stanno creando 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 POST.

IMPORTANTE

Quando si effettuano richieste PUT all’endpoint /datasets/{DATASET_ID}/labels è necessario fornire un’intestazione If-Match valida. Per ulteriori informazioni sull'utilizzo dell'intestazione richiesta, vedere la sezione 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 dei dati da aggiungere al set di dati.
optionalLabels Elenco di tutti i singoli campi all’interno del set di dati a cui si desidera aggiungere le etichette. Ogni elemento della matrice deve avere le seguenti proprietà:

option: Oggetto che contiene gli attributi Experience Data Model (XDM) del campo. Sono richieste le tre proprietà seguenti:
  • id: 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 Accetta intestazioni valide per una richiesta di ricerca XDM.
  • schemaPath: Percorso del campo nello 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" ]
    }
  ]
}

Rimuovere le etichette da un set di dati

Puoi rimuovere le etichette applicate a un set di dati effettuando una richiesta DELETE all’ API Dataset Service .

Formato API

DELETE /datasets/{DATASET_ID}/labels
Parametro Descrizione
{DATASET_ID} Valore univoco id 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.

IMPORTANTE

Quando si effettuano richieste DELETE all’endpoint /datasets/{DATASET_ID}/labels è necessario fornire un’intestazione If-Match valida. Per ulteriori informazioni sull'utilizzo dell'intestazione richiesta, vedere la sezione 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

Una risposta corretta, stato HTTP 200 (OK), che indica che le etichette sono state rimosse. Puoi 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 i set di dati e i campi utilizzando l’API Dataset Service.

Dopo aver aggiunto le etichette di utilizzo dei dati a livello di set di dati e di campo, puoi iniziare a inserire i dati in Experience Platform. Per ulteriori informazioni, inizia leggendo la documentazione sull'acquisizione dei dati.

È inoltre possibile definire criteri di utilizzo dei dati in base alle etichette applicate. Per ulteriori informazioni, consulta la panoramica dei criteri di utilizzo dei dati.

Per ulteriori informazioni sulla gestione dei set di dati in Experience Platform, consulta la panoramica dei set di dati.

Appendice

La sezione seguente contiene informazioni aggiuntive sull’utilizzo delle etichette tramite l’API Servizio set di dati.

If-Match header

Quando si eseguono chiamate API che aggiornano le etichette esistenti di un set di dati (PUT e DELETE), deve essere inclusa un’intestazione If-Match che indica la versione corrente dell’entità etichetta di set di dati nel servizio set di dati. Per evitare conflitti tra dati, il servizio aggiorna l’entità set di dati solo se la stringa inclusa If-Match corrisponde al tag di versione più recente generato dal sistema per quel set di dati.

NOTA

Se non esistono attualmente etichette per il set di dati in questione, è possibile aggiungere nuove etichette solo tramite una richiesta POST, che non richiede un’intestazione If-Match. Una volta aggiunte le etichette a un set di dati, viene assegnato un valore etag che può essere utilizzato per aggiornare o rimuovere le etichette in un secondo momento.

Per recuperare la versione più recente dell'entità dataset-label, effettua una richiesta di GET all'endpoint /datasets/{DATASET_ID}/labels. Il valore corrente viene restituito nella risposta sotto un'intestazione etag . Quando si aggiornano le etichette dei set di dati esistenti, è consigliabile eseguire prima una richiesta di ricerca per il set di dati per recuperare il valore etag più recente prima di utilizzare tale valore nell’intestazione If-Match della richiesta PUT o DELETE successiva.

In questa pagina