Applicare la conformità dell’utilizzo dei dati per una definizione di segmento utilizzando le API

Questo tutorial illustra i passaggi necessari per applicare la conformità all’utilizzo dei dati per le definizioni dei segmenti utilizzando le API.

Introduzione

Questo tutorial richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:

  • Real-Time Customer Profile: Real-Time Customer Profile è un archivio di entità di ricerca generico e viene utilizzato per gestire i dati di Experience Data Model (XDM) all'interno di Platform. Il profilo unisce i dati tra diverse risorse di dati aziendali e consente di accedere a tali dati in una presentazione unificata.

    • Criteri di unione: regole utilizzate da Real-Time Customer Profile per determinare quali dati possono essere uniti in una visualizzazione unificata in determinate condizioni. I criteri di unione possono essere configurati a scopo di governance dei dati.
  • Segmentation: Real-Time Customer Profile divide un gruppo elevato di individui contenuti nell'archivio profili in gruppi più piccoli che condividono caratteristiche simili e risponderanno in modo simile alle strategie di marketing.

  • Governance dei dati: la governance dei dati fornisce l'infrastruttura per l'etichettatura e l'applicazione dell'utilizzo dei dati, utilizzando i seguenti componenti:

    • Etichette di utilizzo dati: etichette utilizzate per descrivere set di dati e campi in termini di livello di riservatezza con cui gestire i rispettivi dati.
    • Criteri di utilizzo dati: configurazioni che indicano quali azioni di marketing sono consentite nei dati classificati da particolari etichette di utilizzo dati.
    • Applicazione dei criteri: consente di applicare i criteri di utilizzo dei dati e di impedire operazioni sui dati che costituiscono violazioni dei criteri.
  • 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.

Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per effettuare correttamente chiamate alle API Platform.

Lettura delle chiamate API di esempio

Questo tutorial fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un codice JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform.

Raccogliere i valori per le intestazioni richieste

Per effettuare chiamate alle API Platform, devi prima completare l'esercitazione di autenticazione. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:

  • Autorizzazione: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Tutte le risorse in Experience Platform sono isolate in specifiche sandbox virtuali. Tutte le richieste alle API Platform richiedono un'intestazione che specifichi il nome della sandbox in cui verrà eseguita l'operazione:

  • x-sandbox-name: {SANDBOX_NAME}
NOTE
Per ulteriori informazioni sulle sandbox in Platform, consulta la documentazione di panoramica sulle sandbox.

Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:

  • Content-Type: application/json

Cercare un criterio di unione per una definizione di segmento merge-policy

Questo flusso di lavoro inizia con l’accesso a una definizione di segmento nota. Le definizioni dei segmenti abilitate per l'utilizzo in Real-Time Customer Profile contengono un ID del criterio di unione all'interno della relativa definizione del segmento. Questo criterio di unione contiene informazioni sui set di dati da includere nella definizione del segmento, che a sua volta contengono eventuali etichette di utilizzo dei dati applicabili.

Utilizzando l'API Segmentation, è possibile cercare una definizione di segmento in base al relativo ID per trovare il relativo criterio di unione associato.

Formato API

GET /segment/definitions/{SEGMENT_DEFINITION_ID}
Proprietà
Descrizione
{SEGMENT_DEFINITION_ID}
ID della definizione del segmento che desideri cercare.

Richiesta

curl -X GET \
  https://platform.adobe.io/data/core/ups/segment/definitions/24379cae-726a-4987-b7b9-79c32cddb5c1 \
  -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 i dettagli della definizione del segmento.

{
    "id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 90,
    "imsOrgId": "{ORG_ID}",
    "name": "Cart abandons in CA",
    "description": "",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "homeAddress.countryISO = 'US'"
    },
    "mergePolicyId": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1556094486000,
    "updateEpoch": 1556094486000,
    "updateTime": 1556094486000
  }
}
Proprietà
Descrizione
mergePolicyId
ID del criterio di unione utilizzato per la definizione del segmento. Verrà utilizzato nel passaggio successivo.

Trovare i set di dati di origine dal criterio di unione datasets

I criteri di unione contengono informazioni sui relativi set di dati di origine, che a loro volta contengono etichette di utilizzo dei dati. È possibile ricercare i dettagli di un criterio di unione fornendo l'ID del criterio di unione in una richiesta GET all'API Profile. Ulteriori informazioni sui criteri di unione sono disponibili nella guida dell'endpoint dei criteri di unione.

Formato API

GET /config/mergePolicies/{MERGE_POLICY_ID}
Proprietà
Descrizione
{MERGE_POLICY_ID}
ID del criterio di unione ottenuto nel passaggio precedente.

Richiesta

curl -X GET \
  https://platform.adobe.io/data/core/ups/config/mergePolicies/2b43d78d-0ad4-4c1e-ac2d-574c09b01119 \
  -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 i dettagli del criterio di unione.

{
    "id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "imsOrgId": "{ORG_ID}",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "version": 1,
    "identityGraph": {
        "type": "none"
    },
    "attributeMerge": {
        "type":"dataSetPrecedence",
        "data": {
            "order": ["5b95b155419ec801e6eee780", "5b7c86968f7b6501e21ba9df"]
        }
    },
    "default": false,
    "updateEpoch": 1551127597
}
Proprietà
Descrizione
schema.name
Nome dello schema associato al criterio di unione.
attributeMerge.type
Tipo di configurazione della precedenza dei dati per il criterio di unione. Se il valore è dataSetPrecedence, i set di dati associati a questo criterio di unione sono elencati in attributeMerge > data > order. Se il valore è timestampOrdered, tutti i set di dati associati allo schema a cui si fa riferimento in schema.name vengono utilizzati dal criterio di unione.
attributeMerge.data.order
Se attributeMerge.type è dataSetPrecedence, questo attributo sarà un array contenente gli ID dei set di dati utilizzati da questo criterio di unione. Questi ID vengono utilizzati nel passaggio successivo.

Valuta i set di dati per le violazioni dei criteri

NOTE
Questo passaggio presuppone che tu disponga di almeno un criterio di utilizzo dei dati attivo che impedisca l’esecuzione di specifiche azioni di marketing sui dati contenenti determinate etichette. Se non disponi di criteri di utilizzo applicabili per i set di dati in fase di valutazione, segui il tutorial sulla creazione dei criteri per crearne uno prima di continuare con questo passaggio.

Dopo aver ottenuto gli ID dei set di dati di origine del criterio di unione, è possibile utilizzare l'API del servizio criteri per valutare tali set di dati rispetto a specifiche azioni di marketing al fine di verificare la presenza di violazioni dei criteri di utilizzo dei dati.

Per valutare i set di dati, devi fornire il nome dell’azione di marketing nel percorso di una richiesta POST, fornendo al contempo gli ID dei set di dati nel corpo della richiesta, come mostrato nell’esempio di seguito.

Formato API

POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints
Parametro
Descrizione
{MARKETING_ACTION_NAME}
Nome dell’azione di marketing associata ai criteri di utilizzo dei dati in base ai quali vengono valutati i set di dati. A seconda che il criterio sia stato definito da Adobe o dall'organizzazione, è necessario utilizzare rispettivamente /marketingActions/core o /marketingActions/custom.

Richiesta

La richiesta seguente verifica l'azione di marketing exportToThirdParty sui set di dati ottenuti nel passaggio precedente. Il payload della richiesta è un array contenente gli ID di ciascun set di dati.

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty/constraints
  -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 '[
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780"
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df"
    }
  ]'
Proprietà
Descrizione
entityType
Ogni elemento nella matrice del payload deve indicare il tipo di entità da definire. Per questo caso d’uso, il valore sarà sempre "dataSet".
entityID
Ogni elemento nell’array di payload deve fornire l’ID univoco per un set di dati.

