Creare e attivare un pubblico esterno tramite l’API

Questo tutorial illustra i passaggi necessari per creare un pubblico esterno utilizzando le API di Adobe Experience Platform.

Introduzione

Questo tutorial richiede una buona conoscenza dei vari servizi Experience Platform coinvolti nella creazione di un pubblico esterno. Prima di iniziare questo tutorial, leggi la documentazione dei seguenti servizi:

Intestazioni richieste

Questo tutorial richiede anche di aver completato l'esercitazione di autenticazione per effettuare correttamente le chiamate alle API Experience Platform. 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:

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

Tutte le richieste POST, PUT e PATCH richiedono un’intestazione aggiuntiva:

Preparare il pubblico esterno prepare

Prima di poter creare un pubblico esterno all’interno di Experience Platform, devi preparare un file che contenga i dati del pubblico.

In questo esempio, devi utilizzare un file CSV. Verifica che il file CSV contenga almeno una colonna con un valore di identità come ECID, ID e-mail o ID CRM. Inoltre, assicurati che contenga tutti gli attributi di arricchimento necessari per la segmentazione e l’attivazione.

È inoltre necessario assicurarsi che il file sia conforme ai requisiti dello schema di Experience Platform. Per ulteriori informazioni sulla creazione di uno schema, leggere l'esercitazione sulla creazione di uno schema tramite API o l'esercitazione sulla creazione di uno schema tramite l'interfaccia utente.

Dopo aver confermato che il file CSV contiene tutte le informazioni necessarie e che è conforme allo schema, devi caricare il file CSV nel provider di archiviazione cloud in modo da poter utilizzare le origini per acquisire i dati in Experience Platform. Per ulteriori informazioni sull'utilizzo di un'origine di archiviazione cloud, leggere l'esercitazione sull'esplorazione delle opzioni di archiviazione cloud tramite l'API o la panoramica delle origini.

Creare un pubblico esterno create

Dopo aver preparato il file CSV, ora puoi avviare il processo di creazione del pubblico esterno.

Per creare un pubblico esterno, devi eseguire una richiesta POST all'endpoint /external-audience/.

Quando effettui questa richiesta, devi specificare le seguenti informazioni:

Per informazioni più dettagliate su come utilizzare questo endpoint, consulta la guida dell'endpoint tipi di pubblico esterni.

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/ \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
        "name": "Sample external audience",
        "description": "A sample version of an external audience",
        "fields": [
            {
                "name": "ppid",
                "type": "string",
                "identityNs": "email"
            },
            {
                "name": "list_id",
                "type": "string",
                "labels": ["core/C2", "custom/deep"]
            },
            {
                "name": "delete",
                "type": "number"
            },
            {
                "name": "process_consent",
                "type": "string"
            }
        ],
        "sourceSpec": {
            "params": {
                "path": "activation/sample-source/example.csv",
                "type": "file",
                "sourceType": "Cloud Storage",
                "baseConnectionId": "1d1d4bc5-b527-46a3-9863-530246a61b2b"
            }
        },
        "ttlInDays": "40",
        "labels": ["core/C1"],
        "audienceType": "people",
        "originName": "CUSTOM_UPLOAD"
    }'

Dopo aver effettuato questa richiesta, assicurati di prendere nota di operationId che ricevi dalla risposta in modo da poter recuperare l'ID del pubblico.

Recupera ID pubblico retrieve-audience-id

Dopo aver creato il pubblico esterno, devi ottenere l’ID del pubblico in modo da poterlo inserire in Experience Platform.

Per recuperare l'ID del pubblico, devi eseguire una richiesta GET all'endpoint /external-audiences/operations e fornire l'ID dell'operazione precedentemente ricevuta dalla risposta di creazione del pubblico esterno.

Per informazioni più dettagliate su come utilizzare questo endpoint, consulta la guida dell'endpoint per pubblico esterno.

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/operations/{OPERATION_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Dopo aver effettuato questa richiesta, accertati di prendere nota di audienceId che ricevi dalla risposta in modo da poter attivare il processo di acquisizione per il pubblico.

Avvia l’acquisizione del pubblico start-ingestion

Poiché hai audienceId, ora puoi attivare l'acquisizione del pubblico esterno in Experience Platform.

Per avviare l’acquisizione di un pubblico, effettua una richiesta POST all’endpoint seguente e specifica l’ID del pubblico. Inoltre, è necessario specificare l'ora di inizio per determinare quali file verranno elaborati.

Per informazioni più dettagliate su come utilizzare questo endpoint, consulta la guida dell'endpoint per tipi di pubblico esterni

curl -X POST https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'
 -d '{
    "dataFilterStartTime": 764245635
 }'

Dopo aver effettuato questa richiesta, assicurati di prendere nota di runId che ricevi dalla risposta in modo da poter monitorare lo stato di acquisizione.

Monitorare lo stato di acquisizione monitor-ingestion

Dopo aver attivato l’acquisizione del pubblico, ora puoi monitorare i progressi dell’acquisizione per confermarne il successo e convalidare la disponibilità del pubblico per l’attivazione a valle.

Per recuperare lo stato di un’acquisizione di pubblico, effettua una richiesta GET al seguente endpoint e allo stesso tempo fornisce sia l’ID del pubblico che gli ID di esecuzione.

Per informazioni più dettagliate su come utilizzare questo endpoint, consulta la guida dell'endpoint per pubblico esterno.

curl -X GET https://platform.adobe.io/data/core/ais/external-audience/{AUDIENCE_ID}/runs/{RUN_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

Passaggi successivi next-steps

Una volta confermato che il pubblico esterno è stato acquisito correttamente, puoi visualizzarlo in Audience Portal e utilizzarlo in servizi a valle come le destinazioni.

Per ulteriori informazioni su Audience Portal, consulta la Guida dell'interfaccia utente di Audience Portal. Per ulteriori informazioni sulle destinazioni, leggere la panoramica sulle destinazioni.