Le destinazioni Amazon Kinesis e Azure Event Hubs le destinazioni in CDP in tempo reale sono attualmente in versione beta. La documentazione e le funzionalità sono soggette a modifiche.
Questa esercitazione illustra come utilizzare le chiamate API per connettersi ai dati Adobe Experience Platform, creare una connessione a una destinazione di archiviazione cloud in streaming (Amazon Kinesis o Azure Event Hubs), creare un flusso di dati per la nuova destinazione creata e attivare i dati per la nuova destinazione creata.
Questa esercitazione utilizza la Amazon Kinesis destinazione in tutti gli esempi, ma i passaggi sono identici per Azure Event Hubs.
Se preferite utilizzare l'interfaccia utente in Adobe CDP in tempo reale per collegarvi a una destinazione e attivare i dati, consultate le esercitazioni Connetti una destinazione e Attiva profili e segmenti a una destinazione .
Questa guida richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:
Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per attivare i dati per le destinazioni di streaming in CDP in tempo reale.
Per completare i passaggi di questa esercitazione, devi disporre delle seguenti credenziali, a seconda del tipo di destinazioni a cui stai connettendo e a cui stai attivando i segmenti.
accessKeyId
, secretKey
, region
oppure connectionUrl
sasKeyName
, sasKey
, namespace
Questa esercitazione 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 JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, vedete la sezione come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi del Experience Platform .
Per effettuare chiamate alle API della piattaforma, dovete prima completare l'esercitazione diautenticazione. Completando l'esercitazione sull'autenticazione, vengono forniti i valori per ciascuna delle intestazioni richieste in tutte chiamate API di Experience Platform, come illustrato di seguito:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Le risorse in Experience Platform possono essere isolate in sandbox virtuali specifiche. Nelle richieste alle API della piattaforma, potete specificare il nome e l'ID della sandbox in cui avrà luogo l'operazione. Questi sono parametri facoltativi.
{SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Experience Platform, consultate la documentazione sulla panoramica dellasandbox.
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione aggiuntiva per il tipo di supporto:
application/json
In questa esercitazione potete trovare la documentazione di riferimento associata a tutte le chiamate API in Swagger. Consulta la documentazione API del servizio di flusso Adobe.io. È consigliabile utilizzare questa esercitazione e la pagina della documentazione Swagger in parallelo.
Come primo passo, devi decidere a quale destinazione di streaming attivare i dati. Per iniziare, esegui una chiamata per richiedere un elenco di destinazioni disponibili a cui puoi collegare e attivare i segmenti. Eseguite la seguente richiesta di GET all' connectionSpecs
endpoint per restituire un elenco di destinazioni disponibili:
Formato API
GET /connectionSpecs
Richiesta
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'
Risposta
Una risposta corretta contiene un elenco delle destinazioni disponibili e dei relativi identificatori univoci (id
). Memorizzate il valore della destinazione che intendete utilizzare, come sarà necessario in ulteriori passaggi. Ad esempio, se desiderate collegare e distribuire i segmenti a Amazon Kinesis o Azure Event Hubs, nella risposta cercate il frammento seguente:
{
"id": "86043421-563b-46ec-8e6c-e23184711bf6",
"name": "Amazon Kinesis",
...
...
}
{
"id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
"name": "Azure Event Hubs",
...
...
}
Successivamente, è necessario connettersi ai dati del Experience Platform , in modo da poter esportare i dati del profilo e attivarli nella destinazione desiderata. Si tratta di due sottogruppi descritti di seguito.
Formato API
POST /connections
Richiesta
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Base connection to Experience Platform",
"description": "This call establishes the connection to Experience Platform data",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
}
}'
{CONNECTION_SPEC_ID}
: Utilizzate l'ID delle specifiche di connessione per Unified Profile Service - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Risposta
Una risposta corretta contiene l'identificatore univoco (id
) della connessione di base. Memorizzate questo valore come richiesto nel passaggio successivo per creare la connessione di origine.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
Formato API
POST /sourceConnections
Richiesta
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connecting to Unified Profile Service",
"description": "Optional",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"baseConnectionId": "{BASE_CONNECTION_ID}",
"data": {
"format": "json"
},
"params" : {}
}'
{BASE_CONNECTION_ID}
: Utilizzate l'ID ottenuto nel passaggio precedente.{CONNECTION_SPEC_ID}
: Utilizzate l'ID delle specifiche di connessione per Unified Profile Service - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Risposta
Una risposta corretta restituisce l’identificatore univoco (id
) per la nuova connessione di origine a Unified Profile Service creata. Questo conferma che la connessione ai dati del Experience Platform è stata completata. Memorizza questo valore come richiesto in un passaggio successivo.
{
"id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}
In questo passaggio, si sta configurando una connessione alla destinazione di streaming desiderata. Si tratta di due sottogruppi descritti di seguito.
Formato API
POST /connections
Richiesta
L'esempio seguente include commenti di codice con prefisso //
. Questi commenti evidenziano dove devono essere utilizzati valori diversi per destinazioni di streaming diverse. Rimuovere i commenti prima di utilizzare lo snippet.
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connection for Amazon Kinesis/ Azure Event Hubs",
"description": "summer advertising campaign",
"connectionSpec": {
"id": "{_CONNECTION_SPEC_ID}",
"version": "1.0"
},
"auth": {
"specName": "{AUTHENTICATION_CREDENTIALS}",
"params": { // use these values for Amazon Kinesis connections
"accessKeyId": "{ACCESS_ID}",
"secretKey": "{SECRET_KEY}",
"region": "{REGION}"
},
"params": { // use these values for Azure Event Hubs connections
"sasKeyName": "{SAS_KEY_NAME}",
"sasKey": "{SAS_KEY}",
"namespace": "{EVENT_HUB_NAMESPACE}"
}
}
}'
{CONNECTION_SPEC_ID}
: Utilizza l'ID delle specifiche di connessione ottenuto nel passaggio Ottieni l'elenco delle destinazionidisponibili.{AUTHENTICATION_CREDENTIALS}
: compila il nome della destinazione di streaming: Aws Kinesis authentication credentials
o Azure EventHub authentication credentials
.{ACCESS_ID}
: Per Amazon Kinesis le connessioni. L'ID di accesso per la posizione di archiviazione Amazon Kinesis.{SECRET_KEY}
: Per Amazon Kinesis le connessioni. Chiave segreta per la posizione di archiviazione Amazon Kinesis.{REGION}
: Per Amazon Kinesis le connessioni. La regione nel tuo Amazon Kinesis account in cui CDP in tempo reale eseguirà lo streaming dei dati.{SAS_KEY_NAME}
: Per Azure Event Hubs le connessioni. Inserisci il nome della chiave SAS. Informazioni sull'autenticazione con Azure Event Hubs le chiavi SAS nella documentazione Microsoft.{SAS_KEY}
: Per Azure Event Hubs le connessioni. Compilare la chiave SAS. Informazioni sull'autenticazione con Azure Event Hubs le chiavi SAS nella documentazione Microsoft.{EVENT_HUB_NAMESPACE}
: Per Azure Event Hubs le connessioni. Compilate lo spazio dei nomi in cui il CDP in tempo reale eseguirà lo streaming dei dati. Azure Event Hubs Per ulteriori informazioni, consultate Creare uno spazio dei nomi per gli hub eventi nella Microsoft documentazione.Risposta
Una risposta corretta contiene l'identificatore univoco (id
) della connessione di base. Archiviate questo valore come richiesto nel passaggio successivo per creare una connessione di destinazione.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
Formato API
POST /targetConnections
Richiesta
L'esempio seguente include commenti di codice con prefisso //
. Questi commenti evidenziano dove devono essere utilizzati valori diversi per destinazioni di streaming diverse. Rimuovere i commenti prima di utilizzare lo snippet.
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Amazon Kinesis/ Azure Event Hubs target connection",
"description": "Connection to Amazon Kinesis/ Azure Event Hubs",
"baseConnectionId": "{BASE_CONNECTION_ID}",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": { // use these values for Amazon Kinesis connections
"stream": "{NAME_OF_DATA_STREAM}",
"region": "{REGION}"
},
"params": { // use these values for Azure Event Hubs connections
"eventHubName": "{EVENT_HUB_NAME}"
}
}'
{BASE_CONNECTION_ID}
: Utilizzate l'ID di connessione di base ottenuto nel passaggio precedente.{CONNECTION_SPEC_ID}
: Utilizzare le specifiche di connessione ottenute nel passaggio Ottenere l'elenco delle destinazionidisponibili.{NAME_OF_DATA_STREAM}
: Per Amazon Kinesis le connessioni. Specifica il nome del flusso di dati esistente nel tuo Amazon Kinesis account. CDP in tempo reale esporta i dati in questo flusso.{REGION}
: Per Amazon Kinesis le connessioni. La regione nel tuo account Kinesis Amazon in cui CDP in tempo reale eseguirà lo streaming dei dati.{EVENT_HUB_NAME}
: Per Azure Event Hubs le connessioni. Compila il Azure Event Hub nome in cui il CDP in tempo reale eseguirà lo streaming dei dati. Per ulteriori informazioni, consultate Creare un hub eventi nella Microsoft documentazione.Risposta
Una risposta corretta restituisce l’identificatore univoco (id
) per la nuova connessione di destinazione alla destinazione di streaming. Memorizza questo valore come richiesto nei passaggi successivi.
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
Utilizzando gli ID ottenuti nei passaggi precedenti, ora puoi creare un flusso di dati tra i dati del tuo Experience Platform e la destinazione in cui attiverai i dati. Considerate questo passaggio come la costruzione della pipeline, attraverso la quale i dati scorreranno successivamente, tra Experience Platform e la destinazione desiderata.
Per creare un flusso di dati, eseguite una richiesta di POST, come mostrato di seguito, fornendo al contempo i valori indicati di seguito all'interno del payload.
Eseguite la seguente richiesta di POST per creare un flusso di dati.
Formato API
POST /flows
Richiesta
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "Azure Event Hubs",
"description": "Azure Event Hubs",
"flowSpec": {
"id": "{FLOW_SPEC_ID}",
"version": "1.0"
},
"sourceConnectionIds": [
"{SOURCE_CONNECTION_ID}"
],
"targetConnectionIds": [
"{TARGET_CONNECTION_ID}"
],
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
]
},
"segmentSelectors": {
"selectors": [
]
}
}
}
]
}
{FLOW_SPEC_ID}
: L'ID della specifica di flusso per le destinazioni basate sul profilo è 71471eba-b620-49e4-90fd-23f1fa0174d8
. Utilizzate questo valore nella chiamata.{SOURCE_CONNECTION_ID}
: Utilizzate l'ID di connessione di origine ottenuto nel passaggio Connetti al Experience Platform.{TARGET_CONNECTION_ID}
: Utilizzate l'ID di connessione di destinazione ottenuto nel passaggio Connetti alla destinazionedi streaming.Risposta
Una risposta corretta restituisce l’ID (id
) del flusso di dati appena creato e un ID etag
. Prendete nota di entrambi i valori. come previsto nel passaggio successivo, per attivare i segmenti.
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
"etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}
Dopo aver creato tutte le connessioni e il flusso di dati, ora puoi attivare i dati del profilo sulla piattaforma di streaming. In questo passaggio, puoi selezionare i segmenti e gli attributi di profilo che stai inviando alla destinazione e pianificare e inviare i dati alla destinazione.
Per attivare i segmenti nella nuova destinazione, è necessario eseguire un'operazione PATCH JSON, simile all'esempio seguente. Puoi attivare più segmenti e attributi di profilo in una sola chiamata. Per ulteriori informazioni sul PATCH JSON, consultate la specifica RFC.
Formato API
PATCH /flows
Richiesta
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
{
"op": "add",
"path": "/transformations/0/params/segmentSelectors/selectors/-",
"value": {
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Name of the segment that you are activating",
"description": "Description of the segment that you are activating",
"id": "{SEGMENT_ID}"
}
}
},
{
"op": "add",
"path": "/transformations/0/params/profileSelectors/selectors/-",
"value": {
"type": "JSON_PATH",
"value": {
"operator": "EXISTS",
"path": "{PROFILE_ATTRIBUTE}"
}
}
}
]
{DATAFLOW_ID}
: Utilizzare il flusso di dati ottenuto nel passaggio precedente.{ETAG}
: Utilizzate il tag ottenuto nel passaggio precedente.{SEGMENT_ID}
: Specifica l'ID del segmento da esportare in questa destinazione. Per recuperare gli ID del segmento per i segmenti da attivare, andate a https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/, selezionate Segmentation Service API nel menu di navigazione a sinistra e cercate l’ GET /segment/definitions
operazione in Segment Definitions.{PROFILE_ATTRIBUTE}
: Ad esempio, personalEmail.address
oppure person.lastName
Risposta
Cercate una risposta OK 202. Non viene restituito alcun corpo di risposta. Per verificare che la richiesta fosse corretta, vedere il passaggio successivo, Convalida del flusso di dati.
Come ultimo passaggio nell'esercitazione, devi verificare che i segmenti e gli attributi di profilo siano stati mappati correttamente al flusso di dati.
Per convalidarlo, eseguire la seguente richiesta di GET:
Formato API
GET /flows
Richiesta
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"'
{DATAFLOW_ID}
: Utilizzare il flusso di dati del passaggio precedente.{ETAG}
: Utilizzate il tag del passaggio precedente.Risposta
La risposta restituita deve includere nel transformations
parametro i segmenti e gli attributi di profilo inviati nel passaggio precedente. Un transformations
parametro di esempio nella risposta potrebbe essere simile al seguente:
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
{
"type": "JSON_PATH",
"value": {
"path": "personalEmail.address",
"operator": "EXISTS"
}
},
{
"type": "JSON_PATH",
"value": {
"path": "person.lastname",
"operator": "EXISTS"
}
}
]
},
"segmentSelectors": {
"selectors": [
{
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Men over 50",
"description": "",
"id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
}
}
]
}
}
}
],
Dati esportati
Oltre agli attributi di profilo e ai segmenti nel passaggio Attivare i dati per la nuova destinazione, i dati esportati in AWS Kinesis e Azure Event Hubs includeranno anche informazioni sulla mappa di identità. Rappresenta le identità dei profili esportati (ad esempio ECID, ID mobile, ID Google, indirizzo e-mail, ecc.). Di seguito è riportato un esempio.
{
"person": {
"email": "yourstruly@adobe.con"
},
"segmentMembership": {
"ups": {
"72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
"lastQualificationTime": "2020-03-03T21:24:39Z",
"status": "exited"
},
"7841ba61-23c1-4bb3-a495-00d695fe1e93": {
"lastQualificationTime": "2020-03-04T23:37:33Z",
"status": "existing"
}
}
},
"identityMap": {
"ecid": [
{
"id": "14575006536349286404619648085736425115"
},
{
"id": "66478888669296734530114754794777368480"
}
],
"email_lc_sha256": [
{
"id": "655332b5fa2aea4498bf7a290cff017cb4"
},
{
"id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
}
]
}
}
Per collegarvi alle destinazioni di streaming descritte in questa esercitazione in modo più semplice, potete utilizzare Postman.
Postman è uno strumento che puoi utilizzare per effettuare chiamate API e gestire librerie di chiamate e ambienti predefiniti.
Per questa esercitazione specifica, sono state allegate le seguenti Postman raccolte:
Fate clic qui per scaricare l'archivio delle raccolte.
Ciascuna raccolta include le richieste necessarie e le variabili di ambiente, rispettivamente per AWS Kinesise Azure Event Hub.
Per collegarsi correttamente alle destinazioni utilizzando le raccolte allegate Postman , attenetevi alla seguente procedura:
Seguendo questa esercitazione, hai collegato con successo CDP in tempo reale a una delle destinazioni di streaming preferite e hai impostato un flusso di dati per la rispettiva destinazione. I dati in uscita possono ora essere utilizzati nella destinazione per l'analisi dei clienti o per qualsiasi altra operazione di dati che desideri eseguire. Per ulteriori informazioni, consulta le pagine seguenti: