Trasmettere i dati dei record utilizzando le API Streaming Ingestion
Questa esercitazione ti aiuterà a iniziare a utilizzare le API Streaming Ingestion, parte di Adobe Experience Platform Data Ingestion Service API.
Introduzione
Questo tutorial richiede una conoscenza operativa di vari servizi Adobe Experience Platform. Prima di iniziare questo tutorial, consulta la documentazione dei seguenti servizi:
- Experience Data Model (XDM): il quadro standardizzato mediante il quale Platform organizza i dati dell’esperienza.
- Guida per gli sviluppatori del registro dello schema: guida completa che copre ciascuno degli endpoint disponibili del Schema Registry e come effettuare chiamate. Ciò include la conoscenza
{TENANT_ID}
, che viene visualizzato nelle chiamate di questa esercitazione, oltre a sapere come creare schemi, utilizzati nella creazione di un set di dati per l’acquisizione.
- Guida per gli sviluppatori del registro dello schema: guida completa che copre ciascuno degli endpoint disponibili del Schema Registry e come effettuare chiamate. Ciò include la conoscenza
- Real-Time Customer Profile: fornisce un profilo consumer unificato in tempo reale basato su dati aggregati provenienti da più origini.
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.
Componi uno schema basato su XDM Individual Profile classe
Per creare un set di dati, devi innanzitutto creare un nuovo schema che implementi il XDM Individual Profile classe. Per ulteriori informazioni su come creare schemi, consulta la sezione Guida per gli sviluppatori API del Registro di schema.
Formato API
POST /schemaregistry/tenant/schemas
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"type": "object",
"title": "Sample schema",
"description": "Sample description",
"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-work-details"
}
],
"meta:immutableTags": [
"union"
]
}'
title
description
meta:immutableTags
union
utilizzato per salvare i dati in Real-Time Customer Profile.Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 201 con i dettagli dello schema appena creato.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"meta:altId": "_{TENANT_ID}.schemas.{SCHEMA_ID}",
"meta:resourceType": "schemas",
"version": "1.0",
"type": "object",
"title": "Sample schema",
"description": "Sample description",
"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-work-details"
}
],
"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/data/record",
"https://ns.adobe.com/xdm/cpmtext/identitymap",
"https://ns.adobe.com/xdm/common/extensible",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-work-details"
],
"meta:immutableTags": [
"union"
],
"meta:containerId": "tenant",
"imsOrg": "{ORG_ID}",
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createDate": 1551376506996,
"repo:lastModifiedDate": 1551376506996,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
}
}
{TENANT_ID}
Prendi nota della $id
nonché version
attributi, poiché entrambi verranno utilizzati durante la creazione del set di dati.
Impostare un descrittore di identità primaria per lo schema
Quindi, aggiungi un descrittore di identità allo schema creato in precedenza, utilizzando l’attributo dell’indirizzo e-mail di lavoro come identificatore primario. Questa operazione comporterà due modifiche:
-
L’indirizzo e-mail aziendale diventerà un campo obbligatorio. Ciò significa che i messaggi inviati senza questo campo non supereranno la convalida e non verranno acquisiti.
-
Real-Time Customer Profile utilizzerà l’indirizzo e-mail di lavoro come identificatore per unire più informazioni su quell’individuo.
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"@type":"xdm:descriptorIdentity",
"xdm:sourceProperty":"/workEmail/address",
"xdm:property":"xdm:code",
"xdm:isPrimary":true,
"xdm:namespace":"Email",
"xdm:sourceSchema":"{SCHEMA_REF_ID}",
"xdm:sourceVersion":1
}
{SCHEMA_REF_ID}
$id
ricevuti in precedenza durante la composizione dello schema. Dovrebbe essere simile al seguente: "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}"
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 201 con informazioni sul descrittore di identità primaria appena creato per lo schema.
{
"xdm:property": "xdm:code",
"xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"xdm:namespace": "Email",
"@type": "xdm:descriptorIdentity",
"xdm:sourceVersion": 1,
"xdm:isPrimary": true,
"xdm:sourceProperty": "/workEmail/address",
"@id": "17aaebfa382ce8fc0a40d3e43870b6470aab894e1c368d16",
"meta:containerId": "tenant",
"version": "1",
"imsOrg": "{ORG_ID}"
}
Creare un set di dati per i dati del record
Dopo aver creato lo schema, dovrai creare un set di dati per acquisire i dati del record.
Formato API
POST /catalog/dataSets
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d ' {
"name": "Dataset name",
"description": "Dataset description",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID},
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"tags": {
"unifiedIdentity": ["enabled:true"],
"unifiedProfile": ["enabled:true"]
}
}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 201 e un array contenente l’ID del set di dati appena creato nel formato @/dataSets/{DATASET_ID}
.
[
"@/dataSets/5e30d7986c0cc218a85cee65
]
Creare una connessione in streaming
Dopo aver creato lo schema e il set di dati, puoi creare una connessione in streaming
Per ulteriori informazioni sulla creazione di una connessione in streaming, leggere tutorial sulla creazione di una connessione in streaming.
Acquisire dati di record nella connessione streaming ingest-data
Con il set di dati e la connessione in streaming attivi, puoi acquisire record JSON formattati XDM in cui inserire i dati dei record Platform.
Formato API
POST /collection/{CONNECTION_ID}?syncValidation=true
{CONNECTION_ID}
inletId
valore della connessione streaming creata in precedenza.syncValidation
true
, può essere utilizzato per un feedback immediato per determinare se la richiesta è stata inviata correttamente. Per impostazione predefinita, questo valore è impostato su false
. Tieni presente che se imposti questo parametro di query su true
che la richiesta sarà limitata a 60 volte al minuto per CONNECTION_ID
.Richiesta
L’inserimento di dati record in una connessione in streaming può essere eseguito con o senza il nome dell’origine.
L’esempio di richiesta seguente acquisisce in Platform un record con un nome di origine mancante. Se a un record manca il nome dell’origine, questo aggiungerà l’ID di origine dalla definizione della connessione in streaming.
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?syncValidation=true \
-H "Cache-Control: no-cache" \
-H "Content-Type: application/json" \
-d '{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"flowId": "{FLOW_ID}",
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"xdmEntity": {
"person": {
"name": {
"firstName": "Jane",
"middleName": "F",
"lastName": "Doe"
},
"birthDate": "1969-03-14",
"gender": "female"
},
"workEmail": {
"primary": true,
"address": "janedoe@example.com",
"type": "work",
"status": "active"
}
}
}
}'
Se si desidera includere un nome di origine, nell'esempio seguente viene illustrato come includerlo.
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"source": {
"name": "Sample source name"
}
}
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con dettagli del nuovo flusso Profile.
{
"inletId": "{CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507,
"syncValidation": {
"status": "pass"
}
}
{CONNECTION_ID}
xactionId
receivedTimeMs
syncValidation.status
syncValidation=true
aggiunto, verrà visualizzato questo valore. Se la convalida ha esito positivo, lo stato sarà pass
.Recupera i dati del record appena acquisiti
Per convalidare i record acquisiti in precedenza, puoi utilizzare Profile Access API per recuperare i dati del record.
schema.name
o relatedSchema.name
è _xdm.context.profile
, Profile Access recupererà tutto identità correlate.Formato API
GET /access/entities
GET /access/entities?{QUERY_PARAMETERS}
GET /access/entities?schema.name=_xdm.context.profile&entityId=janedoe@example.com&entityIdNS=email
schema.name
entityId
entityIdNS
Richiesta
Puoi rivedere i dati dei record acquisiti in precedenza con la seguente richiesta GET.
curl -X GET 'https://platform.adobe.io/data/core/ups/access/entities?schema.name=_xdm.context.profile&entityId=janedoe@example.com&entityIdNS=email'\
-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 lo stato HTTP 200 con i dettagli delle entità richieste. Come puoi vedere, si tratta dello stesso record che è stato acquisito correttamente in precedenza.
{
"BVrqzwVv7o2p3naHvnsWpqZXv3KJgA": {
"entityId": "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA",
"mergePolicy": {
"id": "e161dae9-52f0-4c7f-b264-dc43dd903d56"
},
"sources": [
"5e30d7986c0cc218a85cee65"
],
"tags": [
"1580346827274:2478:215"
],
"identityGraph": [
"BVrqzwVv7o2p3naHvnsWpqZXv3KJgA"
],
"entity": {
"person": {
"name": {
"lastName": "Doe",
"middleName": "F",
"firstName": "Jane"
},
"gender": "female",
"birthDate": "1969-03-14"
},
"workEmail": {
"type": "work",
"address": "janedoe@example.com",
"status": "active",
"primary": true
},
"identityMap": {
"email": [
{
"id": "janedoe@example.com"
}
]
}
},
"lastModifiedAt": "2020-01-30T01:13:59Z"
}
}
Passaggi successivi
Una volta letto questo documento, sarai in grado di acquisire i dati dei record in Platform utilizzo di connessioni in streaming. Puoi provare a effettuare più chiamate con valori diversi e a recuperare i valori aggiornati. Inoltre, puoi iniziare a monitorare i dati acquisiti tramite Platform UI. Per ulteriori informazioni, leggere monitoraggio dell’acquisizione dei dati guida.
Per ulteriori informazioni sull’acquisizione in streaming in generale, consulta la sezione panoramica sull’acquisizione in streaming.