Connexion aux destinations de marketing par e-mail et activation des données à l’aide de l’API Flow Service

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 tutoriels Connexion d’une destination et Activation des profils et des segments vers une destination.

Prise en main

Ce guide nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :

• Experience Data Model (XDM) System : cadre 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.
• Sandboxes: Experience Platform fournit des environnements de test virtuels qui divisent une Platform instance unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience numérique.

Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin pour activer les données vers les destinations de marketing par e-mail dans Platform.

Collecte des 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 activez des segments.

• Pour les connexions Amazon S3 aux plateformes de marketing par e-mail : accessId, secretKey
• Pour les connexions SFTP aux plateformes de marketing par e-mail : domain, port, username, password ou ssh key (selon la méthode de connexion à l’emplacement FTP)

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 d'API, voir la section concernant la lecture d'exemples d'appels d'API dans le guide de dépannageExperience Platform.

Collecte de valeurs pour les en-têtes requis et facultatifs

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 :

• Authorization: Bearer {ACCESS_TOKEN}
• x-api-key : {API_KEY}
• x-gw-ims-org-id : {IMS_ORG}

Les ressources de Experience Platform peuvent être isolées dans des environnements de test virtuels spécifiques. Dans les demandes aux API Platform, vous pouvez spécifier le nom et l’identifiant de l’environnement de test 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. Consultez la documentation de l’API de service de flux 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 disponibles

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

Connexion à vos données Experience Platform

Ensuite, vous devez vous connecter à vos données Experience Platform afin de pouvoir exporter les données de profil et les activer dans la destination de votre choix. Il s’agit de deux sous-étapes présentées ci-dessous.

1. 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.
2. 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 à vos données Experience Platform.

Autoriser l’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: {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 - 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: {IMS_ORG}' \
--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": "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 Profile Service - 8a9c3494-9708-43d7-ae3f-cda01e5030e1.

Réponse

Une réponse réussie renvoie l’identifiant unique (id) de la nouvelle connexion source à Profile Service. 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"
}

Connexion à une destination de marketing par e-mail

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.

1. Tout d’abord, vous devez effectuer un appel pour autoriser l’accès au fournisseur de service de messagerie électronique, en établissant une connexion de base.
2. 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.

Autorisation d’accès à la destination de marketing par e-mail

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

Indication de l’emplacement de stockage et du format des données

Adobe Experience Platform exporte les données pour les destinations de marketing par e-mail et de stockage dans le cloud sous la forme de CSV fichiers.

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 les données exportées.
• {FILEPATH}: Chemin d’accès dans votre répertoire de compartiment Amazon S3 où Platform dépose les données exporté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"
}

Création d’un flux de données

En utilisant les identifiants 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 vers laquelle vous activerez les données. Considérez cette étape comme la création du pipeline, par lequel les données seront transmises 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"
}

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 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 API Segmentation Service dans le menu de navigation de gauche, puis recherchez l’opération GET /segment/definitions dans Définitions de segment.
• {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.

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

Étapes suivantes

En suivant ce tutoriel, vous avez réussi à connecter Platform à l’une de vos destinations de marketing par e-mail 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 :

• Présentation des destinations
• Présentation du catalogue des destinations