Om du vill ansluta till ett mål behöver du Manage Destinations åtkomstkontrollbehörighet.
Om du vill aktivera data måste du ha Manage Destinations, Activate Destinations, View Profiles och View Segments behörigheter för åtkomstkontroll.
Läs åtkomstkontroll - översikt eller kontakta produktadministratören för att få de behörigheter som krävs.
I den här självstudien visas hur du använder API-anrop för att ansluta till dina Adobe Experience Platform-data, skapa en anslutning till ett direktuppspelat molnlagringsmål (Amazon Kinesis eller Azure Event Hubs), skapa ett dataflöde till det nya målet och aktivera data till det nya målet.
I den här självstudiekursen används Amazon Kinesis mål i alla exempel, men stegen är identiska för Azure Event Hubs.
Om du föredrar att använda användargränssnittet i Platform för att ansluta till ett mål och aktivera data finns mer information i Anslut ett mål och Aktivera målgruppsdata för att direktuppspela segmentexportmål självstudiekurser.
Handboken kräver en fungerande förståelse av följande komponenter i Adobe Experience Platform:
I följande avsnitt finns ytterligare information som du behöver känna till för att kunna aktivera data för direktuppspelningsmål i Platform.
Om du vill slutföra stegen i den här självstudiekursen bör du ha följande autentiseringsuppgifter tillgängliga, beroende på vilken typ av mål du ansluter och aktiverar segment till.
accessKeyId
, secretKey
, region
eller connectionUrl
sasKeyName
, sasKey
, namespace
I den här självstudiekursen finns exempel-API-anrop som visar hur du formaterar dina begäranden. Det kan vara sökvägar, obligatoriska rubriker och korrekt formaterade begärandenyttolaster. Ett exempel på JSON som returneras i API-svar finns också. Information om konventionerna som används i dokumentationen för exempel-API-anrop finns i avsnittet om läsa exempel-API-anrop i felsökningsguiden för Experience Platform.
För att kunna ringa anrop till plattforms-API:er måste du först slutföra självstudiekurs om autentisering. När du slutför självstudiekursen för autentisering visas värdena för var och en av de obligatoriska rubrikerna i alla API-anrop för Experience Platform, vilket visas nedan:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
Resurser i Experience Platform kan isoleras till specifika virtuella sandlådor. I förfrågningar till plattforms-API:er kan du ange namnet och ID:t för sandlådan som åtgärden ska utföras i. Dessa är valfria parametrar.
{SANDBOX_NAME}
Mer information om sandlådor i Experience Platform finns i översiktsdokumentation för sandlåda.
Alla begäranden som innehåller en nyttolast (POST, PUT, PATCH) kräver ytterligare en medietypsrubrik:
application/json
Du hittar referensdokumentation för alla API-anrop i den här självstudiekursen i Swagger. Se API-dokumentation för Flow Service på Adobe I/O. Vi rekommenderar att du använder den här självstudiekursen och dokumentationssidan för Swagger parallellt.
Som ett första steg bör du bestämma vilket mål för direktuppspelning som data ska aktiveras till. Börja med att ringa ett samtal för att begära en lista över tillgängliga mål som du kan ansluta och aktivera segment till. Utför följande GET-förfrågan till connectionSpecs
slutpunkt för att returnera en lista över tillgängliga destinationer:
API-format
GET /connectionSpecs
Begäran
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'
Svar
Ett lyckat svar innehåller en lista över tillgängliga destinationer och deras unika identifierare (id
). Lagra värdet för destinationen som du tänker använda, vilket krävs i ytterligare steg. Om du till exempel vill ansluta och leverera segment till Amazon Kinesis eller Azure Event Hubssöker du efter följande utdrag i svaret:
{
"id": "86043421-563b-46ec-8e6c-e23184711bf6",
"name": "Amazon Kinesis",
...
...
}
{
"id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
"name": "Azure Event Hubs",
...
...
}
Därefter måste du ansluta till dina Experience Platform-data, så att du kan exportera profildata och aktivera dem på det önskade målet. Detta består av två ämnen som beskrivs nedan.
API-format
POST /connections
Begäran
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Base connection to Experience Platform",
"description": "This call establishes the connection to Experience Platform data",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
}
}'
{CONNECTION_SPEC_ID}
: Använd anslutningsspec-ID för profiltjänsten - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Svar
Ett godkänt svar innehåller basanslutningens unika identifierare (id
). Lagra det här värdet som det behövs i nästa steg för att skapa källanslutningen.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
API-format
POST /sourceConnections
Begäran
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connecting to Profile Service",
"description": "Optional",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"baseConnectionId": "{BASE_CONNECTION_ID}",
"data": {
"format": "json"
},
"params": {}
}'
{BASE_CONNECTION_ID}
: Använd det ID du fick i föregående steg.{CONNECTION_SPEC_ID}
: Använd anslutningsspec-ID för profiltjänsten - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Svar
Ett godkänt svar returnerar den unika identifieraren (id
) för den nyligen skapade källanslutningen till profiltjänsten. Detta bekräftar att du har anslutit till dina Experience Platform-data. Lagra det här värdet som det behövs i ett senare steg.
{
"id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}
I det här steget skapar du en anslutning till det önskade direktuppspelningsmålet. Detta består av två ämnen som beskrivs nedan.
API-format
POST /connections
Begäran
Exemplet nedan innehåller kodkommentarer med prefix //
. Dessa kommentarer visar var olika värden måste användas för olika direktuppspelningsmål. Ta bort kommentarerna innan du använder fragmentet.
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connection for Amazon Kinesis/ Azure Event Hubs",
"description": "summer advertising campaign",
"connectionSpec": {
"id": "{_CONNECTION_SPEC_ID}",
"version": "1.0"
},
"auth": {
"specName": "{AUTHENTICATION_CREDENTIALS}",
"params": { // use these values for Amazon Kinesis connections
"accessKeyId": "{ACCESS_ID}",
"secretKey": "{SECRET_KEY}",
"region": "{REGION}"
},
"params": { // use these values for Azure Event Hubs connections
"sasKeyName": "{SAS_KEY_NAME}",
"sasKey": "{SAS_KEY}",
"namespace": "{EVENT_HUB_NAMESPACE}"
}
}
}'
{CONNECTION_SPEC_ID}
: Använd det anslutningsspec-ID som du fick i steget Hämta listan över tillgängliga mål.{AUTHENTICATION_CREDENTIALS}
: Fyll i namnet på strömningsmålet: Aws Kinesis authentication credentials
eller Azure EventHub authentication credentials
.{ACCESS_ID}
: För Amazon Kinesis anslutningar. Ditt åtkomst-ID för din lagringsplats för Amazon Kinesis.{SECRET_KEY}
: För Amazon Kinesis anslutningar. Din hemliga nyckel för din lagringsplats för Amazon Kinesis.{REGION}
: För Amazon Kinesis anslutningar. Regionen i ditt Amazon Kinesis konto där Platform kan strömma era data.{SAS_KEY_NAME}
: För Azure Event Hubs anslutningar. Fyll i ditt SAS-nyckelnamn. Lär dig mer om autentisering av Azure Event Hubs med SAS-nycklar i Microsoft-dokumentation.{SAS_KEY}
: För Azure Event Hubs anslutningar. Fyll i SAS-nyckeln. Lär dig mer om autentisering av Azure Event Hubs med SAS-nycklar i Microsoft-dokumentation.{EVENT_HUB_NAMESPACE}
: För Azure Event Hubs anslutningar. Fyll i Azure Event Hubs namnutrymme där Platform direktuppspelar data. Mer information finns i Skapa ett namnutrymme för händelsehubbar i Microsoft dokumentation.Svar
Ett godkänt svar innehåller basanslutningens unika identifierare (id
). Lagra det här värdet som det behövs i nästa steg för att skapa en målanslutning.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
API-format
POST /targetConnections
Begäran
Exemplet nedan innehåller kodkommentarer med prefix //
. Dessa kommentarer visar var olika värden måste användas för olika direktuppspelningsmål. Ta bort kommentarerna innan du använder fragmentet.
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Amazon Kinesis/ Azure Event Hubs target connection",
"description": "Connection to Amazon Kinesis/ Azure Event Hubs",
"baseConnectionId": "{BASE_CONNECTION_ID}",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": { // use these values for Amazon Kinesis connections
"stream": "{NAME_OF_DATA_STREAM}",
"region": "{REGION}"
},
"params": { // use these values for Azure Event Hubs connections
"eventHubName": "{EVENT_HUB_NAME}"
}
}'
{BASE_CONNECTION_ID}
: Använd det grundläggande anslutnings-ID som du fick i steget ovan.{CONNECTION_SPEC_ID}
: Använd anslutningsspecifikationen som du fick i steget Hämta listan över tillgängliga mål.{NAME_OF_DATA_STREAM}
: För Amazon Kinesis anslutningar. Ange namnet på din befintliga dataström i din Amazon Kinesis konto. Plattformen exporterar data till den här strömmen.{REGION}
: För Amazon Kinesis anslutningar. Den region på ditt Amazon Kinesis-konto där Platform strömmar dina data.{EVENT_HUB_NAME}
: För Azure Event Hubs anslutningar. Fyll i Azure Event Hub namn där plattformen ska strömma dina data. Mer information finns i Skapa en händelsehubb i Microsoft dokumentation.Svar
Ett godkänt svar returnerar den unika identifieraren (id
) för den nyligen skapade målanslutningen till ditt mål för direktuppspelning. Lagra det här värdet som det behövs i senare steg.
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
Med de ID:n du fick i föregående steg kan du nu skapa ett dataflöde mellan dina Experience Platform-data och det mål där du vill aktivera data. Tänk på det här steget som att skapa en pipeline, genom vilken data sedan flödar mellan Experience Platform och det önskade målet.
Om du vill skapa ett dataflöde ska du utföra en begäran om POST enligt nedan, med de värden som anges nedan i nyttolasten.
Utför följande begäran om POST för att skapa ett dataflöde.
API-format
POST /flows
Begäran
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "Azure Event Hubs",
"description": "Azure Event Hubs",
"flowSpec": {
"id": "{FLOW_SPEC_ID}",
"version": "1.0"
},
"sourceConnectionIds": [
"{SOURCE_CONNECTION_ID}"
],
"targetConnectionIds": [
"{TARGET_CONNECTION_ID}"
],
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
]
},
"segmentSelectors": {
"selectors": [
]
}
}
}
]
}
{FLOW_SPEC_ID}
: Flödesspecifikation-ID för profilbaserade mål är 71471eba-b620-49e4-90fd-23f1fa0174d8
. Använd det här värdet i anropet.{SOURCE_CONNECTION_ID}
: Använd det källanslutnings-ID som du fick i steget Anslut till Experience Platform.{TARGET_CONNECTION_ID}
: Använd det ID för målanslutning som du fick i steget Anslut till direktuppspelningsmål.Svar
Ett godkänt svar returnerar ID:t (id
) av det nya dataflödet och etag
. Notera båda värdena nedåt. som du kommer att göra i nästa steg, för att aktivera segment.
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
"etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}
När du har skapat alla anslutningar och dataflödet kan du nu aktivera dina profildata till direktuppspelningsplattformen. I det här steget väljer du vilka segment och vilka profilattribut du skickar till målet och du kan schemalägga och skicka data till målet.
Om du vill aktivera segment till det nya målet måste du utföra en JSON PATCH-åtgärd, som i exemplet nedan. Du kan aktivera flera segment och profilattribut i ett samtal. Mer information om JSON PATCH finns i RFC-specifikation.
API-format
PATCH /flows
Begäran
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
{
"op": "add",
"path": "/transformations/0/params/segmentSelectors/selectors/-",
"value": {
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Name of the segment that you are activating",
"description": "Description of the segment that you are activating",
"id": "{SEGMENT_ID}"
}
}
},
{
"op": "add",
"path": "/transformations/0/params/profileSelectors/selectors/-",
"value": {
"type": "JSON_PATH",
"value": {
"operator": "EXISTS",
"path": "{PROFILE_ATTRIBUTE}"
}
}
}
]
Egenskap | Beskrivning |
---|---|
{DATAFLOW_ID} |
Använd ID:t för dataflödet som du skapade i föregående steg i URL-adressen. |
{ETAG} |
Skaffa {ETAG} från svaret i föregående steg, Skapa ett dataflöde. Svarsformatet i föregående steg har escape-citattecken. Du måste använda värdena för unescape-konvertering i huvudet i begäran. Se exemplet nedan:
Värdet för etag uppdateras med varje lyckad uppdatering av ett dataflöde. |
{SEGMENT_ID} |
Ange det segment-ID som du vill exportera till det här målet. Information om hur du hämtar segment-ID:n för de segment som du vill aktivera finns i hämta en segmentdefinition i API-referensen för Experience Platform. |
{PROFILE_ATTRIBUTE} |
Exempel: "person.lastName" |
op |
Åtgärdsanropet som används för att definiera åtgärden som krävs för att uppdatera dataflödet. Åtgärderna omfattar: add , replace och remove . Om du vill lägga till ett segment i ett dataflöde använder du add operation. |
path |
Definierar den del av flödet som ska uppdateras. När du lägger till ett segment i ett dataflöde använder du den sökväg som anges i exemplet. |
value |
Det nya värdet som du vill uppdatera parametern med. |
id |
Ange ID:t för det segment som du lägger till i måldataflödet. |
name |
Valfritt. Ange namnet på segmentet som du lägger till i måldataflödet. Observera att det här fältet inte är obligatoriskt och att du kan lägga till ett segment i måldataflödet utan att ange dess namn. |
Svar
Håll utkik efter 202 OK-svar. Ingen svarstext returneras. Om du vill verifiera att begäran var korrekt går du till nästa steg, Validera dataflödet.
Som ett sista steg i självstudiekursen bör du validera att segmenten och profilattributen verkligen har mappats korrekt till dataflödet.
Gör följande GET-förfrågan för att validera detta:
API-format
GET /flows
Begäran
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"'
{DATAFLOW_ID}
: Använd dataflödet från föregående steg.{ETAG}
: Använd taggen från föregående steg.Svar
Det returnerade svaret ska innehålla transformations
parametern segmenten och profilattributen som du skickade i föregående steg. Ett exempel transformations
parametern i svaret kan se ut så här:
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
{
"type": "JSON_PATH",
"value": {
"path": "personalEmail.address",
"operator": "EXISTS"
}
},
{
"type": "JSON_PATH",
"value": {
"path": "person.lastname",
"operator": "EXISTS"
}
}
]
},
"segmentSelectors": {
"selectors": [
{
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Men over 50",
"description": "",
"id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
}
}
]
}
}
}
],
Exporterade data
Förutom profilattributen och segmenten i steget Aktivera data till ditt nya mål, exporterade data i AWS Kinesis och Azure Event Hubs innehåller även information om identitetskartan. Detta representerar identiteten för de exporterade profilerna (till exempel ECID, mobilt ID, Google ID, e-postadress osv.). Se ett exempel nedan.
{
"person": {
"email": "yourstruly@adobe.com"
},
"segmentMembership": {
"ups": {
"72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
"lastQualificationTime": "2020-03-03T21:24:39Z",
"status": "exited"
},
"7841ba61-23c1-4bb3-a495-00d695fe1e93": {
"lastQualificationTime": "2020-03-04T23:37:33Z",
"status": "realized"
}
}
},
"identityMap": {
"ecid": [
{
"id": "14575006536349286404619648085736425115"
},
{
"id": "66478888669296734530114754794777368480"
}
],
"email_lc_sha256": [
{
"id": "655332b5fa2aea4498bf7a290cff017cb4"
},
{
"id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
}
]
}
}
Om du vill ansluta till de direktuppspelningsmål som beskrivs i den här självstudiekursen på ett effektivare sätt kan du använda Postman.
Postman är ett verktyg som du kan använda för att göra API-anrop och hantera bibliotek med fördefinierade anrop och miljöer.
Följande gäller för den här självstudiekursen Postman samlingar har bifogats:
Klicka här för att hämta samlingsarkivet.
Varje samling innehåller nödvändiga begäranden och miljövariabler för AWS Kinesisoch Azure Event Hub, respektive.
För att ansluta till målen med hjälp av den bifogade Postman samlingar, följ dessa steg:
API-slutpunkterna i den här självstudien följer de allmänna felmeddelandeprinciperna för Experience Platform API. Se API-statuskoder och fel i begäranhuvudet i felsökningsguiden för plattformen för mer information om hur du tolkar felsvar.
Genom att följa den här självstudiekursen har du anslutit plattformen till ett av dina önskade direktuppspelningsmål och konfigurerat ett dataflöde till respektive mål. Utgående data kan nu användas i målet för kundanalys eller andra dataåtgärder som du kanske vill utföra. Mer information finns på följande sidor: