Ce tutoriel explique comment utiliser les appels API pour accéder à vos données Adobe Experience Platform, créer une destination de marketing par e-mail, 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 Adobe Campaign dans tous ses exemples, mais les étapes sont identiques pour toutes les destinations de marketing par e-mail.
Si vous préférez utiliser l'interface utilisateur de Platform pour connecter une destination et activer des données, consultez les didacticiels Connecter une destination et Activer les profils et segments à une destination.
Ce guide nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :
Les sections suivantes fournissent des informations supplémentaires dont vous aurez besoin pour activer les données vers les destinations de marketing par courrier électronique dans Platform.
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 activez des segments.
accessId
, secretKey
domain
, port
, username
, password
ou ssh key
(selon la méthode de connexion à l’emplacement FTP)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 d’API, voir la section concernant la lecture d’exemples d’appels d’API dans le guide de dépannageExperience Platform.
Pour lancer des appels aux API Platform, vous devez d’abord suivre le tutoriel d’authentification. Le tutoriel d’authentification fournit les valeurs de chacun des en-têtes requis dans tous les appels d’API Experience Platform, comme indiqué ci-dessous :
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Les ressources de Experience Platform peuvent être isolées dans des sandbox virtuels spécifiques. Dans les demandes aux API Platform, vous pouvez spécifier le nom et l'ID du sandbox dans lequel l'opération aura lieu. Il s’agit de paramètres facultatifs.
{SANDBOX_NAME}
Pour plus d'informations sur les sandbox dans Experience Platform, consultez la documentation d'aperçu de sandbox.
Toutes les requêtes qui contiennent un payload (POST, PUT, PATCH) nécessitent un en-tête de type de média supplémentaire :
application/json
Ce tutoriel vous permet de trouver dans Swagger la documentation de référence relative à tous les appels API. Consultez la documentation de l’API du service de flux sur Adobe.io. Nous vous recommandons de consulter ce tutoriel et la page de documentation de Swagger en parallèle.
Dans un premier temps, vous devez décider vers quelle destination de marketing par e-mail activer les données. Pour commencer, effectuez un appel pour demander une liste des destinations disponibles auxquelles vous pouvez vous connecter et activer des segments. Effectuez la requête GET suivante auprès du point de terminaison 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: {IMS_ORG}' \
--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 fournir des segments à Adobe Campaign, recherchez l’extrait suivant dans la réponse :
{
"id": "0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
"name": "Adobe Campaign",
...
...
}
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.
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: {IMS_ORG}' \
--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 le service de profil unifié - 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"
}
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: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connecting to Unified Profile Service",
"description": "Optional",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"baseConnectionId": "{BASE_CONNECTION_ID}",
"data": {
"format": "CSV",
"schema": null
},
"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 Unified Profile Service - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Réponse
Une réponse réussie renvoie l'identifiant unique (id
) pour la connexion source nouvellement créée à Unified Profile Service. Ceci confirme que vous êtes connecté avec succès à vos données Experience Platform. Conservez cette valeur car elle sera nécessaire lors d’une prochaine étape.
{
"id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}
Au cours de cette étape, vous établissez une connexion avec la destination de marketing par e-mail de votre choix. Il s’agit de deux sous-étapes présentées ci-dessous.
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: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "S3 Connection for Adobe Campaign",
"description": "summer advertising campaign",
"connectionSpec": {
"id": "{_CONNECTION_SPEC_ID}",
"version": "1.0"
},
"auth": {
"specName": "{S3 or SFTP}",
"params": {
"accessId": "{ACCESS_ID}",
"secretKey": "{SECRET_KEY}"
}
}
}'
{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.{S3 or SFTP}
: indiquez le type de connexion souhaité pour cette destination. Dans le catalogue des destinations, faites défiler jusqu’à la destination de votre choix pour voir si les types de connexion S3 et/ou SFTP sont pris en charge.{ACCESS_ID}
Amazon : votre identifiant d’accès pour votre emplacement de stockage S3.{SECRET_KEY}
Amazon : votre clé secrète pour votre emplacement de stockage S3.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"
}
Format d’API
POST /targetConnections
Requête
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: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "TargetConnection for Adobe Campaign",
"description": "Connection to Adobe Campaign",
"baseConnectionId": "{BASE_CONNECTION_ID}",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"data": {
"format": "json",
"schema": {
"id": "1.0",
"version": "1.0"
}
},
"params": {
"mode": "S3",
"bucketName": "{BUCKETNAME}",
"path": "{FILEPATH}",
"format": "CSV"
}
}'
{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.{BUCKETNAME}
: Votre compartiment Amazon S3, où Platform dépose l'exportation de données.{FILEPATH}
: Chemin d’accès dans votre répertoire de compartiment Amazon S3 où Platform dépose l’exportation des données.Réponse
Une réponse réussie renvoie l’identifiant unique (id
) de la nouvelle connexion cible à votre destination de marketing par e-mail. Conservez cette valeur car elle sera nécessaire lors de prochaines étapes.
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
En utilisant les ID que vous avez 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 à laquelle vous allez activer les données. Considérez cette étape comme la construction du pipeline, à travers lequel les données seront acheminées ultérieurement, 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Activate segments to Adobe Campaign",
"description": "This operation creates a dataflow which we will later use to activate segments to Adobe Campaign",
"flowSpec": {
"id": "{FLOW_SPEC_ID}",
"version": "1.0"
},
"sourceConnectionIds": [
"{SOURCE_CONNECTION_ID}"
],
"targetConnectionIds": [
"{TARGET_CONNECTION_ID}"
],
"transformations": [
{
"name": "GeneralTransform",
"params": {
"segmentSelectors": {
"selectors": []
},
"profileSelectors": {
"selectors": []
}
}
}
]
}
{FLOW_SPEC_ID}
: utilisez le flux pour la destination de marketing par e-mail à laquelle vous souhaitez vous connecter. Pour obtenir la spécification du flux, effectuez une opération GET sur le point de terminaison flowspecs
. Consultez la documentation Swagger ici : https://platform.adobe.io/data/foundation/flowservice/swagger#/Flow%20Specs%20API/getFlowSpecs. Dans la réponse, recherchez upsTo
et copiez l’identifiant correspondant à la destination de marketing par e-mail à laquelle vous souhaitez vous connecter. Par exemple, pour Adobe Campaign, recherchez upsToCampaign
et copiez le paramètre id
.{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 Connexion à une destination de marketing par e-mail.Réponse
Une réponse réussie renvoie l’identifiant (id
) du nouveau flux de données et un etag
. Notez les deux valeurs car vous en aurez besoin à l’étape suivante pour activer les segments.
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
"etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}
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 marketing par e-mail. Au cours de cette étape, vous sélectionnez les segments et les attributs de profil que vous envoyez à la destination et vous pouvez planifier et envoyer des données à la destination.
Pour activer les segments vers votre nouvelle destination, vous devez effectuer une opération JSON PATCH, comme dans l’exemple ci-dessous. Vous pouvez activer plusieurs segments et attributs de profil lors d’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: {IMS_ORG}' \
--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/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}"
}
}
}
]
{DATAFLOW_ID}
: utilisez le flux de données obtenu à l’étape précédente.{ETAG}
: utilisez l’etag obtenu à l’étape précédente.{SEGMENT_ID}
: indiquez l’identifiant du segment que vous souhaitez exporter vers cette destination. Pour récupérer les ID de segment pour les segments que vous souhaitez activer, accédez à https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/, sélectionnez Segmentation Service API dans le menu de navigation de gauche et recherchez l'opération GET /segment/definitions
dans Segment Definitions.{PROFILE_ATTRIBUTE}
: par exemple, "person.lastName"
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.
La dernière étape du tutoriel consiste à vérifier que les segments 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: {IMS_ORG}' \
--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 segments 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": []
},
"segmentSelectors": {
"selectors": [
{
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Men over 50",
"description": "",
"id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
}
}
]
}
}
}
],
En suivant ce didacticiel, vous avez réussi à connecter Plateforme à l’une de vos destinations de marketing par courriel 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 des campagnes par e-mail, de la publicité ciblée et de nombreux autres cas d’utilisation. Pour plus d’informations, consultez les pages suivantes :