Creare un flusso di dati per le origini di e-commerce utilizzando Flow Service API
Questa esercitazione descrive i passaggi per recuperare i dati da un’origine e-commerce e portarli a Platform tramite Flow Service API.
- Per creare un flusso di dati, è necessario disporre già di un ID connessione di base valido con un’origine E-commerce. Se non disponi di questo ID, consulta panoramica sulle origini per un elenco di origini di e-commerce con cui è possibile creare una connessione di base.
- Ad Experience Platform, per acquisire i dati, i fusi orari per tutte le origini batch basate su tabelle devono essere configurati in formato UTC.
Introduzione
Questo tutorial richiede una buona conoscenza dei seguenti componenti di Adobe Experience Platform:
-
Experience Data Model (XDM) System: framework standardizzato tramite il quale Experienci Platform organizza i dati sull’esperienza del cliente.
- Nozioni di base sulla composizione dello schema: scopri gli elementi di base degli schemi XDM, compresi i principi chiave e le best practice nella composizione dello schema.
- API del registro dello schema: scopri come eseguire correttamente le chiamate all’API Schema Registry. Ciò include
{TENANT_ID}, il concetto di "contenitori" e le intestazioni necessarie per effettuare le richieste (con particolare attenzione all’intestazione Accept e ai suoi possibili valori).
-
Catalog Service: il catalogo è il sistema di registrazione per la posizione e la derivazione dei dati in Experience Platform.
-
Batch ingestion: l’API di acquisizione in batch consente di acquisire dati in Experience Platform come file batch.
-
Sandboxes: Experience Platform fornisce sandbox virtuali che permettono di suddividere un singolo Platform in ambienti virtuali separati, per facilitare lo sviluppo e l’evoluzione delle applicazioni di esperienza digitale.
Utilizzo delle API di Platform
Per informazioni su come effettuare correttamente chiamate alle API di Platform, consulta la guida su introduzione alle API di Platform.
Creare una connessione sorgente source
Puoi creare una connessione sorgente effettuando una richiesta POST al Flow Service API. Una connessione di origine è costituita da un ID di connessione, un percorso del file di dati di origine e un ID della specifica di connessione.
Per creare una connessione di origine, è inoltre necessario definire un valore enum per l'attributo formato dati.
Utilizza i seguenti valori enum per i connettori basati su file:
delimitedjsonparquetPer tutti i connettori basati su tabella, impostare il valore su tabular.
Formato API
POST /sourceConnections
Richiesta
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": "Shopify source connection",
"baseConnectionId": "582f4f8d-71e9-4a5c-a164-9d2056318d6c",
"description": "Shopify source connection",
"data": {
"format": "tabular"
},
"params": {
"tableName": "Shopify.Orders",
"columns": [
{
"name": "Email",
"type": "string"
},
{
"name": "Phone",
"type": "string"
},
]
},
"connectionSpec": {
"id": "4f63aa36-bd48-4e33-bb83-49fbcd11c708",
"version": "1.0"
}
}'
baseConnectionIdparams.pathconnectionSpec.idRisposta
In caso di esito positivo, la risposta restituisce l’identificatore univoco (id) della connessione sorgente appena creata. Questo ID è necessario nei passaggi successivi per creare una connessione di destinazione.
{
"id": "c278ab14-acdf-440b-b67f-1265d15a7655",
"etag": "\"10007c3f-0000-0200-0000-5fa9be720000\""
}
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 arrivano i dati acquisiti. Per creare una connessione di destinazione, devi fornire l’ID della specifica di connessione fissa associato al Data Lake. L'ID della specifica di connessione è: 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. Utilizzo di Flow Service API, puoi creare una connessione di destinazione specificando questi identificatori insieme al set di dati che conterrà i dati di origine in entrata.
Formato API
POST /targetConnections
Richiesta
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": "Shopify target connection",
"description": "Shopify target connection",
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/854ddc36ad2c7bd001f66a4392575ed4004f81883328772f",
"version": "application/vnd.adobe.xed-full-notext+json; version=1"
}
},
"params": {
"dataSetId": "5fa9c083de62e418dd170b42"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
data.schema.id$id dello schema XDM di destinazione.data.schema.versionapplication/vnd.adobe.xed-full+json;version=1, che restituisce la versione secondaria più recente dello schema.params.dataSetIdconnectionSpec.idc604ff05-7f1a-43c0-8e18-33bf874cb11c.Risposta
In caso di esito positivo, la risposta restituisce l’identificatore univoco della nuova connessione di destinazione (id). Questo valore è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "6c0ba537-a96b-4d74-8c95-450eb88baee8",
"etag": "\"00005506-0000-0200-0000-5fa9c13c0000\""
}
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.
Per creare un set di mappatura, effettua una richiesta POST al mappingSets endpoint del Data Prep API mentre fornisci lo schema XDM di destinazione $id e i dettagli dei set di mappatura da creare.
Formato API
POST /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 '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/854ddc36ad2c7bd001f66a4392575ed4004f81883328772f",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "personalEmail.address",
"sourceAttribute": "Email",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "mobilePhone.number",
"sourceAttribute": "Shipping_Address_Phone",
"identity": false,
"version": 0
}
]
}'
xdmSchema$id dello schema XDM di destinazione.Risposta
In caso di esito positivo, la risposta restituisce i dettagli della mappatura appena creata, compreso l’identificatore univoco (id). Questo ID è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "22922102bffd4369b6209c102a604062",
"version": 0,
"createdDate": 1604960750613,
"modifiedDate": 1604960750613,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Cerca specifiche del flusso di dati specs
Un flusso di dati è responsabile della raccolta dei dati dalle origini e della loro immissione in Platform. Per creare un flusso di dati, devi prima ottenere le specifiche del flusso di dati eseguendo una richiesta di GET al Flow Service API. Le specifiche del flusso di dati sono responsabili della raccolta dei dati da un’origine e-commerce.
Formato API
GET /flowSpecs?property=name=="CRMToAEP"
Richiesta
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="CRMToAEP"' \
-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 specifica del flusso di dati responsabili dell’importazione di dati dall’origine in Platform. La risposta include le specifiche di flusso univoche id necessario per creare un nuovo flusso di dati.
| code language-json |
|---|
|
Creare un flusso di dati
L’ultimo passaggio per la raccolta dei dati consiste nel creare un flusso di dati. A questo punto, è necessario preparare 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 della richiesta.
Per pianificare un’acquisizione, devi prima impostare il valore dell’ora di inizio su tempo epoca in secondi. Quindi, è necessario impostare il valore della frequenza su una delle cinque opzioni seguenti: once, minute, hour, day, o week. Il valore di intervallo indica il periodo tra due acquisizioni consecutive e la creazione di un’acquisizione una tantum non richiede l’impostazione di un intervallo. Per tutte le altre frequenze, il valore dell'intervallo deve essere impostato su uguale o maggiore di 15.
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": "Test Shopify dataflow",
"description": "Shopify With mapping ingestion",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"c278ab14-acdf-440b-b67f-1265d15a7655"
],
"targetConnectionIds": [
"6c0ba537-a96b-4d74-8c95-450eb88baee8"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "22922102bffd4369b6209c102a604062",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1604961070",
"frequency": "once"
}
}'
flowSpec.idsourceConnectionIdstargetConnectionIdstransformations.params.mappingIdtransformations.params.mappingIdscheduleParams.startTimescheduleParams.frequencyfrequency in cui il flusso di dati raccoglierà i dati. I valori accettabili includono: once, minute, hour, day, o week.scheduleParams.intervalfrequency è impostato come once e deve essere maggiore o uguale a 15 per altri frequency valori.Risposta
In caso di esito positivo, la risposta restituisce l’ID id del flusso di dati appena creato.
{
"id": "20c115bc-46e3-40f3-bfe9-fb25abe4ba76",
"etag": "\"030018cb-0000-0200-0000-5fa9c31a0000\""
}
Monitorare il flusso di dati
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 ulteriori informazioni su come monitorare i flussi di dati, consulta l’esercitazione su monitoraggio dei flussi di dati nell’API
Passaggi successivi
Seguendo questa esercitazione, hai creato un connettore di origine per raccogliere i dati di e-commerce su base pianificata. I dati in arrivo possono ora essere utilizzati da downstream Platform servizi quali Real-Time Customer Profile e Data Science Workspace. Per ulteriori informazioni, consulta i seguenti documenti: