Se connecter aux destinations de diffusion en continu et activer les données à l’aide de l’API Flow Service
- Rubriques :
- Destinations
Créé pour :
- Administration
- Utilisateur ou utilisatrice
Ce tutoriel vous explique comment utiliser les appels API pour vous connecter à vos données Adobe Experience Platform, créer une connexion à une destination de stockage en flux continu dans le cloud (Amazon Kinesis ou Azure Event Hubs), créer un flux de données vers votre nouvelle destination et activer les données vers cette dernière.
Ce tutoriel utilise la destination Amazon Kinesis dans tous ses exemples, mais les étapes sont identiques pour Azure Event Hubs.
Si vous préférez utiliser l’interface utilisateur dans Experience Platform pour vous connecter à une destination et activer des données, reportez-vous aux tutoriels Se connecter à une destination et Activer des données d’audience vers des destinations d’exportation d’audience en flux continu.
Prise en main
Ce guide nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :
- Experience Data Model (XDM) System : framework normalisé selon lequel Experience Platform organise les données de l’expérience client.
- Catalog Service : Catalog est le système d’enregistrement de l’emplacement et de la traçabilité des données dans Experience Platform.
- Sandbox : Experience Platform fournit des sandbox virtuels qui divisent une instance Experience Platform unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.
Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin afin d’activer des données vers des destinations de diffusion en streaming dans Experience Platform.
Collecter les informations d’identification requises
Pour suivre les étapes de ce tutoriel, vous devez disposer des informations d’identification suivantes, selon le type de destinations auxquelles vous vous connectez et sur lesquelles vous activez des audiences.
- Pour les connexions Amazon Kinesis :
accessKeyId
,secretKey
,region
ouconnectionUrl
- Pour les connexions Azure Event Hubs :
sasKeyName
,sasKey
,namespace
Lecture d’exemples d’appels API
Ce tutoriel fournit des exemples d’appels API pour démontrer comment formater vos requêtes. Il s’agit notamment de chemins d’accès, d’en-têtes requis et de payloads de requêtes correctement formatés. L’exemple JSON renvoyé dans les réponses de l’API est également fourni. Pour plus d’informations sur les conventions utilisées dans la documentation pour les exemples d’appels API, consultez la section sur la lecture d’exemples d’appels API dans le guide de dépannage d’Experience Platform.
Collecte de valeurs pour les en-têtes requis et facultatifs
Pour lancer des appels aux API Experience Platform, vous devez d’abord suivre le tutoriel sur l’authentification. Le tutoriel sur l’authentification indique les valeurs de chacun des en-têtes requis dans tous les appels API Experience Platform, comme illustré ci-dessous :
- Authorization: Bearer
{ACCESS_TOKEN}
- x-api-key :
{API_KEY}
- x-gw-ims-org-id:
{ORG_ID}
Les ressources d’Experience Platform peuvent être isolées dans des sandbox virtuels spécifiques. Dans les requêtes aux API Experience Platform, vous pouvez spécifier le nom et l’identifiant du sandbox dans lequel l’opération aura lieu. Il s’agit de paramètres facultatifs.
- x-sandbox-name:
{SANDBOX_NAME}
Toutes les requêtes qui contiennent un payload (POST, PUT, PATCH) nécessitent un en-tête de type de média supplémentaire :
- Content-Type:
application/json
Documentation Swagger
Ce tutoriel vous permet de trouver dans Swagger la documentation de référence relative à tous les appels API. Voir la Documentation de l’API Flow Service sur Adobe I/O. Nous vous recommandons de consulter ce tutoriel et la page de documentation de Swagger en parallèle.
Obtention de la liste des destinations de streaming disponibles
Dans un premier temps, vous devez décider vers quelle destination de diffusion en continu activer les données. Pour commencer, effectuez un appel pour demander une liste des destinations disponibles auxquelles vous pouvez vous connecter et activer des audiences. Effectuez la requête GET suivante auprès du point d’entrée connectionSpecs
pour obtenir une liste des destinations disponibles :
Format d’API
GET /connectionSpecs
Requête
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}'
Réponse
Une réponse réussie contient une liste des destinations disponibles et leurs identifiants uniques (id
). Conservez la valeur de la destination que vous prévoyez d’utiliser, car elle sera requise dans les étapes suivantes. Par exemple, si vous souhaitez vous connecter et diffuser des audiences vers Amazon Kinesis ou Azure Event Hubs, recherchez l’extrait suivant dans la réponse :
{
"id": "86043421-563b-46ec-8e6c-e23184711bf6",
"name": "Amazon Kinesis",
...
...
}
{
"id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
"name": "Azure Event Hubs",
...
...
}
Connexion à vos données Experience Platform
Ensuite, vous devez vous connecter à vos données Experience Platform afin de pouvoir exporter des données de profil et les activer dans votre destination préférée. Il s’agit de deux sous-étapes présentées ci-dessous.
- Tout d’abord, vous devez effectuer un appel pour autoriser l’accès à vos données dans Experience Platform, en établissant une connexion de base.
- Ensuite, à l’aide de l’identifiant de connexion de base, vous passerez un autre appel au cours duquel vous créerez une connexion source, qui établira la connexion avec vos données Experience Platform.
Autorisation d’accès à vos données dans Experience Platform
Format d’API
POST /connections
Requête
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}
: utilisez l’identifiant de spécification de connexion pour Service de profil -8a9c3494-9708-43d7-ae3f-cda01e5030e1
.
Réponse
Une réponse réussie contient l’identifiant unique de la connexion de base (id
). Conservez cette valeur car elle est nécessaire à l’étape suivante pour créer la connexion source.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
Connexion à vos données Experience Platform
Format d’API
POST /sourceConnections
Requête
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}
: utilisez l’identifiant que vous avez obtenu à l’étape précédente.{CONNECTION_SPEC_ID}
: utilisez l’identifiant de spécification de connexion pour Service de profil -8a9c3494-9708-43d7-ae3f-cda01e5030e1
.
Réponse
Une réponse réussie renvoie l’identifiant unique (id
) de la nouvelle connexion source au service de profil. Cela confirme que vous avez réussi à vous connecter à vos données Experience Platform. Conservez cette valeur car elle sera nécessaire lors d’une prochaine étape.
{
"id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}
Se connecter à la destination de diffusion en continu
Au cours de cette étape, vous établissez une connexion à la destination de diffusion en continu souhaitée. Il s’agit de deux sous-étapes présentées ci-dessous.
- Tout d’abord, vous devez effectuer un appel pour autoriser l’accès à la destination de diffusion en streaming, en établissant une connexion de base.
- Ensuite, à l’aide de l’identifiant de connexion de base, vous passerez un autre appel au cours duquel vous créerez une connexion cible, qui spécifie l’emplacement de votre compte de stockage où les données exportées seront transmises, ainsi que le format des données qui seront exportées.
Autoriser l’accès à la destination de diffusion en streaming
Format d’API
POST /connections
Requête
//
. Ces commentaires indiquent où différentes valeurs doivent être utilisées pour différentes destinations de diffusion en streaming. Supprimez les commentaires avant d’utiliser le fragment de code.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}
: utilisez l’identifiant de spécification de connexion que vous avez obtenu lors de l’étape Obtention de la liste des destinations disponibles.{AUTHENTICATION_CREDENTIALS}
: renseignez le nom de votre destination de diffusion en streaming :Aws Kinesis authentication credentials
ouAzure EventHub authentication credentials
.{ACCESS_ID}
: Pour les connexions Amazon Kinesis. Identifiant d’accès pour l’emplacement de stockage Amazon Kinesis.{SECRET_KEY}
: Pour les connexions Amazon Kinesis. Votre clé secrète pour l’emplacement de stockage Amazon Kinesis.{REGION}
: Pour les connexions Amazon Kinesis. Région de votre compte Amazon Kinesis dans laquelle Experience Platform diffusera vos données.{SAS_KEY_NAME}
: Pour les connexions Azure Event Hubs. Renseignez votre nom de clé SAS. Découvrez comment vous authentifier à l’Azure Event Hubs avec des clés SAS dans la documentation de Microsoft.{SAS_KEY}
: Pour les connexions Azure Event Hubs. Renseignez votre clé SAS. Découvrez comment vous authentifier à l’Azure Event Hubs avec des clés SAS dans la documentation de Microsoft.{EVENT_HUB_NAMESPACE}
: Pour les connexions Azure Event Hubs. Renseignez l’espace de noms Azure Event Hubs dans lequel Experience Platform diffusera vos données. Pour plus d’informations, consultez Création d’un espace de noms Event Hubs dans la documentation Microsoft.
Réponse
Une réponse réussie contient l’identifiant unique de la connexion de base (id
). Conservez cette valeur car elle est nécessaire à l’étape suivante pour créer une connexion cible.
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
Indication de l’emplacement de stockage et du format des données
Format d’API
POST /targetConnections
Requête
//
. Ces commentaires indiquent où différentes valeurs doivent être utilisées pour différentes destinations de diffusion en streaming. Supprimez les commentaires avant d’utiliser le fragment de code.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}
: utilisez l’identifiant de connexion de base que vous avez obtenu à l’étape ci-dessus.{CONNECTION_SPEC_ID}
: utilisez la spécification de connexion que vous avez obtenue lors de l’étape Obtention de la liste des destinations disponibles.{NAME_OF_DATA_STREAM}
: Pour les connexions Amazon Kinesis. Indiquez le nom de votre flux de données existant dans votre compte Amazon Kinesis. Experience Platform exportera les données vers ce flux.{REGION}
: Pour les connexions Amazon Kinesis. Zone géographique de votre compte Amazon Kinesis dans laquelle Experience Platform diffusera vos données.{EVENT_HUB_NAME}
: Pour les connexions Azure Event Hubs. Renseignez le nom du Azure Event Hub où Experience Platform diffusera vos données. Pour plus d’informations, consultez Création d’un centre d’événements dans la documentation Microsoft.
Réponse
Une réponse réussie renvoie l’identifiant unique (id
) de la nouvelle connexion cible créée à votre destination de diffusion en streaming. Conservez cette valeur car elle sera nécessaire lors de prochaines étapes.
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
Créer un flux de données
À l’aide des identifiants obtenus lors des étapes précédentes, vous pouvez maintenant créer un flux de données entre vos données Experience Platform et la destination vers laquelle vous activerez les données. Considérez cette étape comme la création du pipeline, par lequel les données seront ensuite acheminées, entre Experience Platform et la destination souhaitée.
Pour créer un flux de données, effectuez une requête POST, comme indiqué ci-après, tout en fournissant les valeurs mentionnées ci-dessous dans le payload.
Effectuez la requête POST suivante pour créer un flux de données.
Format d’API
POST /flows
Requête
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}
: l’identifiant de spécification de flux pour les destinations basées sur le profil est71471eba-b620-49e4-90fd-23f1fa0174d8
. Utilisez cette valeur dans l’appel à .{SOURCE_CONNECTION_ID}
: utilisez l’identifiant de connexion source obtenu à l’étape Connexion à Experience Platform.{TARGET_CONNECTION_ID}
: utilisez l’identifiant de connexion cible obtenu à l’étape Se connecter à la destination de diffusion en streaming.
Réponse
Une réponse réussie renvoie l’identifiant (id
) du nouveau flux de données et un etag
. Notez les deux valeurs comme vous le ferez à l’étape suivante, pour activer les audiences.
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
"etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}
Activation des données vers votre nouvelle destination
Après avoir créé toutes les connexions et le flux de données, vous pouvez maintenant activer vos données de profil sur la plateforme de streaming. Au cours de cette étape, vous sélectionnez les audiences et les attributs de profil que vous envoyez à la destination, puis vous pouvez planifier et envoyer des données à la destination.
Pour activer des audiences vers votre nouvelle destination, vous devez effectuer une opération JSON PATCH, similaire à l’exemple ci-dessous. Vous pouvez activer plusieurs audiences et attributs de profil en un seul appel. Pour en savoir plus sur le JSON PATCH, consultez la spécification RFC.
Format d’API
PATCH /flows
Requête
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}"
}
}
}
]
{DATAFLOW_ID}
{ETAG}
Récupérez le {ETAG}
à partir de la réponse de l’étape précédente, Créer un flux de données. Le format de réponse de l’étape précédente contient des guillemets d’échappement. Vous devez utiliser les valeurs sans échappement dans l’en-tête de la requête. Voir l’exemple ci-dessous :
- Exemple de réponse :
"etag":""7400453a-0000-1a00-0000-62b1c7a90000""
- Valeur à utiliser dans votre demande :
"etag": "7400453a-0000-1a00-0000-62b1c7a90000"
La valeur etag est mise à jour avec chaque mise à jour réussie d’un flux de données.
{SEGMENT_ID}
{PROFILE_ATTRIBUTE}
"person.lastName"
op
add
, replace
et remove
. Pour ajouter une audience à un flux de données, utilisez l’opération add
.path
value
id
name
Réponse
Recherchez une réponse 202 OK. Aucun corps de réponse n’est renvoyé. Pour vérifier que la requête était correcte, reportez-vous à l’étape suivante : validation du flux de données.
Validation du flux de données
La dernière étape du tutoriel consiste à vérifier que les audiences et les attributs de profil ont été correctement mappés au flux de données.
Pour ce faire, effectuez la requête GET suivante :
Format d’API
GET /flows
Requête
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}
: utilisez le flux de données de l’étape précédente.{ETAG}
: utilisez l’etag de l’étape précédente.
Réponse
La réponse renvoyée doit inclure dans le paramètre transformations
les audiences et les attributs de profil que vous avez envoyés à l’étape précédente. Voici un exemple de paramètre transformations
dans la réponse :
"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"
}
}
]
}
}
}
],
Données exportées
{
"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"
}
]
}
}
Utilisation de collections Postman pour la connexion à des destinations de diffusion en continu
Pour vous connecter aux destinations de diffusion en continu décrites dans ce tutoriel de manière plus rationalisée, vous pouvez utiliser Postman.
Postman est un outil que vous pouvez utiliser pour effectuer des appels API et gérer des bibliothèques d’appels et d’environnements prédéfinis.
Pour ce tutoriel spécifique, les collections de Postman suivantes ont été jointes :
- AWS Kinesis Postman collection
- Azure Event Hubs Postman collection
Cliquez ici pour télécharger l’archive des collections.
Chaque collection comprend les requêtes et les variables d’environnement nécessaires, par AWS Kinesis, et Azure Event Hub, respectivement.
Utilisation des collections Postman
Pour établir une connexion aux destinations à l’aide des collections de Postman jointes, procédez comme suit :
- Télécharger et installer Postman ;
- Télécharger et décompresser les collections jointes ;
- importer les collections de leurs dossiers correspondants dans Postman ;
- Renseignez les variables d’environnement conformément aux instructions de cet article.
- Exécutez les requêtes API à partir de Postman, en fonction des instructions de cet article.
Gestion des erreurs d’API
Les points d’entrée d’API de ce tutoriel suivent les principes généraux des messages d’erreur de l’API Experience Platform. Pour plus d’informations sur l’interprétation des réponses d’erreur🔗 consultez les sections Codes d’état API et Erreurs d’en-tête de requête dans le guide de dépannage d’Experience Platform.
Étapes suivantes
En suivant ce tutoriel, vous avez réussi à connecter Experience Platform à l’une de vos destinations de diffusion en continu préférées et à configurer un flux de données vers la destination correspondante. Les données sortantes peuvent désormais être utilisées dans la destination pour Customer Analytics ou toute autre opération de données que vous souhaitez effectuer. Pour plus d’informations, consultez les pages suivantes :