Questa esercitazione ti aiuterà a iniziare a utilizzare le API Streaming Ingestion, parte delle API di Adobe Experience Platform Data Ingestion Service.
Questa esercitazione richiede una buona conoscenza dei vari servizi Adobe Experience Platform. Prima di iniziare questa esercitazione, consulta la documentazione relativa ai seguenti servizi:
{TENANT_ID}
, visualizzato nelle chiamate durante questa esercitazione, e la conoscenza di come creare schemi, che viene utilizzato nella creazione di un set di dati per l’acquisizione.Inoltre, questa esercitazione richiede che sia già stata creata una connessione in streaming. Per ulteriori informazioni sulla creazione di una connessione in streaming, leggi l' esercitazione sulla connessione in streaming.
Le sezioni seguenti forniscono informazioni aggiuntive che dovrai conoscere per effettuare correttamente le chiamate alle API di acquisizione in streaming.
Questa guida fornisce esempi di chiamate API per dimostrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richiesta formattati correttamente. Viene inoltre fornito un esempio di codice JSON restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere le chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform .
Per effettuare chiamate alle API Platform, devi prima completare l’ esercitazione sull’autenticazione. Il completamento dell’esercitazione di autenticazione fornisce i valori per ciascuna delle intestazioni richieste in tutte le chiamate API Experience Platform, come mostrato di seguito:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Tutte le risorse in Experience Platform sono isolate in sandbox virtuali specifiche. Tutte le richieste alle API Platform richiedono un’intestazione che specifichi il nome della sandbox in cui avrà luogo l’operazione:
{SANDBOX_NAME}
Per ulteriori informazioni sulle sandbox in Platform, consulta la documentazione di panoramica sandbox.
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:
Per creare un set di dati, devi innanzitutto creare un nuovo schema che implementi la classe XDM ExperienceEvent . Per ulteriori informazioni sulla creazione degli schemi, consulta la Guida per gli sviluppatori API del Registro di sistema .
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"type": "object",
"title": "{SCHEMA_NAME}",
"description": "{SCHEMA_DESCRIPTION}",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/experienceevent"
},
{
"$ref": "https://ns.adobe.com/xdm/context/experienceevent-environment-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/experienceevent-commerce"
},
{
"$ref":"https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details"
}
],
"meta:immutableTags": [
"union"
]
}'
Proprietà | Descrizione |
---|---|
title |
Nome da utilizzare per lo schema. Questo nome deve essere univoco. |
description |
Una descrizione significativa dello schema che si sta creando. |
meta:immutableTags |
In questo esempio, il tag union viene utilizzato per mantenere i dati in Real-time Customer Profile. |
Risposta
Una risposta corretta restituisce lo stato HTTP 201 con i dettagli del nuovo schema creato.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"meta:altId": "_{TENANT_ID}.schemas.{SCHEMA_ID}",
"meta:resourceType": "schemas",
"version": "{SCHEMA_VERSION}",
"type": "object",
"title": "{SCHEMA_NAME}",
"description": "{SCHEMA_DESCRIPTION}",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/experienceevent",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/experienceevent-commerce",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details",
"type": "object",
"meta:xdmType": "object"
}
],
"refs": [
"https://ns.adobe.com/xdm/context/experienceevent-commerce",
"https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details",
"https://ns.adobe.com/xdm/context/experienceevent-environment-details",
"https://ns.adobe.com/xdm/context/experienceevent"
],
"imsOrg": "{IMS_ORG}",
"meta:immutableTags": [
"union"
],
"meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
"required": [
"@id",
"xdm:timestamp"
],
"meta:abstract": false,
"meta:extensible": false,
"meta:extends": [
"https://ns.adobe.com/xdm/context/experienceevent",
"https://ns.adobe.com/xdm/data/time-series",
"https://ns.adobe.com/xdm/context/identitymap",
"https://ns.adobe.com/xdm/context/experienceevent-environment-details",
"https://ns.adobe.com/xdm/context/experienceevent-commerce",
"https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details"
],
"meta:containerId": "tenant",
"imsOrg": "{IMS_ORG}",
"meta:xdmType": "object",
"meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
"meta:registryMetadata": {
"repo:createDate": 1551229957987,
"repo:lastModifiedDate": 1551229957987,
"xdm:createdClientId": "{CLIENT_ID}",
"xdm:repositoryCreatedBy": "{CREATED_BY}"
},
"meta:tenantNamespace": "{NAMESPACE}"
}
Proprietà | Descrizione |
---|---|
{TENANT_ID} |
Questo ID viene utilizzato per garantire che le risorse create siano spaccate correttamente e contenute all’interno dell’organizzazione IMS. Per ulteriori informazioni sull'ID tenant, consulta la guida del Registro di sistema dello schema. |
Prendi nota degli attributi $id
e version
, in quanto entrambi verranno utilizzati durante la creazione del set di dati.
Quindi, aggiungi un descrittore di identità allo schema creato sopra, utilizzando l'attributo dell'indirizzo e-mail di lavoro come identificatore principale. Ciò comporterà due modifiche:
L’indirizzo e-mail di lavoro diventerà un campo obbligatorio. Ciò significa che i messaggi inviati senza questo campo non possono essere convalidati e non verranno acquisiti.
Real-time Customer Profile utilizzerà l'indirizzo e-mail di lavoro come identificatore per unire più informazioni su quell'individuo.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"@type":"xdm:descriptorIdentity",
"xdm:sourceProperty":"/_experience/campaign/message/profileSnapshot/workEmail/address",
"xdm:property":"xdm:code",
"xdm:isPrimary":true,
"xdm:namespace":"Email",
"xdm:sourceSchema":"{SCHEMA_REF_ID}",
"xdm:sourceVersion":1
}
Proprietà | Descrizione |
---|---|
{SCHEMA_REF_ID} |
Il $id ricevuto in precedenza al momento della composizione dello schema. Dovrebbe assomigliare a questo: "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}" |
Codici dello spazio dei nomi identità
Assicurati che i codici siano validi - l'esempio precedente utilizza "email" che è uno spazio dei nomi di identità standard. Altri namespace di identità standard comunemente utilizzati si trovano nelle Domande frequenti sul servizio Identity.
Per creare uno spazio dei nomi personalizzato, segui i passaggi descritti nella panoramica dello spazio dei nomi di identità.
Risposta
Una risposta corretta restituisce lo stato HTTP 201 con informazioni sullo spazio dei nomi di identità principale 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": "/_experience/campaign/message/profileSnapshot/workEmail/address",
"@id": "ec31c09e0906561861be5a71fcd964e29ebe7923b8eb0d1e",
"meta:containerId": "tenant",
"version": "1",
"imsOrg": "{IMS_ORG}"
}
Una volta creato lo schema, dovrai creare un set di dati per acquisire i dati dei record.
Questo set di dati verrà abilitato per Real-time Customer Profile e Identity impostando i tag appropriati.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "{DATASET_NAME}",
"description": "{DATASET_DESCRIPTION}",
"schemaRef": {
"id": "{SCHEMA_REF_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
},
"fileDescription": {
"persisted": true,
"containerFormat": "parquet",
"format": "parquet"
},
"tags": {
"unifiedIdentity": ["enabled:true"],
"unifiedProfile": ["enabled:true"]
}
}'
Risposta
Una risposta corretta restituisce lo stato HTTP 201 e un array contenente l'ID del set di dati appena creato nel formato @/dataSets/{DATASET_ID}
.
[
"@/dataSets/5e72608b10f6e318ad2dee0f"
]
Con il set di dati e la connessione in streaming attivo, puoi acquisire record JSON in formato XDM per acquisire dati di serie temporali all’interno di Platform.
Formato API
POST /collection/{CONNECTION_ID}?synchronousValidation=true
Parametro | Descrizione |
---|---|
{CONNECTION_ID} |
Il valore id della nuova connessione streaming creata. |
synchronousValidation |
Parametro di query facoltativo destinato a scopi di sviluppo. Se impostato su true , può essere utilizzato per un feedback immediato per determinare se la richiesta è stata inviata correttamente. Per impostazione predefinita, questo valore è impostato su false . |
Richiesta
È possibile inserire dati di serie temporali in una connessione streaming con o senza il nome sorgente.
La richiesta di esempio riportata di seguito acquisisce i dati delle serie temporali con un nome sorgente mancante in Platform. Se ai dati manca il nome sorgente, aggiungerà l’ID sorgente dalla definizione della connessione in streaming.
Sarà necessario generare i propri xdmEntity._id
e xdmEntity.timestamp
. Un buon modo per generare un ID è quello di utilizzare la funzione UUID in Preparazione dati. Ulteriori informazioni sulla funzione UUID sono disponibili nella Guida alle funzioni di preparazione dei dati. L'attributo xdmEntity._id
rappresenta un identificatore univoco per il record stesso, not un ID univoco della persona o del dispositivo di cui è il record. L’ID persona o dispositivo sarà specifico in tutti gli attributi assegnati come identificatore di persona o dispositivo dello schema.
Sia xdmEntity._id
che xdmEntity.timestamp
sono gli unici campi obbligatori per i dati relativi alle serie temporali. Inoltre, la seguente chiamata API non richiede intestazioni di autenticazione.
curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?synchronousValidation=true \
-H "Content-Type: application/json" \
-d '{
"header": {
"schemaRef": {
"id": "{SCHEMA_REF_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
},
"imsOrgId": "{IMS_ORG}",
"datasetId": "{DATASET_ID}"
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
}
},
"xdmEntity":{
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla\/5.0 (Windows NT 5.1) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/29.0.1547.57 Safari\/537.36 OPR\/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Fernie Snow",
"quantity": 30,
"priceTotal": 7.8
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail":{
"address": "janedoe@example.com"
}
}
}
}
}
}
}
}'
Per 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={SCHEMA_VERSION}"
},
"imsOrgId": "{IMS_ORG}",
"datasetId": "{DATASET_ID}",
"source": {
"name": "Sample source name"
}
}
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con i dettagli del nuovo streaming Profile.
{
"inletId": "{CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507,
"synchronousValidation": {
"status": "pass"
}
}
Proprietà | Descrizione |
---|---|
{CONNECTION_ID} |
ID della connessione in streaming creata in precedenza. |
xactionId |
Un identificatore univoco generato lato server per il record appena inviato. Questo ID consente ad Adobe di tracciare il ciclo di vita di questo record attraverso vari sistemi e con il debug. |
receivedTimeMs : Una marca temporale (epoch in millisecondi) che mostra a che ora è stata ricevuta la richiesta. |
|
synchronousValidation.status |
Poiché è stato aggiunto il parametro di query synchronousValidation=true , questo valore viene visualizzato. Se la convalida è riuscita, lo stato sarà pass . |
Per convalidare i record acquisiti in precedenza, puoi utilizzare Profile Access API per recuperare i dati delle serie temporali. Questo può essere fatto utilizzando una richiesta GET all’ endpoint /access/entities
e utilizzando parametri di query facoltativi. È possibile utilizzare più parametri, separati da e commerciale (&)."
Se l'ID del criterio di unione non è definito e il schema.name
o relatedSchema.name
è _xdm.context.profile
, Profile Access recupererà le identità correlate all.
Formato API
GET /access/entities
GET /access/entities?{QUERY_PARAMETERS}
GET /access/entities?schema.name=_xdm.context.experienceevent&relatedSchema.name=_xdm.context.profile&relatedEntityId=janedoe@example.com&relatedEntityIdNS=email
Parametro | Descrizione |
---|---|
schema.name |
Obbligatorio. Nome dello schema a cui si accede. |
relatedSchema.name |
Obbligatorio. Poiché si accede a un _xdm.context.experienceevent , questo valore specifica lo schema per l'entità profilo a cui sono correlati gli eventi delle serie temporali. |
relatedEntityId |
ID dell’entità correlata. Se fornito, è necessario fornire anche lo spazio dei nomi dell’entità. |
relatedEntityIdNS |
Spazio dei nomi dell'ID che si sta tentando di recuperare. |
Richiesta
curl -X GET \
https://platform-stage.adobe.io/data/core/ups/access/entities?schema.name=_xdm.context.experienceevent&relatedSchema.name=_xdm.context.profile&relatedEntityId=janedoe@example.com&relatedEntityIdNS=email \
-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}"
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con i dettagli delle entità richieste. Come puoi vedere, si tratta degli stessi dati della serie temporale precedentemente acquisiti.
{
"_page": {
"orderby": "timestamp",
"start": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"count": 1,
"next": ""
},
"children": [
{
"relatedEntityId": "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA",
"entityId": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": 1582495621000,
"entity": {
"environment": {
"browserDetails": {
"javaScriptVersion": "1.6",
"cookiesEnabled": true,
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"commerce": {
"productViews": {
"value": 1
}
},
"productListItems": [
{
"name": "Fernie Snow",
"quantity": 30,
"SKU": "CC",
"priceTotal": 7.8
}
],
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "janedoe@example.com"
}
}
}
}
},
"timestamp": "2020-02-23T22:07:01Z"
},
"lastModifiedAt": "2020-03-18T18:51:19Z"
}
],
"_links": {
"next": {
"href": ""
}
}
}
Leggendo questo documento, ora puoi imparare a inserire dati di record in Platform utilizzando le connessioni di streaming. Puoi provare a effettuare più chiamate con valori diversi e recuperare i valori aggiornati. Inoltre, puoi iniziare a monitorare i dati acquisiti tramite l’ Platform interfaccia utente. Per ulteriori informazioni, consulta la guida monitoring data ingestion .
Per ulteriori informazioni sull'acquisizione in streaming in generale, consulta la panoramica sull'acquisizione in streaming.