Show Menu
SUJETS×

Créez des destinations marketing par courrier électronique et activez les données à l’aide d’appels d’API dans le Adobe. Real-time Customer Data Platform

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 la plateforme de données clients en temps réel d’Adobe pour connecter une destination et activer des données, consultez les tutoriels Connexion d’une destination et Activation de profils et de segments vers une destination .

Prise en main

Ce guide nécessite une compréhension professionnelle des composants suivants d’Adobe Experience Platform :
  • Système de modèle de données d’expérience (XDM) : Cadre normalisé selon lequel Experience Platform organiser les données d’expérience client.
  • Service de catalogue : Catalog est le système d’enregistrement pour l’emplacement et le lignage des données dans Experience Platform.
  • Sandbox : Experience Platform fournit des sandbox virtuels qui partitionnent une Platform instance unique en environnements virtuels distincts pour aider à développer et développer des applications d'expérience numérique.
Les sections suivantes apportent des informations supplémentaires dont vous aurez besoin afin d’activer les données vers les destinations de marketing par e-mail dans la plateforme de données clients en temps réel d’Adobe.

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.
  • For Amazon S3 connections to email marketing platforms: 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. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

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

In order to make calls to Platform APIs, you must first complete the authentication tutorial . Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:
  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Resources in Experience Platform can be isolated to specific virtual sandboxes. In requests to Platform APIs, you can specify the name and ID of the sandbox that the operation will take place in. Il s’agit de paramètres facultatifs.
  • x-sandbox-name: {SANDBOX_NAME}
For more information on sandboxes in Experience Platform, see the sandbox overview documentation .
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. Reportez-vous à la documentation de l’API Flow Service sur Adobe.io . 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",
  ...
  ...
}

Connect to your Experience Platform data

Next, you must connect to your Experience Platform data, so you can export profile data and activate it in your preferred destination. Il s’agit de deux sous-étapes présentées ci-dessous.
  1. First, you must perform a call to authorize access to your data in Experience Platform, by setting up a base connection.
  2. Then, using the base connection ID, you will make another call in which you create a source connection, which establishes the connection to your Experience Platform data.

Authorize access to your data in 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 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"
}

Connect to your Experience Platform data

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
A successful response returns the unique identifier ( id ) for the newly created source connection to Unified Profile Service. This confirms that you have successfully connected to your Experience Platform data. 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": "your company's holiday 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

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} Amazon : votre compartiment S3, où la plateforme de données clients en temps réel dépose les données exportées.
  • {FILEPATH} Amazon : chemin d’accès dans le répertoire de votre compartiment S3 où la plateforme de données clients en temps réel 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

Using the IDs you obtained in the previous steps, you can now create a dataflow between your Experience Platform data and the destination where you will activate data to. Think of this step as constructing the pipeline, through which data will later flow, between Experience Platform and your desired destination.
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 Segmentation Service API dans le menu de navigation de gauche et recherchez l’ GET /segment/definitions opération 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 la plateforme de données clients en temps réel à l’une de vos destinations de marketing par e-mail préférées et à mettre en place 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 :