Se connecter aux destinations de marketing par courrier électronique et activer les données à l’aide d’appels d’API

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.

Présentation : étapes de création d’une destination et d’activation de segments

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.

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 pour l’emplacement et le lignage des données dans Experience Platform.
  • Sandboxes: 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 fournissent des informations supplémentaires dont vous aurez besoin pour activer les données vers les destinations de marketing par courrier électronique 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 courriel : 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 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.

  • x-sandbox-name: {SANDBOX_NAME}
REMARQUE

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 :

  • 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 du service de flux 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

Présentation des étapes de la destination : étape 1

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

Se connecter à vos données Experience Platform

Présentation des étapes de la destination : étape 2

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.

  1. Tout d'abord, vous devez effectuer un appel pour autoriser l'accès à vos données dans Experience Platform, en configurant une connexion de base.
  2. Ensuite, en utilisant l'ID de connexion de base, vous effectuerez un autre appel dans lequel vous créez une connexion source, qui établit 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 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"
}

Se connecter à 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 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"
}

Connexion à une destination de marketing par e-mail

Présentation des étapes de la destination : étape 3

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

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

Création d’un flux de données

Présentation des étapes de la destination : étape 4

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

Activation des données vers votre nouvelle destination

Présentation des étapes de la destination : étape 5

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.

Validation du flux de données

Présentation des étapes de la destination : étape 6

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

Sur cette page