Verbinding maken met streaming doelen en gegevens activeren met de Flow Service API

Dit leerprogramma toont aan hoe te om API vraag te gebruiken om met uw gegevens van Adobe Experience Platform te verbinden, een verbinding tot een het stromen bestemming van de wolkenopslag tot stand te brengen ( Amazon Kinesisof Azure Gebeurtenis Hubs), een dataflow aan uw nieuwe gecreeerde bestemming tot stand te brengen, en gegevens aan uw nieuwe gecreeerde bestemming te activeren.

In deze zelfstudie wordt in alle voorbeelden het doel van Amazon Kinesis gebruikt, maar de stappen zijn identiek voor Azure Event Hubs .

Als u verkiest om het gebruikersinterface in Experience Platform te gebruiken om met een bestemming te verbinden en gegevens te activeren, verbind een bestemmingen activeer publieksgegevens aan het stromen van publiek uitvoerbestemmingenleerprogramma's.

Aan de slag

Deze handleiding vereist een goed begrip van de volgende onderdelen van Adobe Experience Platform:

De volgende secties verstrekken extra informatie die u zult moeten weten om gegevens aan het stromen bestemmingen in Experience Platform te activeren.

Vereiste referenties verzamelen

Om de stappen in dit leerprogramma te voltooien, zou u de volgende geloofsbrieven klaar moeten hebben, afhankelijk van het type van bestemmingen dat u verbindend en activerend publiek aan.

API-voorbeeldaanroepen lezen reading-sample-api-calls

Deze zelfstudie biedt voorbeeld-API-aanroepen om aan te tonen hoe uw verzoeken moeten worden opgemaakt. Dit zijn paden, vereiste kopteksten en correct opgemaakte ladingen voor aanvragen. Voorbeeld-JSON die wordt geretourneerd in API-reacties, wordt ook verschaft. Voor informatie over de overeenkomsten die in documentatie voor steekproef API vraag worden gebruikt, zie de sectie op hoe te om voorbeeld API vraagin de het oplossen van problemengids van Experience Platform te lezen.

Waarden verzamelen voor vereiste en optionele koppen gather-values

Om vraag aan Experience Platform APIs te maken, moet u het authentificatieleerprogrammaeerst voltooien. Als u de zelfstudie over verificatie voltooit, krijgt u de waarden voor elk van de vereiste headers in alle Experience Platform API-aanroepen, zoals hieronder wordt getoond:

De middelen in Experience Platform kunnen aan specifieke virtuele zandbakken worden geïsoleerd. In aanvragen voor Experience Platform API's kunt u de naam en id opgeven van de sandbox waarin de bewerking plaatsvindt. Dit zijn optionele parameters.

Alle verzoeken die een lading (POST, PUT, PATCH) bevatten vereisen een extra media typekopbal:

Documentatie voor de wagenbak swagger-docs

In deze zelfstudie in Swagger vindt u begeleidende referentiedocumentatie voor alle API-aanroepen. Zie de documentatie van de Dienst API van de Stroom op Adobe I/O. We raden u aan deze zelfstudie en de documentatiepagina van Swagger parallel te gebruiken.

Hiermee wordt de lijst met beschikbare streamingdoelen opgehaald get-the-list-of-available-streaming-destinations

Als eerste stap moet u bepalen naar welke streamingbestemming de gegevens moeten worden geactiveerd. Om met te beginnen, voer een vraag uit om een lijst van beschikbare bestemmingen te verzoeken die u kunt verbinden en publiek activeren aan. Voer het volgende GET verzoek aan het connectionSpecs eindpunt uit om een lijst van beschikbare bestemmingen terug te keren:

API formaat

GET /connectionSpecs

Verzoek

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

Reactie

Een succesvolle reactie bevat een lijst van beschikbare bestemmingen en hun unieke herkenningstekens (id). Sla de waarde op van het doel dat u wilt gebruiken, zoals in verdere stappen wordt vereist. Als u bijvoorbeeld een verbinding wilt maken met Amazon Kinesis of Azure Event Hubs en een publiek wilt maken, zoekt u het volgende fragment in het antwoord:

{
    "id": "86043421-563b-46ec-8e6c-e23184711bf6",
  "name": "Amazon Kinesis",
  ...
  ...
}

{
    "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
  "name": "Azure Event Hubs",
  ...
  ...
}

Verbinding maken met uw Experience Platform-gegevens connect-to-your-experience-platform-data

Vervolgens moet u verbinding maken met uw Experience Platform-gegevens, zodat u profielgegevens kunt exporteren en activeren op de gewenste bestemming. Deze bestaat uit twee substappen die hieronder worden beschreven.

Toegang tot uw gegevens autoriseren in Experience Platform

API formaat

POST /connections

Verzoek

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

Reactie

Een succesvolle reactie bevat het unieke herkenningsteken van de basisverbinding (id). Sla deze waarde op zoals vereist in de volgende stap om de bronverbinding te maken.

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Verbinding maken met uw Experience Platform-gegevens connect-to-platform-data

API formaat

POST /sourceConnections

Verzoek

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": {}
}'

Reactie

