Show Menu
ARGOMENTI×

Creazione di un criterio di utilizzo dei dati

L’etichettatura e l’applicazione dell’uso dei dati (DULE) è il meccanismo fondamentale di governance dei dati della piattaforma Adobe Experience. L'API dule-policy-service.yaml DULE Policy Service consente di creare e gestire criteri DULE per determinare quali azioni di marketing possono essere eseguite rispetto ai dati che contengono determinate etichette DULE.
Questo documento fornisce un'esercitazione dettagliata per la creazione di un criterio DULE tramite l'API del servizio criteri. Per una guida più completa alle diverse operazioni disponibili nell'API, vedete la guida per gli sviluppatori di Policy Service.

Introduzione

Questa esercitazione richiede una conoscenza approfondita dei seguenti concetti chiave relativi alla creazione e alla valutazione di criteri DULE:
  • Governance dei dati: Il framework tramite il quale la piattaforma applica la conformità all'utilizzo dei dati.
  • Etichette di utilizzo dati: Le etichette di utilizzo dei dati vengono applicate ai campi di dati XDM, specificando le restrizioni relative alle modalità di accesso ai dati.
  • Experience Data Model (XDM) : Il framework standardizzato tramite il quale la piattaforma organizza i dati sull'esperienza cliente.
  • Sandbox : Experience Platform fornisce sandbox virtuali che dividono una singola istanza della piattaforma in ambienti virtuali separati per sviluppare e sviluppare applicazioni per esperienze digitali.
Prima di avviare questa esercitazione, consultare la guida Guida per gli sviluppatori API di DULE Policy Service allo sviluppatore per informazioni importanti che è necessario conoscere per eseguire correttamente le chiamate all'API di servizio Criteri DULE, incluse le intestazioni richieste e come leggere le chiamate API di esempio.

Definire un'azione di marketing

Nel framework di governance dei dati, un'azione di marketing è un'azione che un consumatore di dati della piattaforma di esperienze deve intraprendere, per la quale è necessario verificare la presenza di violazioni dei criteri di utilizzo dei dati.
Il primo passo per creare un criterio DULE consiste nel determinare quale azione marketing verrà valutata dal criterio. Questa operazione può essere eseguita utilizzando una delle seguenti opzioni:

Cerca un'azione di marketing esistente

Puoi cercare le azioni di marketing esistenti da valutare in base ai criteri DULE effettuando una richiesta GET a uno degli /marketingActions endpoint.
Formato API
A seconda se stai cercando un'azione di marketing fornita da Experience Platform o un'azione di marketing personalizzata creata dalla tua organizzazione, usa rispettivamente gli marketingActions/core endpoint o marketingActions/custom .
GET /marketingActions/core
GET /marketingActions/custom

Richiesta
La richiesta seguente utilizza l’ marketingActions/custom endpoint, che raccoglie un elenco di tutte le azioni di marketing definite dall’organizzazione IMS.
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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta
Una risposta di successo restituisce il numero totale di azioni di marketing trovate ( count ) ed elenca i dettagli delle azioni di marketing stesse all'interno dell' children array.
{
    "_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": "{IMS_ORG}",
            "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": "{IMS_ORG}",
            "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' children array contiene un ID URI per l'azione di marketing elencata.
Quando trovi l'azione di marketing da utilizzare, registra il valore della relativa href proprietà. Questo valore viene utilizzato durante il passaggio successivo della creazione di un criterio DULE.

Creare una nuova azione di marketing

Puoi creare una nuova azione di marketing eseguendo una richiesta PUT all’ /marketingActions/custom/ endpoint e fornendo 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}
Il nome della nuova azione di marketing da creare. Questo nome funge da identificatore principale dell'azione di marketing e deve pertanto essere univoco. La best practice consiste nel assegnare all’azione di marketing un nome descrittivo ma conciso.
Richiesta
La richiesta seguente crea una nuova azione di marketing personalizzata denominata "exportToThirdParty". Il payload della richiesta name è 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: {IMS_ORG}' \
  -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
Una risposta corretta 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": "{IMS_ORG}",
    "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, che verrà utilizzata nel passaggio successivo per la creazione di un criterio DULE.

Creare un criterio DULE

Per creare un nuovo criterio è necessario fornire l'ID URI di un'azione di marketing con un'espressione delle etichette DULE che vietano tale azione di marketing.
Questa espressione è denominata espressione ​policy ed è un oggetto contenente (A) un'etichetta DULE, oppure (B) un operatore e gli operandi, ma non entrambi. A sua volta, ogni operando è anche un oggetto con espressione di criterio. Ad esempio, un criterio relativo all'esportazione di dati a terzi potrebbe essere vietato se sono presenti C1 OR (C3 AND C7) etichette. Questa espressione viene specificata come:
"deny": {
  "operator": "OR",
  "operands": [
    {
      "label": "C1"
    },
    {
      "operator": "AND",
      "operands": [
        {
          "label": "C3"
        },
        {
          "label": "C7"
        }
      ]
    }
  ]
}

Sono supportati solo gli operatori OR e AND.
Dopo aver configurato l'espressione del criterio, potete creare un nuovo criterio DULE effettuando una richiesta POST all' /policies/custom endpoint.
Formato API
POST /policies/custom

Richiesta
La richiesta seguente crea un criterio DULE denominato "Export Data to Third Party" fornendo un'azione di marketing e un'espressione del 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: {IMS_ORG}' \
  -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
Un array contenente il href valore di un'azione di marketing, ottenuto nel passaggio Definire un'azione di marketing precedente. Anche se l'esempio precedente elenca una sola azione di marketing, è possibile fornire più azioni.
deny
L'oggetto policy espressione. Definisce le etichette e le condizioni DULE che causerebbero il rifiuto dell'azione di marketing a cui si fa riferimento in marketingActionRefs .
Risposta
Una risposta corretta 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": "{IMS_ORG}",
    "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 generato dal sistema di sola lettura che identifica in modo univoco il criterio DULE.
Registra l'ID URI del criterio DULE appena creato, in quanto viene utilizzato nel passaggio successivo per abilitare il criterio.

Abilita criterio DULE

Anche se questo passaggio è facoltativo se desiderate lasciare il criterio DULE nello DRAFT stato, tenete presente che per impostazione predefinita un criterio deve avere lo stato impostato su ENABLED per poter partecipare alla valutazione. Per informazioni su come fare eccezioni per i criteri di stato, vedere l'esercitazione sull'applicazione dei criteri DRAFT DULE.
Per impostazione predefinita, i criteri DULE con status proprietà impostata per DRAFT non partecipano alla valutazione. Potete abilitare il criterio per la valutazione eseguendo una richiesta PATCH all' /policies/custom/ endpoint e fornendo l'identificatore univoco per il criterio alla fine del percorso della richiesta.
Formato API
PATCH /policies/custom/{POLICY_ID}

Parametro
Descrizione
{POLICY_ID}
Il id valore del criterio che si desidera abilitare.
Richiesta
La richiesta seguente esegue un'operazione PATCH sulla status proprietà del criterio DULE, modificando 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: {IMS_ORG}' \
  -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 un criterio, il valore deve essere impostato su "/status".
value
Il nuovo valore da assegnare alla proprietà specificata in path . Questa richiesta imposta la status proprietà del criterio su "ENABLED".
Risposta
Una risposta di successo restituisce lo stato HTTP 200 (OK) e i dettagli del criterio aggiornato, con status la relativa ora impostata 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": "{IMS_ORG}",
    "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 con successo un criterio di utilizzo dei dati per un'azione di marketing. È ora possibile continuare l'esercitazione sull' applicazione dei criteri di utilizzo dei dati per apprendere come verificare la presenza di violazioni dei criteri e gestirle nell'applicazione di esperienza.
Per ulteriori informazioni sulle diverse operazioni disponibili nell'API di Policy Service, consultate la guida per gli sviluppatori di Policy Service. Per informazioni su come applicare criteri per i dati del profilo cliente in tempo reale, consulta l’esercitazione sull’ applicazione della conformità dell’utilizzo dei dati per i segmenti di pubblico.
Per informazioni su come gestire i criteri di utilizzo nell'interfaccia utente della piattaforma Experience, consulta la guida utente ai criteri.