Skapa en HTTP API-direktuppspelningsanslutning med Flow Service API
Flow Service används för att samla in och centralisera kunddata från olika källor inom Adobe Experience Platform. Tjänsten tillhandahåller ett användargränssnitt och RESTful API som alla källor som stöds kan anslutas från.
I den här självstudiekursen används Flow Service API för att gå igenom stegen för att skapa en direktuppspelningsanslutning med Flow Service API.
Komma igång
Handboken kräver en fungerande förståelse av följande komponenter i Adobe Experience Platform:
- Experience Data Model (XDM): Det standardiserade ramverk som Platform organiserar upplevelsedata.
- Real-Time Customer Profile: Ger en enhetlig konsumentprofil i realtid baserad på aggregerade data från flera källor.
Om du vill skapa en direktuppspelningsanslutning måste du dessutom ha ett mål-XDM-schema och en datauppsättning. Läs självstudiekursen om du vill veta hur du skapar dessa data för direktuppspelningspost eller självstudiekursen data i tidsserie för direktuppspelning.
Använda plattforms-API:er
Mer information om hur du kan anropa API:er för plattformar finns i handboken komma igång med plattforms-API:er.
Skapa en basanslutning
En basanslutning anger källan och innehåller den information som krävs för att göra flödet kompatibelt med API:er för direktuppspelning. När du skapar en basanslutning kan du välja att skapa en icke-autentiserad och autentiserad anslutning.
Icke-autentiserad anslutning
Icke-autentiserade anslutningar är den standarddirektuppspelningsanslutning som du kan skapa när du vill strömma data till plattformen.
Om du vill skapa en oautentiserad basanslutning skickar du en POST till /connections
slutpunkten när du anger ett namn för anslutningen, datatypen och API-anslutningsspecifikations-ID:t för HTTP. Detta ID är bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.
API-format
POST /flowservice/connections
Begäran
Följande begäran skapar en basanslutning för HTTP API.
code language-shell |
---|
|
code language-shell |
---|
|
name
description
connectionSpec.id
bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.auth.params.dataType
xdm
och raw
.auth.params.name
Svar
Ett godkänt svar returnerar HTTP-status 201 med information om den nya anslutningen, inklusive dess unika identifierare (id
).
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
id
id
av din nya basanslutning.etag
Autentiserad anslutning
Autentiserade anslutningar bör användas när du behöver skilja mellan poster som kommer från betrodda och ej betrodda källor. Användare som vill skicka information med personligt identifierbar information (PII) bör skapa en autentiserad anslutning vid direktuppspelning av information till plattformen.
Om du vill skapa en autentiserad basanslutning måste du inkludera authenticationRequired
parametern i din begäran och ange dess värde som true
. Under det här steget kan du även ange ett käll-ID för din autentiserade basanslutning. Den här parametern är valfri och använder samma värde som name
om det inte anges.
API-format
POST /flowservice/connections
Begäran
Följande begäran skapar en autentiserad basanslutning för HTTP API.
code language-shell |
---|
|
code language-shell |
---|
|
auth.params.sourceId
name
om det inte anges.auth.params.authenticationRequired
authenticationRequired
är inställd på true
måste autentisering anges för direktuppspelningsanslutningen. If authenticationRequired
är inställd på false
behöver du inte autentisera.Svar
Ett godkänt svar returnerar HTTP-status 201 med information om den nya anslutningen, inklusive dess unika identifierare (id
).
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
Hämta URL för direktuppspelningsslutpunkt
När du har skapat basanslutningen kan du nu hämta URL:en för direktuppspelningsslutpunkten.
API-format
GET /flowservice/connections/{BASE_CONNECTION_ID}
{BASE_CONNECTION_ID}
id
värdet för anslutningen som du skapade tidigare.Begäran
curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{BASE_CONNECTION_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Svar
Ett lyckat svar returnerar HTTP-status 200 med detaljerad information om den begärda anslutningen. URL:en för direktuppspelningsslutpunkten skapas automatiskt med anslutningen och kan hämtas med inletUrl
värde.
{
"items": [
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"createdAt": 1669238699119,
"updatedAt": 1669238699119,
"createdBy": "acme@AdobeID",
"updatedBy": "acme@AdobeID",
"createdClient": "{CREATED_CLIENT}",
"updatedClient": "{UPDATED_CLIENT}",
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"imsOrgId": "{ORG_ID}",
"name": "ACME Streaming Connection XDM Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"state": "enabled",
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "ACME Streaming Connection XDM Data",
"inletUrl": "https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"authenticationRequired": false,
"inletId": "667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"dataType": "xdm",
"name": "ACME Streaming Connection XDM Data"
}
},
"version": "\"f50185ed-0000-0200-0000-637e8fad0000\"",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
]
}
Skapa en källanslutning source
Om du vill skapa en källanslutning skickar du en POST till /sourceConnections
slutpunkt när du anger ditt basanslutnings-ID.
API-format
POST /flowservice/sourceConnections
Begäran
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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": "ACME Streaming Source Connection for Customer Data",
"description": "A streaming source connection for ACME XDM Customer Data",
"baseConnectionId": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
}
}'
Svar
Ett lyckat svar returnerar HTTP-status 201 med detaljerad information om den nya källanslutningen, inklusive dess unika identifierare (id
).
{
"id": "34ece231-294d-416c-ad2a-5a5dfb2bc69f",
"etag": "\"d505125b-0000-0200-0000-637eb7790000\""
}
Skapa ett mål-XDM-schema target-schema
För att källdata ska kunna användas i Platform måste ett målschema skapas för att strukturera källdata efter dina behov. Målschemat används sedan för att skapa en plattformsdatauppsättning där källdata finns.
Ett mål-XDM-schema kan skapas genom att utföra en POST-begäran till API för schemaregister.
Detaljerade anvisningar om hur du skapar ett XDM-målschema finns i självstudiekursen om skapa ett schema med API.
Skapa en måldatauppsättning target-dataset
En måldatauppsättning kan skapas genom att en POST till Katalogtjänstens API, som tillhandahåller målschemats ID i nyttolasten.
Detaljerade anvisningar om hur du skapar en måldatauppsättning finns i självstudiekursen om skapa en datauppsättning med API.
Skapa en målanslutning target
En målanslutning representerar anslutningen till målet där inkapslade data kommer in. Om du vill skapa en målanslutning begär du POST till /targetConnections
när du anger ID:n för måldatauppsättningen och XDM-målschemat. Under det här steget måste du även ange data Lake Connection specification ID. Detta ID är c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
API-format
POST /flowservice/targetConnections
Begäran
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-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": "ACME Streaming Target Connection",
"description": "ACME Streaming Target Connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "637eb7fadc8a211b6312b65b"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
Svar
Ett lyckat svar returnerar HTTP-status 201 med information om den nya målanslutningen, inklusive dess unika identifierare (id
).
{
"id": "07f2f6ff-1da5-4704-916a-c615b873cba9",
"etag": "\"340680f7-0000-0200-0000-637eb8730000\""
}
Skapa en mappning mapping
För att källdata ska kunna hämtas till en måldatamängd måste den först mappas till målschemat som måldatamängden följer.
Skapa en mappningsuppsättning genom att göra en POST-förfrågan till mappingSets
slutpunkt för Data Prep API när du tillhandahöll ditt mål-XDM-schema $id
och information om de mappningsuppsättningar som du vill skapa.
API-format
POST /mappingSets
Begäran
curl -X POST \
'https://platform.adobe.io/data/foundation/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}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "firstName",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "lastName",
"identity": false,
"version": 0
}
]
}'
xdmSchema
$id
av mål-XDM-schemat.Svar
Ett godkänt svar returnerar information om den nyligen skapade mappningen inklusive dess unika identifierare (id
). Detta ID krävs i ett senare steg för att skapa ett dataflöde.
{
"id": "79a623960d3f4969835c9e00dc90c8df",
"version": 0,
"createdDate": 1669249214031,
"modifiedDate": 1669249214031,
"createdBy": "acme@AdobeID",
"modifiedBy": "acme@AdobeID"
}
Skapa ett dataflöde
När käll- och målanslutningarna har skapats kan du nu skapa ett dataflöde. Dataflödet ansvarar för att schemalägga och samla in data från en källa. Du kan skapa ett dataflöde genom att göra en POST-förfrågan till /flows
slutpunkt.
API-format
POST /flows
Begäran
Följande begäran skapar ett direktuppspelat dataflöde för HTTP API utan dataomvandlingar.
code language-shell |
---|
|
Följande begäranden skapar ett dataflöde för direktuppspelning för HTTP API med mappningsomformningar tillämpade på dina data.
När du skapar ett dataflöde med omformningar name
-parametern kan inte ändras. Värdet måste alltid anges till Mapping
.
code language-shell |
---|
|
name
description
flowSpec.id
c1a19761-d2c7-4702-b9fa-fe91f0613e81
. Om du vill skapa ett dataflöde utan omformningar använder du d8a6f005-7eaf-4153-983e-e8574508b877
.sourceConnectionIds
targetConnectionIds
transformations.params.mappingId
Svar
Ett lyckat svar returnerar HTTP-status 201 med information om ditt nya dataflöde, inklusive dess unika identifierare (id
).
{
"id": "f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2",
"etag": "\"dc0459ae-0000-0200-0000-637ebaec0000\""
}
Bokför data som ska importeras till plattformen ingest-data
Nu när du har skapat ditt flöde kan du skicka ditt JSON-meddelande till direktuppspelningsslutpunkten som du skapade tidigare.
API-format
POST /collection/{INLET_URL}
{INLET_URL}
/connections
slutpunkt när du anger ditt basanslutnings-ID.{FLOW_ID}
Begäran
code language-shell |
---|
|
När du skickar rådata kan du ange ditt flödes-ID som en frågeparameter eller som en del av HTTP-huvudet. I följande exempel anges flödes-ID som HTTP-huvud.
code language-shell |
---|
|
När du skickar rådata kan du ange ditt flödes-ID som antingen en frågeparameter eller som ett HTTP-huvud. I följande exempel anges flödes-ID som en frågeparameter.
code language-shell |
---|
|
Svar
Ett lyckat svar returnerar HTTP-status 200 med information om den nya informationen.
{
"inletId": "{BASE_CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507
}
{BASE_CONNECTION_ID}
xactionId
receivedTimeMs
Nästa steg
Genom att följa den här självstudiekursen har du skapat en HTTP-direktuppspelningsanslutning, vilket gör att du kan använda direktuppspelningsslutpunkten för att importera data till plattformen. Instruktioner om hur du skapar en direktuppspelningsanslutning i användargränssnittet finns i skapa en självstudiekurs för direktuppspelningsanslutning.
Om du vill lära dig att strömma data till plattformen kan du läsa självstudiekursen på data för tidsserie för direktuppspelning eller självstudiekursen data för direktuppspelningspost.
Bilaga
I det här avsnittet finns ytterligare information om hur du skapar direktuppspelningsanslutningar med API:t.
Skicka meddelanden till en autentiserad direktuppspelningsanslutning
Om en direktuppspelningsanslutning har autentisering aktiverat måste klienten lägga till Authorization
till deras begäran.
Om Authorization
huvudet saknas, eller så skickas en ogiltig/utgången åtkomsttoken, ett otillåtet HTTP 401-svar returneras, med ett liknande svar som nedan:
Svar
{
"type": "https://ns.adobe.com/adobecloud/problem/data-collection-service-authorization",
"status": "401",
"title": "Authorization",
"report": {
"message": "[id] Ims service token is empty"
}
}