Een succesvolle reactie keert unieke herkenningsteken (id) voor de pas gecreëerde bronverbinding aan de Dienst van het Profiel terug. Hiermee bevestigt u dat u verbinding hebt gemaakt met uw Experience Platform-gegevens. Sla deze waarde op zoals deze in een latere stap wordt vereist.

{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

Verbinding maken met streamingdoel connect-to-streaming-destination

In deze stap stelt u een verbinding in met uw gewenste streamingdoel. Deze bestaat uit twee substappen die hieronder worden beschreven.

Toegang tot de streamingbestemming autoriseren

API formaat

POST /connections

Verzoek

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

Reactie

Een succesvolle reactie bevat het unieke herkenningsteken van de basisverbinding (id). Sla deze waarde op zoals vereist in de volgende stap om een doelverbinding te maken.

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Opslaglocatie en gegevensindeling opgeven

API formaat

POST /targetConnections

Verzoek

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

Reactie

Een succesvol antwoord keert unieke herkenningsteken (id) voor de pas gecreëerde doelverbinding aan uw het stromen bestemming terug. Sla deze waarde op zoals deze in latere stappen wordt vereist.

{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

Een gegevensstroom maken

Met de id's die u in de vorige stappen hebt opgehaald, kunt u nu een gegevensstroom maken tussen uw Experience Platform-gegevens en de bestemming waarnaar u de gegevens wilt activeren. Beschouw deze stap als het construeren van de pijpleiding, waardoor de gegevens later, tussen Experience Platform en uw gewenste bestemming zullen stromen.

Als u een gegevensstroom wilt maken, voert u een POST-verzoek uit, zoals hieronder wordt weergegeven, terwijl u de hieronder vermelde waarden opgeeft binnen de laadtijd.

Voer het volgende POST- verzoek uit om een gegevensstroom tot stand te brengen.

API formaat

POST /flows

Verzoek

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": [

          ]
        }
      }
    }
  ]
}

Reactie

Een geslaagde reactie retourneert de id (id) van de nieuwe gegevensstroom en een etag . Noteer beide waarden. zoals u dat in de volgende stap doet , om het publiek te activeren .

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

Gegevens activeren naar uw nieuwe bestemming activate-data

Nadat u alle verbindingen en de gegevensstroom hebt gemaakt, kunt u nu uw profielgegevens activeren op het streamingplatform. In deze stap selecteert u welk publiek en welke profielkenmerken u naar de bestemming verzendt en kunt u gegevens plannen en naar de bestemming verzenden.

Als u een publiek naar uw nieuwe bestemming wilt activeren, moet u een JSON PATCH-bewerking uitvoeren, vergelijkbaar met het onderstaande voorbeeld. U kunt veelvoudige publiek en profielattributen in één vraag activeren. Meer over JSON PATCH leren, zie de specificatie RFC.

API formaat

PATCH /flows

Verzoek

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

Reactie

Kijk naar een 202 OK-antwoord. Er wordt geen responsorgaan geretourneerd. Om te bevestigen dat het verzoek correct was, zie de volgende stap, de gegevensstroom bevestigen.

De gegevensstroom valideren

Als laatste stap in de zelfstudie moet u controleren of het publiek en de profielkenmerken correct zijn toegewezen aan de gegevensstroom.

Voer de volgende GET-aanvraag uit om dit te valideren:

API formaat

GET /flows

Verzoek

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

Reactie

De geretourneerde reactie moet in de parameter transformations het publiek en de profielkenmerken bevatten die u in de vorige stap hebt verzonden. Een sample transformations -parameter in de reactie kan er als volgt uitzien:

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

Geëxporteerde Gegevens

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

Postman -verzamelingen gebruiken om verbinding te maken met streaming doelen collections

Om met de het stromen bestemmingen te verbinden die in dit leerprogramma worden beschreven op een meer gestroomlijnde manier, kunt u Postman gebruiken.

Postman is een hulpmiddel dat u kunt gebruiken om API vraag te maken en bibliotheken van vooraf bepaalde vraag en milieu's te beheren.

Voor deze specifieke zelfstudie zijn de volgende Postman verzamelingen gekoppeld:

Klik hierom het archief van inzamelingen te downloaden.

Elke verzameling bevat de benodigde aanvragen en omgevingsvariabelen voor respectievelijk AWS Kinesis en Azure Event Hub .

De Postman -verzamelingen gebruiken how-to-use-postman-collections

Voer de volgende stappen uit om verbinding te maken met de doelen die zijn gekoppeld aan de verzamelingen in Postman :

API-foutafhandeling api-error-handling

De API-eindpunten in deze zelfstudie volgen de algemene beginselen van het Experience Platform API-foutbericht. Verwijs naar API statuscodesen de fouten van de verzoekkopbalin de het oplossen van problemengids van Experience Platform voor meer informatie bij het interpreteren van foutenreacties.

Volgende stappen next-steps

Door deze zelfstudie te volgen, hebt u Experience Platform verbonden met een van uw voorkeursstreamingdoelen en een gegevensstroom ingesteld naar het desbetreffende doel. De uitgaande gegevens kunnen nu in de bestemming voor klantenanalyse of om het even welke andere gegevensverrichtingen worden gebruikt u zou willen uitvoeren. Raadpleeg de volgende pagina's voor meer informatie: