Ansluta till direktuppspelningsmål och aktivera data med API:t för Flow Service

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 direktuppspelad målgruppsexport självstudier.

Kom igång

Handboken kräver en fungerande förståelse av följande komponenter i Adobe Experience Platform:

• Experience Data Model (XDM) System: Det standardiserade ramverk som Experience Platform använder för att ordna kundupplevelsedata.
• Catalog Service: Catalog är registersystemet för dataplats och datalinje inom Experience Platform.
• Sandlådor: Experience Platform tillhandahåller virtuella sandlådor som partitionerar en enda plattformsinstans i separata virtuella miljöer för att utveckla och utveckla program för digitala upplevelser.

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.

Samla in nödvändiga inloggningsuppgifter

För att 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 målgrupper till.

• För Amazon Kinesis anslutningar: accessKeyId, secretKey, region eller connectionUrl
• För Azure Event Hubs anslutningar: sasKeyName, sasKey, namespace

Läser exempel-API-anrop

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.

Samla in värden för obligatoriska och valfria rubriker

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:

• Behörighet: Bearer {ACCESS_TOKEN}
• x-api-key: {API_KEY}
• x-gw-ims-org-id: {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.

• x-sandbox-name: {SANDBOX_NAME}

Alla begäranden som innehåller en nyttolast (POST, PUT, PATCH) kräver ytterligare en medietypsrubrik:

• Innehållstyp: application/json

Dokumentation för Swagger

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.

Hämta listan över tillgängliga mål för direktuppspelning

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 destinationer som du kan ansluta och aktivera målgrupper 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 målgrupper 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",
  ...
  ...
}

Ansluta till dina Experience Platform-data

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.

1. Först måste du ringa ett samtal för att ge behörighet till dina data i Experience Platform genom att konfigurera en basanslutning.
2. Med basanslutnings-ID:t gör du sedan ett nytt anrop där du skapar en källanslutning som upprättar anslutningen till dina Experience Platform-data.

Ge åtkomst till dina data i Experience Platform

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"
}

Ansluta till dina Experience Platform-data

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"
}

Anslut till direktuppspelningsmål

I det här steget skapar du en anslutning till det önskade direktuppspelningsmålet. Detta består av två ämnen som beskrivs nedan.

1. Först måste du ringa för att auktorisera åtkomst till direktuppspelningsmålet genom att konfigurera en basanslutning.
2. Med hjälp av basanslutnings-ID:t gör du sedan ett nytt anrop där du skapar en målanslutning, där du anger platsen i lagringskontot där exporterade data ska levereras samt formatet för de data som ska exporteras.

Auktorisera åtkomst till direktuppspelningsmålet

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": "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å ditt mål för direktuppspelning: 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"
}

Ange lagringsplats och dataformat

API-format

POST /targetConnections

Begäran

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"
}

Skapa ett dataflöde

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ödesspekt-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 din 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 ni kommer att göra i nästa steg, för att aktivera målgrupper.

{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

Aktivera data till ditt nya mål

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 målgrupper och vilka profilattribut du skickar till målet, och du kan schemalägga och skicka data till målet.

Om du vill aktivera målgrupper till ditt nya mål måste du utföra en JSON PATCH-åtgärd, som i exemplet nedan. Du kan aktivera flera målgrupper 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 audience that you are activating",
        "description": "Description of the audience 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}"
      }
    }
  }
]

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.

Validera dataflödet

Som ett sista steg i självstudiekursen bör du validera att målgrupper och profilattribut 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 anger målgrupper och profilattribut 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

{
  "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"
      }
    ]
  }
}

Använda Postman samlingar att ansluta till direktuppspelningsmål

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:

• AWS Kinesis Postman samling
• Azure Event Hubs Postman samling

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

Så här använder du Postman samlingar

För att ansluta till målen med hjälp av den bifogade Postman samlingar, följ dessa steg:

• Hämta och installera Postman;
• Ladda ned och packa upp de bifogade samlingarna,
• Importera samlingar från deras motsvarande mappar till Postman;
• Fyll i miljövariablerna enligt instruktionerna i denna artikel.
• Kör API förfrågningar från Postmanenligt instruktionerna i den här artikeln.

API-felhantering

API-slutpunkterna i den här självstudiekursen 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.

Nästa steg

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:

• Översikt över mål
• Översikt över destinationskatalogen