Creare un flusso di dati per acquisire dati da un sistema CRM in Experience Platform
Leggi questa guida per scoprire come creare un flusso di dati e acquisire dati in Adobe Experience Platform utilizzando Flow Service API.
Introduzione
Questa guida richiede una buona conoscenza dei seguenti componenti di Experience Platform:
- Acquisizione batch: scopri come caricare in modo rapido ed efficiente grandi volumi di dati in batch.
- Catalog Service: organizza e tieni traccia dei set di dati in Experience Platform.
- Preparazione dati: trasforma e mappa i dati in arrivo in modo che corrispondano ai requisiti dello schema.
- Flussi dati: imposta e gestisci le pipeline che spostano i dati dalle origini alle destinazioni.
- Schemi Experience Data Model (XDM): struttura i dati utilizzando schemi XDM in modo che siano pronti per l'utilizzo in Experience Platform.
- Sandbox: verifica e sviluppo sicuri in ambienti isolati senza influire sui dati di produzione.
- Origini: scopri come collegare le tue origini dati esterne ad Experience Platform.
Utilizzare le API di Experience Platform
Per informazioni su come effettuare correttamente chiamate alle API di Experience Platform, consulta la guida guida introduttiva alle API di Experience Platform.
Crea connessione di base base
Per creare un flusso di dati per l’origine, è necessario un account di origine completamente autenticato e il relativo ID di connessione di base corrispondente. Se non disponi di questo ID, visita il catalogo origini per trovare un elenco di origini per le quali puoi creare una connessione di base.
Creare uno schema XDM di destinazione target-schema
Uno schema Experience Data Model (XDM) fornisce un modo standardizzato per organizzare e descrivere i dati sull’esperienza del cliente in Experience Platform. Per acquisire i dati di origine in Experience Platform, devi innanzitutto creare uno schema XDM di destinazione che definisca la struttura e i tipi di dati da acquisire. Questo schema funge da blueprint per il set di dati di Experience Platform in cui risiederanno i dati acquisiti.
È possibile creare uno schema XDM di destinazione eseguendo una richiesta POST all'API Schema Registry. Per i passaggi dettagliati su come creare uno schema XDM di destinazione, leggi le seguenti guide:
Una volta creato, lo schema XDM di destinazione $id
sarà necessario in seguito per il set di dati di destinazione e la mappatura.
Creare un set di dati di destinazione target-dataset
Un set di dati è un costrutto di archiviazione e gestione per una raccolta di dati, in genere strutturato come una tabella con colonne (schema) e righe (campi). I dati acquisiti correttamente in Experience Platform vengono memorizzati nel data lake come set di dati. Durante questo passaggio, puoi creare un nuovo set di dati o utilizzarne uno esistente.
È possibile creare un set di dati di destinazione effettuando una richiesta POST all'API Catalog Service, fornendo al tempo stesso l'ID dello schema di destinazione all'interno del payload. Per i passaggi dettagliati su come creare un set di dati di destinazione, consulta la guida su creazione di un set di dati utilizzando l'API.
Formato API
code language-http |
---|
|
Richiesta
L’esempio seguente mostra come creare un set di dati di destinazione abilitato per l’acquisizione di Real-Time Customer Profile. In questa richiesta, la proprietà unifiedProfile
è impostata su true
(nell'oggetto tags
), che indica ad Experience Platform di includere il set di dati nel profilo cliente in tempo reale.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Proprietà | Descrizione |
name |
Un nome descrittivo per il set di dati di destinazione. Utilizza un nome chiaro e univoco per semplificare l’identificazione e la gestione del set di dati nelle operazioni future. |
schemaRef.id |
ID dello schema XDM di destinazione. |
tags.unifiedProfile |
Valore booleano che informa Experience Platform se i dati devono essere acquisiti in Real-Time Customer Profile. |
Risposta
In caso di esito positivo, la risposta restituisce l’ID del set di dati target. Questo ID è necessario in un secondo momento per creare una connessione di destinazione.
code language-json |
---|
|
Creare una connessione sorgente source
Una connessione di origine definisce il modo in cui i dati vengono introdotti in Experience Platform da un’origine esterna. Specifica sia il sistema di origine che il formato dei dati in arrivo e fa riferimento a una connessione di base che contiene i dettagli di autenticazione. Ogni connessione sorgente è univoca per la tua organizzazione.
- Per le origini basate su file (ad esempio le archiviazioni cloud), una connessione di origine può includere impostazioni come delimitatore di colonna, tipo di codifica, tipo di compressione, espressioni regolari per la selezione dei file e se acquisire i file in modo ricorsivo.
- Per le origini basate su tabelle (ad esempio database, CRM e provider di automazione marketing), una connessione di origine può specificare dettagli quali il nome della tabella e le mappature delle colonne.
Per creare una connessione di origine, eseguire una richiesta POST all'endpoint /sourceConnections
dell'API Flow Service e fornire l'ID connessione di base, l'ID specifica connessione e il percorso al file di dati di origine.
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": "ACME source connection",
"description": "A source connection for ACME contact data",
"baseConnectionId": "6990abad-977d-41b9-a85d-17ea8cf1c0e4",
"data": {
"format": "tabular"
},
"params": {
"tableName": "Contact",
"columns": [
{
"name": "TestID",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Name",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Datefield",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"version": "1.0"
}
}'
name
description
baseConnectionId
id
della connessione di base. È possibile recuperare questo ID autenticando l'origine in Experience Platform utilizzando l'API Flow Service.data.format
tabular
per le origini basate su tabelle, ad esempio database, CRM e provider di automazione marketing.params.tableName
params.columns
connectionSpec.id
Risposta
In caso di esito positivo, la risposta restituisce l’ID della connessione sorgente. Questo ID è necessario per creare un flusso di dati e acquisire i dati.
{
"id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
"etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}
Creare una connessione di destinazione target
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 di specifica della connessione fissa associato al data lake. ID della specifica di connessione: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
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": "ACME target connection",
"description": "ACME target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6889f4f89b982b2b90bc1207"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
name
description
data.schema.id
params.dataSetId
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.Mappatura mapping
Quindi, mappa i dati di origine con lo schema di destinazione a cui aderisce il set di dati di destinazione. Per creare una mappatura, effettuare una richiesta POST all'endpoint mappingSets
dell'Data Prep API. Includi l’ID dello schema XDM di destinazione e i dettagli dei set di mappatura che desideri 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/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "TestID",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.fullName",
"sourceAttribute": "Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.birthDate",
"sourceAttribute": "Datefield",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchema
$id
dello schema XDM di destinazione.Risposta
In caso di esito positivo, la risposta restituisce i dettagli della mappatura appena creata, incluso il relativo identificatore univoco (id
). Questo ID è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "93ddfa69c4864d978832b1e5ef6ec3b9",
"version": 0,
"createdDate": 1612309018666,
"modifiedDate": 1612309018666,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Recuperare le specifiche del flusso di dati flow-specs
Prima di poter creare un flusso di dati, è necessario recuperare le specifiche corrispondenti alla sorgente. Per recuperare queste informazioni, effettuare una richiesta GET all'endpoint /flowSpecs
dell'API Flow Service.
Formato API
GET /flowSpecs?property=name=="{NAME}"
property=name=="{NAME}"
Nome della specifica del flusso di dati.
- Per le origini basate su file (ad esempio l'archiviazione cloud), impostare questo valore su
CloudStorageToAEP
. - Per le origini basate su tabelle (ad esempio database, CRM e provider di automazione marketing), impostare questo valore su
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 Experience Platform. La risposta include la specifica di flusso univoca id
necessaria per creare un nuovo flusso di dati.
Per assicurarsi di utilizzare la specifica di flusso di dati corretta, controllare l'array items.sourceConnectionSpecIds
nella risposta. Verificare che l'ID della specifica di connessione per l'origine sia incluso nell'elenco.
code language-json |
---|
|
Creare un flusso di dati dataflow
Un flusso di dati è una pipeline configurata che trasferisce dati tra i servizi di Experience Platform. Definisce il modo in cui i dati vengono acquisiti da origini esterne (come database, archiviazione cloud o API), elaborati e instradati ai set di dati target. Questi set di dati vengono quindi utilizzati da servizi come Identity Service, Real-Time Customer Profile e Destinations per l’attivazione e l’analisi.
Per creare un flusso di dati, devi fornire i valori per i seguenti elementi:
Durante questo passaggio, puoi utilizzare i seguenti parametri in scheduleParams
per configurare una pianificazione di acquisizione per il flusso di dati:
startTime
frequency
La frequenza di acquisizione. Configura la frequenza per indicare la frequenza con cui deve essere eseguito il flusso di dati. Puoi impostare la frequenza su:
once
: imposta la frequenza suonce
per creare un'acquisizione unica. Le impostazioni di intervallo e retrocompilazione non sono disponibili per i processi di acquisizione una tantum. Per impostazione predefinita, la frequenza di pianificazione è impostata su una volta.minute
: imposta la frequenza suminute
per pianificare il flusso di dati per acquisire i dati al minuto.hour
: imposta la frequenza suhour
per pianificare il flusso di dati per acquisire i dati su base oraria.day
: imposta la frequenza suday
per pianificare il flusso di dati per acquisire i dati su base giornaliera.week
: imposta la frequenza suweek
per pianificare il flusso di dati per acquisire i dati settimanalmente.
interval
Intervallo tra acquisizioni consecutive (richiesto per tutte le frequenze eccetto once
). Configura l’impostazione dell’intervallo per stabilire l’intervallo di tempo tra ogni acquisizione. Ad esempio, se la frequenza è impostata su giorno e l’intervallo è 15, il flusso di dati verrà eseguito ogni 15 giorni. Impossibile impostare l'intervallo su zero. Il valore dell'intervallo minimo accettato per ciascuna frequenza è il seguente:
once
: n/dminute
: 15hour
: 1day
: 1week
: 1
backfill
startTime
.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": "ACME Contact Dataflow",
"description": "A dataflow for ACME contact data",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"b7581b59-c603-4df1-a689-d23d7ac440f3"
],
"targetConnectionIds": [
"320f119a-5ac1-4ab1-88ea-eb19e674ea2e"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "Datefield",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "93ddfa69c4864d978832b1e5ef6ec3b9",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1612310466",
"frequency":"minute",
"interval":"15",
"backfill": "true"
}
}'
name
description
flowSpec.id
sourceConnectionIds
targetConnectionIds
transformations.params.deltaColum
deltaColumn
è yyyy-MM-dd HH:mm:ss
. Per Microsoft Dynamics, il formato supportato per deltaColumn
è yyyy-MM-ddTHH:mm:ssZ
.transformations.params.deltaColumn.dateFormat
transformations.params.deltaColumn.timeZone
transformations.params.mappingId
scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
o week
.scheduleParams.interval
scheduleParams.backfill
true
o false
) che determina se acquisire i dati storici (backfill) quando il flusso di dati viene creato per la prima volta.Risposta
In caso di esito positivo, la risposta restituisce l'ID (id
) del flusso di dati appena creato.
{
"id": "ae0a9777-b322-4ac1-b0ed-48ae9e497c7e",
"etag": "\"770029f8-0000-0200-0000-6019e7d40000\""
}
Utilizza l’interfaccia utente per convalidare il flusso di lavoro API validate-in-ui
Puoi utilizzare l’interfaccia utente di Experience Platform per convalidare la creazione del flusso di dati. Passa al catalogo Origini nell'interfaccia utente di Experience Platform, quindi seleziona Flussi dati dalle schede intestazione. Utilizzare quindi la colonna Nome flusso di dati e individuare il flusso di dati creato utilizzando l'API Flow Service.
Puoi convalidare ulteriormente il flusso di dati tramite l'interfaccia Attività flusso di dati. Utilizza la barra a destra per visualizzare le informazioni sull'utilizzo API del flusso di dati. In questa sezione vengono visualizzati lo stesso ID del flusso di dati, lo stesso ID del set di dati e lo stesso ID di mappatura generati durante il processo di creazione del flusso di dati in Flow Service.
Passaggi successivi
Questa esercitazione ti ha guidato nel processo di creazione di un flusso di dati in Experience Platform utilizzando l'API Flow Service. Hai imparato a creare e configurare i componenti necessari, inclusi lo schema XDM di destinazione, il set di dati, la connessione di origine, la connessione di destinazione e il flusso di dati stesso. Seguendo questi passaggi, puoi automatizzare l’acquisizione di dati da origini esterne in Experience Platform, consentendo ai servizi a valle come Real-Time Customer Profile e Destinations di sfruttare i dati acquisiti per casi d’uso avanzati.
Monitorare il flusso di dati
Una volta creato il flusso di dati, puoi monitorarne le prestazioni direttamente nell’interfaccia utente di Experience Platform. Ciò include il tracciamento dei tassi di acquisizione, delle metriche di successo e di eventuali errori che si verificano. Per ulteriori informazioni su come monitorare il flusso di dati, consulta l'esercitazione su account di monitoraggio e flussi di dati.
Aggiornare il flusso di dati
Per aggiornare le configurazioni per la pianificazione, la mappatura o le informazioni generali dei flussi di dati, visita il tutorial su aggiornamento dei flussi di dati di origine.
Eliminare il flusso di dati
È possibile eliminare i flussi di dati non più necessari o creati in modo errato utilizzando la funzione Elimina disponibile nell'area di lavoro Flussi di dati. Per ulteriori informazioni su come eliminare i flussi di dati, consulta l'esercitazione su eliminazione dei flussi di dati.