Questa esercitazione descrive i passaggi per recuperare i dati da un CRM di terze parti e trasferirli in Adobe Experience Platform tramite connettori di origine e l'API Flow Service.
Questa esercitazione richiede l'accesso a un sistema CRM di terze parti tramite una connessione valida e informazioni sulla tabella che desideri portare in Piattaforma, incluso il percorso e la struttura della tabella. Se non disponi di queste informazioni, consulta l'esercitazione su come esplorare i sistemi CRM utilizzando l'API del servizio di flusso prima di provare a seguire questa esercitazione.
Questa esercitazione richiede inoltre di conoscere i seguenti componenti di Adobe Experience Platform:
{TENANT_ID}
, il concetto di "contenitori" e le intestazioni necessarie per effettuare le richieste (con particolare attenzione all'intestazione Accetta e ai relativi valori possibili).Le sezioni seguenti forniscono informazioni aggiuntive che sarà necessario conoscere per collegarsi correttamente a un sistema CRM utilizzando l'API Flow Service.
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, consultate la sezione relativa a come leggere chiamate API di esempio nella guida alla risoluzione dei problemi del Experience Platform .
Per effettuare chiamate alle API della piattaforma, è innanzitutto necessario completare l'esercitazione sull'autenticazione a1/>. 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:
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}
Tutte le risorse in Experience Platform, incluse quelle appartenenti a Flow Service, sono isolate in sandbox virtuali specifiche. Tutte le richieste alle API della piattaforma richiedono un'intestazione che specifica il nome della sandbox in cui avrà luogo l'operazione:
x-sandbox-name: {SANDBOX_NAME}
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un'intestazione aggiuntiva per il tipo di supporto:
Content-Type: application/json
È possibile creare una connessione di origine effettuando una richiesta di POST all'API Flow Service. Una connessione di origine è costituita da un ID connessione, un percorso al file di dati di origine e un ID di specifica di connessione.
Per creare una connessione di origine, è inoltre necessario definire un valore enum per l'attributo del formato dati.
Utilizzate i seguenti valori enum per i connettori basati su file:
Formato dati | Valore Enum |
---|---|
Delimitato | delimited |
JSON | json |
Parquet | parquet |
Per tutti i connettori basati su tabelle, impostate 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Salesforce source connection",
"baseConnectionId": "4cb0c374-d3bb-4557-b139-5712880adc55",
"description": "Salesforce source connection",
"data": {
"format": "tabular",
},
"params": {
"tableName": "Accounts",
"columns": [
{
"name": "first_name",
"type": "string",
"xdm": {
"type": "String"
}
},
{
"name": "last_name",
"type": "string",
"xdm": {
"type": "String"
}
},
{
"name": "email",
"type": "string",
"xdm": {
"type": "String"
}
}
]
},
"connectionSpec": {
"id": "ccfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"version": "1.0"
}
}'
Proprietà | Descrizione |
---|---|
baseConnectionId |
L'ID di connessione univoco del sistema CRM di terze parti a cui si accede. |
params.path |
Percorso del file di origine. |
connectionSpec.id |
L'ID della specifica di connessione associato al sistema CRM di terze parti specifico. Per un elenco degli ID delle specifiche di connessione, vedere l' appendice. |
Risposta
Una risposta corretta restituisce l'identificatore univoco (id
) della connessione di origine appena creata. Questo ID è richiesto in un passaggio successivo per creare un flusso di dati.
{
"id": "9a603322-19d2-4de9-89c6-c98bd54eb184"
"etag": "\"4a00038b-0000-0200-0000-5ebc47fd0000\""
}
Affinché i dati di origine siano utilizzati in Piattaforma, è necessario creare uno schema di destinazione per strutturare i dati di origine in base alle esigenze. Lo schema di destinazione viene quindi utilizzato per creare un set di dati della piattaforma in cui sono contenuti i dati di origine. Questo schema XDM di destinazione estende anche la classe XDM Individual Profile.
È possibile creare uno schema XDM di destinazione eseguendo una richiesta POST all'API del Registro di sistema Schema.
Formato API
POST /schemaregistry/tenant/schemas
Richiesta
La seguente richiesta di esempio crea uno schema XDM che estende la classe di profilo singolo XDM.
curl -X POST \
'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
-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 '{
"type": "object",
"title": "Salesforce target XDM schema",
"description": "Salesforce target XDM schema",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
}
],
"meta:containerId": "tenant",
"meta:resourceType": "schemas",
"meta:xdmType": "object",
"meta:class": "https://ns.adobe.com/xdm/context/profile"
}'
Risposta
Una risposta corretta restituisce i dettagli dello schema appena creato, compreso l'identificatore univoco ($id
). Questo ID è richiesto nei passaggi successivi per creare un set di dati di destinazione, una mappatura e un flusso di dati.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/417a33eg81a221bd10495920574gfa2d",
"meta:altId": "{TENANT_ID}.schemas.417a33eg81a221bd10495920574gfa2d",
"meta:resourceType": "schemas",
"version": "1.0",
"title": "Salesforce target XDM schema",
"description": "",
"type": "object",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
}
],
"meta:xdmType": "object",
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/xdm/context/profile",
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details"
],
"meta:containerId": "tenant",
"meta:registryMetadata": {
"eTag": "6m/FrIlXYU2+yH6idbcmQhKSlMo="
}
}
È possibile creare un set di dati di destinazione eseguendo una richiesta POST all' API del servizio catalogo, fornendo l'ID dello schema di destinazione all'interno del payload.
Formato API
POST /catalog/dataSets
Richiesta
curl -X POST \
'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
-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": "Salesforce target dataset",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/417a33eg81a221bd10495920574gfa2d",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
}
}'
Proprietà | Descrizione |
---|---|
schemaRef.id |
ID dello schema XDM di destinazione. |
Risposta
Una risposta corretta restituisce un array contenente l’ID del set di dati appena creato nel formato "@/datasets/{DATASET_ID}"
. L’ID del set di dati è una stringa di sola lettura generata dal sistema che viene utilizzata per fare riferimento al set di dati nelle chiamate API. L’ID del set di dati di destinazione è richiesto nei passaggi successivi per creare una connessione di destinazione e un flusso di dati.
[
"@/dataSets/5c8c3c555033b814b69f947f"
]
Una connessione di destinazione rappresenta la connessione alla destinazione in cui i dati acquisiti entrano. Per creare una connessione di destinazione, è necessario fornire l'ID di specifica di connessione fisso associato al Data Lake. Questo ID della specifica di connessione è: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Ora sono disponibili gli identificatori univoci, uno schema di destinazione, un set di dati di destinazione e l'ID delle specifiche di connessione al data Lake. Utilizzando l'API Flow Service, potete creare una connessione di destinazione specificando questi identificatori insieme al dataset che conterrà i dati di origine in ingresso.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Salesforce target connection",
"description": "Salesforce target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/417a33eg81a221bd10495920574gfa2d",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "5c8c3c555033b814b69f947f"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
Proprietà | Descrizione |
---|---|
data.schema.id |
$id dello schema XDM di destinazione. |
params.dataSetId |
ID del set di dati di destinazione. |
connectionSpec.id |
ID della specifica di connessione utilizzata per connettersi al Data Lake. Questo ID è: c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
{
"id": "4ee890c7-519c-4291-bd20-d64186b62da8",
"etag": "\"2a007aa8-0000-0200-0000-5e597aaf0000\""
}
Affinché i dati di origine siano assimilati in un set di dati di destinazione, devono essere mappati sullo schema di destinazione a cui aderisce il set di dati di destinazione. Questo si ottiene eseguendo una richiesta POST all'API Conversion Service con mappature dati definite all'interno del 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/417a33eg81a221bd10495920574gfa2d",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "first_name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "last_name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "personalEmail.address",
"sourceAttribute": "email",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
Proprietà | Descrizione |
---|---|
xdmSchema |
ID dello schema XDM di destinazione. |
Risposta
Una risposta corretta restituisce i dettagli della nuova mappatura creata, incluso il relativo identificatore univoco (id
). Questo valore è richiesto in un passaggio successivo per creare un flusso di dati.
{
"id": "500a9b747fcf4908a21917d49bd61780",
"version": 0,
"createdDate": 1591043336298,
"modifiedDate": 1591043336298,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Un flusso di dati è responsabile della raccolta di dati da origini e del loro inserimento in Piattaforma. Per creare un flusso di dati, devi innanzitutto ottenere le specifiche del flusso di dati che sono responsabili della raccolta dei dati CRM.
Formato API
GET /flowSpecs?property=name=="CRMToAEP"
Richiesta
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CRMToAEP%22' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce i dettagli della specifica del flusso di dati responsabile dell'inserimento dei dati dall'origine nella piattaforma. La risposta include la specifica di flusso univoca id
necessaria per creare un nuovo flusso di dati.
{
"items": [
{
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"name": "CRMToAEP",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"sourceConnectionSpecIds": [
"3416976c-a9ca-4bba-901a-1f08f66978ff",
"38ad80fe-8b06-4938-94f4-d4ee80266b07",
"d771e9c1-4f26-40dc-8617-ce58c4b53702",
"3c9b37f8-13a6-43d8-bad3-b863b941fedd",
"cc6a4487-9e91-433e-a3a3-9cf6626c1806",
"3000eb99-cd47-43f3-827c-43caf170f015",
"26d738e0-8963-47ea-aadf-c60de735468a",
"74a1c565-4e59-48d7-9d67-7c03b8a13137",
"cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"4f63aa36-bd48-4e33-bb83-49fbcd11c708",
"cb66ab34-8619-49cb-96d1-39b37ede86ea",
"eb13cb25-47ab-407f-ba89-c0125281c563",
"1f372ff9-38a4-4492-96f5-b9a4e4bd00ec",
"37b6bf40-d318-4655-90be-5cd6f65d334b",
"a49bcc7d-8038-43af-b1e4-5a7a089a7d79",
"221c7626-58f6-4eec-8ee2-042b0226f03b",
"a8b6a1a4-5735-42b4-952c-85dce0ac38b5",
"6a8d82bc-1caf-45d1-908d-cadabc9d63a6",
"aac9bbd4-6c01-46ce-b47e-51c6f0f6db3f",
"8e6b41a8-d998-4545-ad7d-c6a9fff406c3",
"ecde33f2-c56f-46cc-bdea-ad151c16cd69",
"102706fb-a5cd-42ee-afe0-bc42f017ff43",
"09182899-b429-40c9-a15a-bf3ddbc8ced7",
"0479cc14-7651-4354-b233-7480606c2ac3",
"d6b52d86-f0f8-475f-89d4-ce54c8527328",
"a8f4d393-1a6b-43f3-931f-91a16ed857f4",
"1fe283f6-9bec-11ea-bb37-0242ac130002"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"optionSpec": {
"name": "OptionSpec",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"errorDiagnosticsEnabled": {
"title": "Error diagnostics.",
"description": "Flag to enable detailed and sample error diagnostics summary.",
"type": "boolean",
"default": false
},
"partialIngestionPercent": {
"title": "Partial ingestion threshold.",
"description": "Percentage which defines the threshold of errors allowed before the run is marked as failed.",
"type": "number",
"exclusiveMinimum": 0
}
}
}
},
"transformationSpecs": [
{
"name": "Copy",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"deltaColumn": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"dateFormat": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"required": [
"name"
]
}
},
"required": [
"deltaColumn"
]
}
},
{
"name": "Mapping",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for different mapping from source to target",
"properties": {
"mappingId": {
"type": "string"
},
"mappingVersion": {
"type": "string"
}
}
}
}
],
"scheduleSpec": {
"name": "PeriodicSchedule",
"type": "Periodic",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"startTime": {
"description": "epoch time",
"type": "integer"
},
"frequency": {
"type": "string",
"enum": [
"once",
"minute",
"hour",
"day",
"week"
]
},
"interval": {
"type": "integer"
},
"backfill": {
"type": "boolean",
"default": true
}
},
"required": [
"startTime",
"frequency"
],
"if": {
"properties": {
"frequency": {
"const": "once"
}
}
},
"then": {
"allOf": [
{
"not": {
"required": [
"interval"
]
}
},
{
"not": {
"required": [
"backfill"
]
}
}
]
},
"else": {
"required": [
"interval"
],
"if": {
"properties": {
"frequency": {
"const": "minute"
}
}
},
"then": {
"properties": {
"interval": {
"minimum": 15
}
}
},
"else": {
"properties": {
"interval": {
"minimum": 1
}
}
}
}
}
},
"attributes": {
"notification": {
"category": "sources",
"flowRun": {
"enabled": true
}
}
},
"permissionsInfo": {
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
],
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
]
}
}
]
}
L'ultimo passaggio per la raccolta dei dati CRM è 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 dei dati da un'origine. È possibile creare un flusso di dati eseguendo una richiesta di POST fornendo al contempo i valori indicati in precedenza all'interno del payload.
Per pianificare un'assimilazione, è innanzitutto necessario impostare il valore dell'ora di inizio in modo che l'ora dell'epoch sia espressa in secondi. Quindi, è necessario impostare il valore della frequenza su una delle cinque opzioni: once
, minute
, hour
, day
o week
. Il valore dell'intervallo indica il periodo tra due assimilazioni consecutive e la creazione di un'assimilazione 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Salesforce dataflow",
"description": "Salesforce dataflow",
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
},
"sourceConnectionIds": [
"9a603322-19d2-4de9-89c6-c98bd54eb184"
],
"targetConnectionIds": [
"4ee890c7-519c-4291-bd20-d64186b62da8"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "updatedAt",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "500a9b747fcf4908a21917d49bd61780"
}
}
],
"scheduleParams": {
"startTime": "1567411548",
"frequency":"minute",
"interval":"30"
}
}'
Proprietà | Descrizione |
---|---|
flowSpec.id |
ID specifica di flusso recuperato nel passaggio precedente. |
sourceConnectionIds |
L' ID connessione di origine recuperato in un passaggio precedente. |
targetConnectionIds |
L' ID connessione di destinazione recuperato in un passaggio precedente. |
transformations.params.mappingId |
L' ID di mappatura recuperato in un passaggio precedente. |
transformations.params.deltaColum |
Colonna designata utilizzata per distinguere tra dati nuovi ed esistenti. I dati incrementali verranno acquisiti in base alla marca temporale della colonna selezionata. Il formato supportato per deltaColumn è yyyy-MM-dd HH:mm:ss . Se si utilizza Microsoft Dynamics, il formato supportato per deltaColumn è yyyy-MM-ddTHH:mm:ssZ . |
transformations.params.mappingId |
L'ID di mappatura associato al database. |
scheduleParams.startTime |
Ora di inizio per il flusso di dati in epoch time. |
scheduleParams.frequency |
Frequenza con cui il flusso di dati raccoglie i dati. I valori accettabili sono: once , minute , hour , day o week . |
scheduleParams.interval |
L'intervallo indica il periodo tra due esecuzioni di flusso consecutive. Il valore dell'intervallo deve essere un numero intero diverso da zero. L'intervallo non è richiesto quando la frequenza è impostata come once e deve essere maggiore o uguale a 15 per gli altri valori di frequenza. |
Risposta
Una risposta corretta restituisce l'ID (id
) del flusso di dati appena creato.
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
Una volta creato il flusso di dati, è possibile monitorare i dati che vengono acquisiti attraverso di esso per visualizzare informazioni sulle esecuzioni del flusso, lo stato di completamento e gli errori. Per ulteriori informazioni su come monitorare i flussi di dati, vedete l'esercitazione sui flussi di dati di monitoraggio nell'API
Seguendo questa esercitazione, hai creato un connettore di origine per raccogliere dati da un sistema CRM su base programmata. I dati in entrata possono ora essere utilizzati dai servizi della piattaforma a valle, quali Real-time Customer Profile e Data Science Workspace. Per ulteriori informazioni, consulta i documenti seguenti:
Nella sezione seguente sono elencati i diversi connettori di origine CRM e le relative specifiche di connessione.
Nome connettore | Specifica di connessione |
---|---|
Microsoft Dynamics | 38ad80fe-8b06-4938-94f4-d4ee80266b07 |
Salesforce | cfc0fee1-7dc0-40ef-b73e-d8b134c436f5 |