DocumentazioneExperience PlatformGuida alla governance dei dati

Creare un criterio di governance dei dati nell’API

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Argomenti:

Creato per:

  • Utente
  • Sviluppatore
  • Amministratore

L'API del servizio criteri consente di creare e gestire criteri di governance dei dati per determinare quali azioni di marketing possono essere eseguite sui dati che contengono determinate etichette di utilizzo dei dati.

Questo documento fornisce un tutorial dettagliato per la creazione di un criterio di governance tramite l'API Policy Service.

NOTE
Per i passaggi su come creare un criterio di controllo di accesso, vedere la guida dell'endpoint /policies per l'API di controllo di accesso. Per informazioni su come creare un criterio di consenso, consulta la guida dell'interfaccia utente dei criteri.

Introduzione

Questo tutorial richiede una buona conoscenza dei seguenti concetti chiave coinvolti nella creazione e nella valutazione delle policy:

  • Governance dei dati di Adobe Experience Platform: framework tramite il quale Platform impone la conformità all'utilizzo dei dati.
    • Etichette di utilizzo dati: le etichette di utilizzo dati vengono applicate ai campi dati XDM, specificando restrizioni per l'accesso ai dati.
  • Experience Data Model (XDM): framework standardizzato tramite il quale Platform organizza i dati sull'esperienza del cliente.
  • Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza di Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.

Prima di iniziare questo tutorial, consulta la guida per gli sviluppatori per informazioni importanti che devi conoscere per effettuare correttamente chiamate all'API Policy Service, incluse le intestazioni richieste e la lettura delle chiamate API di esempio.

Definire un’azione di marketing define-action

Nel framework di governance dei dati, un'azione di marketing è un'azione eseguita da un consumatore di dati Experience Platform, per la quale è necessario verificare la presenza di violazioni dei criteri di utilizzo dei dati.

Il primo passaggio nella creazione di un criterio di utilizzo dei dati consiste nel determinare l’azione di marketing che verrà valutata dal criterio. Questa operazione può essere eseguita utilizzando una delle seguenti opzioni:

Cercare un’azione di marketing esistente look-up

Per cercare le azioni di marketing esistenti da valutare in base ai criteri, devi eseguire una richiesta GET a uno degli endpoint /marketingActions.

Formato API

A seconda che tu stia cercando un'azione di marketing fornita da Experience Platform o un'azione di marketing personalizzata creata dalla tua organizzazione, utilizza rispettivamente gli endpoint marketingActions/core o marketingActions/custom.

GET /marketingActions/core
GET /marketingActions/custom

Richiesta

La richiesta seguente utilizza l'endpoint marketingActions/custom, che recupera un elenco di tutte le azioni di marketing definite dall'organizzazione.

curl -X GET \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom \
  -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}'

Risposta

In caso di esito positivo, la risposta restituisce il numero totale di azioni di marketing trovate (count) ed elenca i dettagli delle azioni di marketing stesse nell'array children.

{
    "_page": {
        "start": "sampleMarketingAction",
        "count": 2
    },
    "_links": {
        "page": {
            "href": "https://platform.adobe.io/marketingActions/custom?{?limit,start,property}",
            "templated": true
        }
    },
    "children": [
        {
            "name": "sampleMarketingAction",
            "description": "Marketing Action description.",
            "imsOrg": "{ORG_ID}",
            "created": 1550714012088,
            "createdClient": "{CREATED_CLIENT}",
            "createdUser": "{CREATED_USER}",
            "updated": 1550714012088,
            "updatedClient": "{UPDATED_CLIENT}",
            "updatedUser": "{UPDATED_USER}",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/sampleMarketingAction"
                }
            }
        },
        {
            "name": "newMarketingAction",
            "description": "Another marketing action.",
            "imsOrg": "{ORG_ID}",
            "created": 1550793833224,
            "createdClient": "{CREATED_CLIENT}",
            "createdUser": "{CREATED_USER}",
            "updated": 1550793833224,
            "updatedClient": "{UPDATED_CLIENT}",
            "updatedUser": "{UPDATED_USER}",
            "_links": {
                "self": {
                    "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/newMarketingAction"
                }
            }
        }
    ]
}
Proprietà
Descrizione
_links.self.href
Ogni elemento all'interno dell'array children contiene un ID URI per l'azione di marketing indicata.

Quando trovi l'azione di marketing che desideri utilizzare, registra il valore della relativa proprietà href. Questo valore viene utilizzato durante il passaggio successivo di creazione di un criterio.

