Creare una connessione di origine e un flusso di dati per Customer.io utilizzo dell’API del servizio Flusso
Il seguente tutorial illustra i passaggi necessari per creare un Customer.io connessione sorgente e flusso di dati da portare Customer.io dati evento a Adobe Experience Platform utilizzando Flow Service API.
Introduzione getting-started
Questa guida richiede una buona conoscenza dei seguenti componenti di Experience Platform:
- Sorgenti: Experience Platform consente di acquisire dati da varie origini, fornendo al contempo la possibilità di strutturare, etichettare e migliorare i dati in arrivo tramite Platform servizi.
- Sandbox: Experienci Platform fornisce sandbox virtuali che permettono di suddividere una singola istanza Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.
Connetti Customer.io alla piattaforma utilizzando Flow Service API connect-platform-to-flow-api
Di seguito sono descritti i passaggi da eseguire per creare una connessione di origine e un flusso di dati per portare Customer.io dati degli eventi di cui eseguire l’Experience Platform.
Creare una connessione sorgente source-connection
Creare una connessione sorgente effettuando una richiesta POST al Flow Service API, fornendo l’ID della specifica di connessione della sorgente e dettagli come nome e descrizione e il formato dei dati.
Formato API
POST /sourceConnections
Richiesta
La richiesta seguente crea una connessione sorgente per Customer.io:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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 '{
"name": "Streaming Source Connection for Customer.io",
"providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
"description": "Streaming Source Connection for customer.io",
"connectionSpec": {
"id": "96479064-7b8a-4d69-b9ed-21c5683837ea",
"version": "1.0"
},
"data": {
"format": "json"
}
}'
name
description
connectionSpec.id
data.format
json
.Risposta
In caso di esito positivo, la risposta restituisce l’identificatore univoco (id
) della connessione sorgente appena creata. Questo ID è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "133bb51f-f310-4b4a-b8b2-731aef1e223c",
"etag": "\"af00a717-0000-0200-0000-63ef2cbd0000\""
}
Creare uno schema XDM di destinazione target-schema
Per utilizzare i dati sorgente in Platform, è necessario creare uno schema di destinazione che strutturi i dati sorgente in base alle tue esigenze. Lo schema di destinazione viene quindi utilizzato per creare un set di dati di Platform in cui sono contenuti i dati di origine.
È possibile creare uno schema XDM di destinazione eseguendo una richiesta POST al API del registro dello schema.
Per i passaggi dettagliati su come creare uno schema XDM di destinazione, consulta l’esercitazione su creazione di uno schema tramite l’API.
Creare un set di dati di destinazione target-dataset
È possibile creare un set di dati di destinazione eseguendo una richiesta POST al API Catalog Service, che fornisce l’ID dello schema di destinazione all’interno del payload.
Per i passaggi dettagliati su come creare un set di dati di destinazione, consulta l’esercitazione su creazione di un set di dati tramite l’API.
Creare una connessione di destinazione target-connection
Una connessione di destinazione rappresenta la connessione alla destinazione in cui devono essere memorizzati i dati acquisiti. Per creare una connessione di destinazione, devi fornire l’ID di specifica della connessione fissa che corrisponde al data lake. Questo ID è: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Ora disponi degli identificatori univoci, di uno schema di destinazione, di un set di dati di destinazione e dell’ID della specifica di connessione al data lake. Utilizzando questi identificatori, puoi creare una connessione di destinazione utilizzando Flow Service API per specificare il set di dati che conterrà i dati di origine in entrata.
Formato API
POST /targetConnections
Richiesta
La richiesta seguente crea una connessione di destinazione per Customer.io:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-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 '{
"name": "Streaming Target Connection for Customer.io",
"description": "Streaming Target Connection for Customer.io",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json",
"schema": {
"id": "https://ns.adobe.com/extconndev/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "63ec807d3f5ce91bd2d06c65"
}
}'
name
description
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.data.format
params.dataSetId
Risposta
In caso di esito positivo, la risposta restituisce l’identificatore univoco della nuova connessione di destinazione (id
). Questo ID è richiesto nei passaggi successivi.
{
"id": "da8b75ad-f6ee-4991-95df-291e62936e98",
"etag": "\"70003dff-0000-0200-0000-63ef4a090000\""
}
Creare una mappatura mapping
Per poter acquisire i dati di origine in un set di dati di destinazione, è necessario prima mapparli sullo schema di destinazione a cui il set di dati di destinazione aderisce. Ciò si ottiene eseguendo una richiesta POST a Data Prep API con mappature di dati definite nel payload della richiesta.
Formato API
POST /conversion/mappingSets
Richiesta
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-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 '{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"destinationXdmPath": "_extconndev.cio_id",
"sourceAttribute": "data.identifiers.cio_id",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "_extconndev.email",
"sourceAttribute": "data.identifiers.email",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "_extconndev.event_id0",
"sourceAttribute": "event_id",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "_extconndev.metricx",
"sourceAttribute": "metric",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "_extconndev.object_type1",
"sourceAttribute": "object_type",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "_extconndev.timestampx",
"sourceAttribute": "timestamp",
"identity": false,
"version": 0
}
]
}'
outputSchema.schemaRef.id
mappings.sourceType
mappings.source
mappings.destination
Risposta
In caso di esito positivo, la risposta restituisce i dettagli della mappatura appena creata, compreso l’identificatore univoco (id
). Questo valore è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
"version": 0,
"createdDate": 1676627988129,
"modifiedDate": 1676627988129,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Creare un flusso flow
L’ultimo passaggio per importare dati da Customer.io In Platform è necessario creare un flusso di dati. A questo punto sono stati preparati i seguenti valori obbligatori:
Un flusso di dati è responsabile della pianificazione e della raccolta di dati da un’origine. Puoi creare un flusso di dati eseguendo una richiesta POST e fornendo i valori precedentemente menzionati all’interno del payload.
Formato API
POST /flows
Richiesta
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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 '{
"name": "Streaming Dataflow for Customer.io",
"description": "Streaming Dataflow for Customer.io",
"flowSpec": {
"id": "e77fde5a-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"sourceConnectionIds": [
"133bb51f-f310-4b4a-b8b2-731aef1e223c"
],
"targetConnectionIds": [
"da8b75ad-f6ee-4991-95df-291e62936e98"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
"mappingVersion": 0
}
}
]
}'
name
description
flowSpec.id
e77fde5a-22a8-11ed-861d-0242ac120002
.flowSpec.version
1.0
.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
.Risposta
In caso di esito positivo, la risposta restituisce l’ID (id
) del flusso di dati appena creato. Puoi usare questo ID per monitorare, aggiornare o eliminare il flusso di dati.
{
"id": "4982698b-e6b3-48c2-8dcf-040e20121fd2",
"etag": "\"4c012103-0000-0200-0000-63ef57db0000\""
}
Ottieni l’URL dell’endpoint di streaming get-streaming-endpoint-url
Una volta creato il flusso di dati, ora puoi recuperare l’URL dell’endpoint di streaming. Utilizzerai questo URL endpoint per sottoscrivere l’origine a un webhook, consentendo alla tua origine di comunicare con Experienci Platform.
Per recuperare l’URL dell’endpoint di streaming, effettua una richiesta GET al /flows
e fornire l’ID del flusso di dati.
Formato API
GET /flows/{FLOW_ID}
Richiesta
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flows/4982698b-e6b3-48c2-8dcf-040e20121fd2' \
-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 informazioni sul flusso di dati, incluso l’URL dell’endpoint, contrassegnato come inletUrl
. Consulta la sezione Configura webhook per ottenere il valore richiesto.
{
"items": [
{
"id": "4982698b-e6b3-48c2-8dcf-040e20121fd2",
"createdAt": 1676629979503,
"updatedAt": 1676629985390,
"createdBy": "acme@AdobeID",
"updatedBy": "acme@AdobeID",
"createdClient": "{CREATED_CLIENT}",
"updatedClient": "{UPDATED_CLIENT}",
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"imsOrgId": "{ORG_ID}",
"name": "Streaming Dataflow for Customer.io",
"description": "Streaming Dataflow for Customer.io",
"flowSpec": {
"id": "e77fde5a-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"state": "enabled",
"version": "\"4c01c003-0000-0200-0000-63ef57e10000\"",
"etag": "\"4c01c003-0000-0200-0000-63ef57e10000\"",
"sourceConnectionIds": [
"133bb51f-f310-4b4a-b8b2-731aef1e223c"
],
"targetConnectionIds": [
"da8b75ad-f6ee-4991-95df-291e62936e98"
],
"inheritedAttributes": {
"properties": {
"isSourceFlow": true
},
"sourceConnections": [
{
"id": "133bb51f-f310-4b4a-b8b2-731aef1e223c",
"connectionSpec": {
"id": "96479064-7b8a-4d69-b9ed-21c5683837ea",
"version": "1.0"
}
}
],
"targetConnections": [
{
"id": "da8b75ad-f6ee-4991-95df-291e62936e98",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}
]
},
"options": {
"inletUrl": "https://dcs.adobedc.net/collection/e75dcb5247eb65e7385df30270192e80b145566f52ed74d570505bd2e82463f3"
},
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
"mappingVersion": 0
}
}
],
"runs": "/runs?property=flowId==4982698b-e6b3-48c2-8dcf-040e20121fd2",
"providerRefId": "c4726e6f-64b4-4b3b-97e3-f128ace0cc74",
"lastOperation": {
"started": 0,
"updated": 0,
"operation": "enable"
}
}
]
}
Appendice appendix
La sezione seguente fornisce informazioni sui passaggi possibili per monitorare, aggiornare ed eliminare il flusso di dati.
Monitorare il flusso di dati monitor-dataflow
Una volta creato il flusso di dati, puoi monitorare i dati che vengono acquisiti tramite di esso per visualizzare informazioni sulle esecuzioni del flusso, sullo stato di completamento e sugli errori. Per esempi API completi, consulta la guida su monitoraggio dei flussi di dati di origine tramite l’API.
Aggiornare il flusso di dati update-dataflow
Aggiorna i dettagli del flusso di dati, ad esempio il nome e la descrizione, nonché la pianificazione di esecuzione e i set di mappatura associati, effettuando una richiesta PATCH al /flows
endpoint di Flow Service e fornire l’ID del flusso di dati. Quando effettui una richiesta PATCH, devi fornire il codice univoco del flusso di dati etag
nel If-Match
intestazione. Per esempi API completi, consulta la guida su aggiornamento dei flussi di dati di origine tramite l’API
Aggiornare l’account update-account
Aggiorna il nome, la descrizione e le credenziali dell’account di origine eseguendo una richiesta PATCH al Flow Service fornendo l’ID connessione di base come parametro di query. Quando effettui una richiesta PATCH, devi fornire il codice univoco dell’account sorgente etag
nel If-Match
intestazione. Per esempi API completi, consulta la guida su aggiornamento dell’account sorgente tramite l’API.
Eliminare il flusso di dati delete-dataflow
Elimina il flusso di dati eseguendo una richiesta DELETE al Flow Service fornendo l’ID del flusso di dati che desideri eliminare come parte del parametro di query. Per esempi API completi, consulta la guida su eliminazione dei flussi di dati tramite API.
Elimina l’account delete-account
Elimina l’account eseguendo una richiesta DELETE al Flow Service fornendo l’ID della connessione di base dell’account da eliminare. Per esempi API completi, consulta la guida su eliminazione dell’account sorgente tramite l’API.