Risposta

In caso di esito positivo, la risposta restituisce l’URI per l’azione di marketing, le etichette di utilizzo dei dati raccolte dai set di dati forniti e un elenco di eventuali criteri di utilizzo dei dati violati a seguito del test dell’azione su tali etichette. In questo esempio, il criterio "Export Data to Third Party" (Esporta dati a terze parti) viene visualizzato nell'array violatedPolicies, a indicare che l'azione di marketing ha attivato una violazione dei criteri.

{
  "timestamp": 1556324277895,
  "clientId": "{CLIENT_ID}",
  "userId": "{USER_ID}",
  "imsOrg": "{ORG_ID}",
  "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty",
  "duleLabels": [
    "C1",
    "C2",
    "C4",
    "C5"
  ],
  "discoveredLabels": [
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780",
      "dataSetLabels": {
        "connection": {
          "labels": []
        },
        "dataSet": {
          "labels": [
            "C5"
          ]
        },
        "fields": [
          {
            "labels": [
              "C2",
            ],
            "path": "/properties/_customer"
          },
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/geoUnit"
          },
          {
            "labels": [
              "C1"
            ],
            "path": "/properties/identityMap"
          }
        ]
      }
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df",
      "dataSetLabels": {
        "connection": {
          "labels": []
        },
        "dataSet": {
          "labels": [
            "C5"
          ]
        },
        "fields": [
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/createdByBatchID"
          },
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/faxPhone"
          }
        ]
      }
    }
  ],
  "violatedPolicies": [
    {
      "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"
    }
  ]
}
Proprietà
Descrizione
duleLabels
Elenco di etichette di utilizzo dei dati estratte dai set di dati forniti.
discoveredLabels
Elenco dei set di dati forniti nel payload della richiesta, con le etichette a livello di set di dati e di campo presenti in ognuno di essi.
violatedPolicies
Array che elenca i criteri di utilizzo dei dati violati dal test dell'azione di marketing (specificata in marketingActionRef) rispetto al duleLabels fornito.

Utilizzando i dati restituiti nella risposta API, puoi impostare i protocolli all’interno dell’applicazione Experience per applicare in modo appropriato le violazioni dei criteri quando si verificano.

Filtrare i campi dati

Se la definizione del segmento non supera la valutazione, puoi regolare i dati inclusi nella definizione del segmento tramite uno dei due metodi descritti di seguito.

Aggiornare il criterio di unione della definizione del segmento

L’aggiornamento del criterio di unione di una definizione di segmento adeguerà i set di dati e i campi che verranno inclusi durante l’esecuzione del processo di segmentazione. Per ulteriori informazioni, consulta la sezione sull'aggiornamento di un criterio di unione esistente nell'esercitazione sui criteri di unione API.

Limita campi di dati specifici durante l’esportazione della definizione del segmento

Quando si esporta una definizione di segmento in un set di dati utilizzando l'API Segmentation, è possibile filtrare i dati inclusi nell'esportazione utilizzando il parametro fields. Tutti i campi dati aggiunti a questo parametro verranno inclusi nell’esportazione, mentre tutti gli altri campi dati verranno esclusi.

Considera una definizione di segmento con campi di dati denominati "A", "B" e "C". Se desideri esportare solo il campo "C", il parametro fields conterrà solo il campo "C". In questo modo, i campi "A" e "B" verrebbero esclusi durante l’esportazione della definizione del segmento.

Per ulteriori informazioni, consulta la sezione sull'esportazione di una definizione di segmento nel tutorial sulla segmentazione.

Passaggi successivi

Seguendo questa esercitazione, hai cercato le etichette di utilizzo dei dati associate a una definizione di segmento e le hai testate per verificare la presenza di violazioni dei criteri rispetto a specifiche azioni di marketing. Per ulteriori informazioni sulla governance dei dati in Experience Platform, leggere la panoramica di Governance dei dati.

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871