Creare una nuova azione di marketing create-new

Per creare una nuova azione di marketing, devi eseguire una richiesta PUT all'endpoint /marketingActions/custom/ e fornire un nome per l'azione di marketing alla fine del percorso della richiesta.

Formato API

PUT /marketingActions/custom/{MARKETING_ACTION_NAME}
Parametro
Descrizione
{MARKETING_ACTION_NAME}
Nome della nuova azione di marketing da creare. Questo nome funge da identificatore principale dell’azione di marketing e deve quindi essere univoco. Si consiglia di assegnare all’azione di marketing un nome descrittivo ma conciso.

Richiesta

La richiesta seguente crea una nuova azione di marketing personalizzata denominata "exportToThirdParty". Tieni presente che name nel payload della richiesta è uguale al nome fornito nel percorso della richiesta.

curl -X PUT \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty \
  -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 '{
      "name": "exportToThirdParty",
      "description": "Export data to a third party"
    }'
Proprietà
Descrizione
name
Nome dell’azione di marketing da creare. Questo nome deve corrispondere al nome fornito nel percorso della richiesta, altrimenti si verificherà un errore 400 (Richiesta non valida).
description
Una descrizione leggibile dell’azione di marketing.

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 201 (Creato) e i dettagli dell’azione di marketing appena creata.

{
    "name": "exportToThirdParty",
    "description": "Export data to a third party",
    "imsOrg": "{ORG_ID}",
    "created": 1550713341915,
    "createdClient": "{CREATED_CLIENT}",
    "createdUser": "{CREATED_USER",
    "updated": 1550713856390,
    "updatedClient": "{UPDATED_CLIENT}",
    "updatedUser": "{UPDATED_USER}",
    "_links": {
        "self": {
            "href": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
        }
    }
}
Proprietà
Descrizione
_links.self.href
ID URI dell’azione di marketing.

Registra l’ID URI dell’azione di marketing appena creata, in quanto verrà utilizzata nel passaggio successivo della creazione di un criterio.

Creare un criterio create-policy

Per creare un nuovo criterio è necessario fornire all’ID URI di un’azione di marketing un’espressione delle etichette di utilizzo che impediscono tale azione di marketing.

Questa espressione viene definita espressione di criteri ed è un oggetto contenente (A) un'etichetta oppure (B) un operatore e operandi, ma non entrambi. A sua volta, ogni operando è anche un oggetto espressione di criteri. Ad esempio, un criterio relativo all'esportazione di dati a terze parti potrebbe essere vietato se sono presenti etichette C1 OR (C3 AND C7). Questa espressione viene specificata come:

"deny": {
  "operator": "OR",
  "operands": [
    {
      "label": "C1"
    },
    {
      "operator": "AND",
      "operands": [
        {
          "label": "C3"
        },
        {
          "label": "C7"
        }
      ]
    }
  ]
}
NOTE
Sono supportati solo gli operatori OR e AND.

Dopo aver configurato l'espressione dei criteri, è possibile creare un nuovo criterio effettuando una richiesta POST all'endpoint /policies/custom.

Formato API

POST /policies/custom

Richiesta

La richiesta seguente crea un criterio denominato "Export Data to Third Party" (Esporta dati a terze parti) fornendo un’azione di marketing e un’espressione di criterio nel payload della richiesta.

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/policies/custom \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "name": "Export Data to Third Party",
    "status": "DRAFT",
    "marketingActionRefs": [
      "../marketingActions/custom/exportToThirdParty"
    ],
    "description": "Conditions under which data cannot be exported to a third party",
    "deny": {
      "operator": "OR",
      "operands": [
        {"label": "C1"},
        {
          "operator": "AND",
          "operands": [
            {"label": "C3"},
            {"label": "C7"}
          ]
        }
      ]
    }
  }'
Proprietà
Descrizione
marketingActionRefs
Matrice contenente il valore href di un'azione di marketing, ottenuta nel passaggio precedente. Nell’esempio precedente è elencata una sola azione di marketing, ma è possibile specificare anche più azioni.
deny
L’oggetto espressione criterio. Definisce le etichette e le condizioni di utilizzo che causerebbero il rifiuto da parte del criterio dell'azione di marketing a cui si fa riferimento in marketingActionRefs.

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 201 (Creato) e i dettagli del criterio appena creato.

