Applicare la conformità in materia di utilizzo dei dati per un segmento di pubblico utilizzando le API

Questa esercitazione descrive i passaggi per applicare la conformità in materia di utilizzo dei dati per i segmenti di pubblico Real-time Customer Profile che utilizzano le API.

Introduzione

Questa esercitazione richiede una buona comprensione 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 Experience Data Model (XDM) i dati all’interno di Platform. Il profilo unisce i dati tra varie risorse di dati aziendali e fornisce l’accesso 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 Data Governance.
• Segmentation: Come Real-time Customer Profile divide un grande gruppo di individui contenuti nell’archivio profili in gruppi più piccoli che condividono caratteristiche simili e risponderanno in modo simile alle strategie di marketing.
• Data Governance: Data Governance 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 i set di dati e i campi in termini di livello di sensibilità con cui gestire i rispettivi dati.
  • Criteri di utilizzo dati: Configurazioni che indicano quali azioni di marketing sono consentite sui dati categorizzati da particolari etichette di utilizzo dei dati.
  • Applicazione delle regole: Consente di applicare i criteri di utilizzo dei dati e di impedire le operazioni di dati che costituiscono violazioni dei criteri.
• Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola Platform istanza in ambienti virtuali separati per sviluppare e sviluppare applicazioni di esperienza digitale.

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

Lettura di chiamate API di esempio

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

Raccogli i valori delle intestazioni richieste

Per effettuare chiamate alle API Platform, devi prima completare l’ esercitazione sull’autenticazione. Il completamento dell’esercitazione di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come mostrato di seguito:

• Autorizzazione: Portatore {ACCESS_TOKEN}
• x-api-key: {API_KEY}
• x-gw-ims-org-id: {IMS_ORG}

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

• nome x-sandbox: {SANDBOX_NAME}

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

• Tipo di contenuto: application/json

Cercare un criterio di unione per una definizione di segmento

Questo flusso di lavoro inizia con l’accesso a un segmento di pubblico noto. I segmenti abilitati per l’uso in Real-time Customer Profile contengono un ID criterio di unione all’interno della relativa definizione del segmento. Questo criterio di unione contiene informazioni sui set di dati da includere nel segmento, che a loro volta contengono eventuali etichette di utilizzo dei dati applicabili.

Utilizzando l’API Segmentation, puoi cercare una definizione di segmento in base al relativo ID per trovare i criteri di unione associati.

Formato API

GET /segment/definitions/{SEGMENT_DEFINITION_ID}

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

Una risposta corretta restituisce i dettagli della definizione del segmento.

{
    "id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
    "schema": { 
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 90,
    "imsOrgId": "{IMS_ORG}",
    "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
  }
}

Trovare i set di dati di origine dal criterio di unione

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

Formato API

GET /config/mergePolicies/{MERGE_POLICY_ID}

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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

Una risposta corretta restituisce i dettagli del criterio di unione.

{
    "id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "imsOrgId": "{IMS_ORG}",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "version": 1,
    "identityGraph": {
        "type": "none"
    },
    "attributeMerge": {
        "type":"dataSetPrecedence", 
        "data": {
            "order" : ["5b95b155419ec801e6eee780", "5b7c86968f7b6501e21ba9df"]
        }
    },
    "default": false,
    "updateEpoch": 1551127597
}

Valutare i set di dati per le violazioni dei criteri

Dopo aver ottenuto gli ID dei set di dati di origine dei criteri di unione, puoi utilizzare l’ API del servizio criteri per valutare tali set di dati rispetto a azioni di marketing specifiche 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 di POST, fornendo allo stesso tempo gli ID dei set di dati all’interno del corpo della richiesta, come mostrato nell’esempio seguente.

Formato API

POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints

Richiesta

La richiesta seguente verifica l'azione di marketing exportToThirdParty rispetto ai set di dati ottenuti nel passaggio precedente. Il payload della richiesta è un array contenente gli ID di ogni 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780"
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df"
    }
  ]'

Risposta

Una risposta corretta restituisce l’URI per l’azione di marketing, le etichette di utilizzo dei dati raccolte dai set di dati specificati e un elenco di tutti i criteri di utilizzo dei dati che sono stati violati in seguito al test dell’azione rispetto a tali etichette. In questo esempio, il criterio "Esporta dati in 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": "{IMS_ORG}",
  "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": "{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"
    }
  ]
}

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

Filtrare i campi dati

Se il segmento di pubblico non supera la valutazione, puoi regolare i dati inclusi nel segmento attraverso 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 regola i set di dati e i campi che verranno inclusi durante l’esecuzione del processo di segmento. Per ulteriori informazioni, consulta la sezione sull’ aggiornamento di un criterio di unione esistente nell’esercitazione sui criteri di unione delle API .

Limita campi di dati specifici durante l’esportazione del segmento

Durante l’esportazione di un segmento in un set di dati utilizzando l’ API Segmentation , puoi filtrare i dati inclusi nell’esportazione utilizzando il parametro fields . Tutti i campi di dati aggiunti a questo parametro verranno inclusi nell’esportazione, mentre tutti gli altri campi di dati verranno esclusi.

Considera un segmento con campi di dati denominati "A", "B" e "C". Se si desidera 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 del segmento.

Per ulteriori informazioni, consulta la sezione sull’ esportazione di un segmento nell’esercitazione sulla segmentazione .

Passaggi successivi

Seguendo questa esercitazione, hai cercato le etichette di utilizzo dei dati associate a un segmento di pubblico e le hai testate per individuare eventuali violazioni dei criteri rispetto a specifiche azioni di marketing. Per ulteriori informazioni su Data Governance in Experience Platform, leggere la panoramica relativa a Data Governance.