{
    "name": "Export Data to Third Party",
    "status": "DRAFT",
    "marketingActionRefs": [
        "https://platform-stage.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
    ],
    "description": "Conditions under which data cannot be exported to a third party",
    "deny": {
        "operator": "OR",
        "operands": [
            {
                "label": "C1"
            },
            {
                "operator": "AND",
                "operands": [
                    {
                        "label": "C3"
                    },
                    {
                        "label": "C7"
                    }
                ]
            }
        ]
    },
    "imsOrg": "{ORG_ID}",
    "created": 1565651746693,
    "createdClient": "{CREATED_CLIENT}",
    "createdUser": "{CREATED_USER",
    "updated": 1565651746693,
    "updatedClient": "{UPDATED_CLIENT}",
    "updatedUser": "{UPDATED_USER}",
    "_links": {
        "self": {
            "href": "https://platform-stage.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3"
        }
    },
    "id": "5d51f322e553c814e67af1a3"
}
Proprietà
Descrizione
id
Valore di sola lettura generato dal sistema che identifica in modo univoco il criterio.

Registra l’ID URI del criterio appena creato, in quanto viene utilizzato nel passaggio successivo per abilitare il criterio.

Abilita il criterio

NOTE
Questo passaggio è facoltativo se si desidera lasciare il criterio nello stato DRAFT, ma per impostazione predefinita per partecipare alla valutazione è necessario impostare lo stato di un criterio su ENABLED. Per informazioni su come creare eccezioni per i criteri con stato DRAFT, consulta la guida sull'applicazione dei criteri.

Per impostazione predefinita, i criteri la cui proprietà status è impostata su DRAFT non partecipano alla valutazione. È possibile abilitare i criteri per la valutazione effettuando una richiesta PATCH all'endpoint /policies/custom/ e fornendo l'identificatore univoco per i criteri alla fine del percorso della richiesta.

Formato API

PATCH /policies/custom/{POLICY_ID}
Parametro
Descrizione
{POLICY_ID}
Il valore id del criterio che si desidera abilitare.

Richiesta

La richiesta seguente esegue un'operazione PATCH sulla proprietà status del criterio, modificandone il valore da DRAFT a ENABLED.

curl -X PATCH \
  https://platform.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '[
    {
      "op": "replace",
      "path": "/status",
      "value": "ENABLED"
    }
  ]'
Proprietà
Descrizione
op
Tipo di operazione PATCH da eseguire. Questa richiesta esegue un'operazione di "sostituzione".
path
Percorso del campo da aggiornare. Quando si abilita una policy, il valore deve essere impostato su "/status".
value
Il nuovo valore da assegnare alla proprietà specificata in path. Questa richiesta imposta la proprietà status del criterio su "ENABLED".

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 (OK) e i dettagli del criterio aggiornato con status ora impostato su ENABLED.

{
    "name": "Export Data to Third Party",
    "status": "ENABLED",
    "marketingActionRefs": [
        "https://platform-stage.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
    ],
    "description": "Conditions under which data cannot be exported to a third party",
    "deny": {
        "operator": "OR",
        "operands": [
            {
                "label": "C1"
            },
            {
                "operator": "AND",
                "operands": [
                    {
                        "label": "C3"
                    },
                    {
                        "label": "C7"
                    }
                ]
            }
        ]
    },
    "imsOrg": "{ORG_ID}",
    "created": 1565651746693,
    "createdClient": "{CREATED_CLIENT}",
    "createdUser": "{CREATED_USER}",
    "updated": 1565723012139,
    "updatedClient": "{UPDATED_CLIENT}",
    "updatedUser": "{UPDATED_USER}",
    "_links": {
        "self": {
            "href": "https://platform-stage.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3"
        }
    },
    "id": "5d51f322e553c814e67af1a3"
}

Passaggi successivi

Seguendo questa esercitazione, hai creato correttamente un criterio di utilizzo dei dati per un’azione di marketing. Ora puoi continuare l'esercitazione su imposizione dei criteri di utilizzo dei dati per scoprire come verificare la presenza di violazioni dei criteri e gestirle nell'applicazione Experience.

Per ulteriori informazioni sulle diverse operazioni disponibili nell'API Policy Service, vedere la Guida per gli sviluppatori di Policy Service. Per informazioni su come applicare i criteri per i dati Real-Time Customer Profile, consulta l'esercitazione su imposizione della conformità in materia di utilizzo dei dati per i segmenti di pubblico.

Per informazioni su come gestire i criteri di utilizzo nell'interfaccia utente di Experience Platform, vedere la guida utente dei criteri.

recommendation-more-help
834e0cae-2761-454a-be4d-62f0fd4b4456