Création d’un flux de données pour ingérer des données d’un CRM dans Experience Platform
Lisez ce guide pour savoir comment créer un flux de données et ingérer des données dans Adobe Experience Platform à l’aide de l’Flow Service API.
Commencer
Ce guide nécessite une compréhension professionnelle des composants suivants d’Experience Platform :
- Ingestion par lots : découvrez comment charger rapidement et efficacement d’importants volumes de données par lots.
- Service de catalogue : organisez et suivez vos jeux de données dans Experience Platform.
- Préparation de données : transformez et mappez vos données entrantes pour qu’elles correspondent aux exigences de votre schéma.
- Flux de données : configurez et gérez les pipelines qui déplacent vos données des sources vers les destinations.
- Schémas de modèle de données d’expérience (XDM) : structurez vos données à l’aide de schémas XDM afin qu’elles soient prêtes à être utilisées dans Experience Platform.
- Sandbox : testez et développez en toute sécurité dans des environnements isolés sans affecter les données de production.
- Sources : découvrez comment connecter vos sources de données externes à Experience Platform.
Utilisation des API Experience Platform
Pour plus d’informations sur la manière d’effectuer avec succès des appels vers les API Experience Platform, consultez le guide sur la Prise en main des API Experience Platform.
Créer une connexion de base base
Pour créer un flux de données pour votre source, vous aurez besoin d’un compte source entièrement authentifié et de son identifiant de connexion de base correspondant. Si vous ne disposez pas de cet identifiant, consultez le catalogue de sources pour trouver une liste de sources pour lesquelles vous pouvez créer une connexion de base.
Créer un schéma XDM cible target-schema
Un schéma de modèle de données d’expérience (XDM) offre un moyen normalisé d’organiser et de décrire les données d’expérience client dans Experience Platform. Pour ingérer les données sources dans Experience Platform, vous devez d’abord créer un schéma XDM cible qui définit la structure et les types de données à ingérer. Ce schéma sert de plan directeur pour le jeu de données Experience Platform où se trouveront vos données ingérées.
Un schéma XDM cible peut être créé en adressant une requête POST à l’API Schema Registry. Pour obtenir des instructions détaillées sur la création d’un schéma XDM cible, consultez les guides suivants :
Une fois créé, le schéma XDM cible $id
sera requis ultérieurement pour votre jeu de données cible et votre mappage.
Créer un jeu de données cible target-dataset
Un jeu de données est une structure de stockage et de gestion pour une collection de données, généralement structurée comme un tableau avec des colonnes (schéma) et des lignes (champs). Les données correctement ingérées par Experience Platform sont stockées dans le lac de données sous forme de jeux de données. Au cours de cette étape, vous pouvez créer un jeu de données ou en utiliser un existant.
Vous pouvez créer un jeu de données cible en adressant une requête POST à l’API Catalog Service, tout en fournissant l’identifiant du schéma cible dans la payload. Pour obtenir des instructions détaillées sur la création d’un jeu de données cible, consultez le guide création d’un jeu de données à l’aide de l’API.
Format d’API
code language-http |
---|
|
Requête
L’exemple suivant montre comment créer un jeu de données cible activé pour l’ingestion du profil client en temps réel. Dans cette requête, la propriété unifiedProfile
est définie sur true
(sous l’objet tags
), ce qui indique à Experience Platform d’inclure le jeu de données dans le profil client en temps réel.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propriété | Description |
name |
Nom explicite de votre jeu de données cible. Utilisez un nom clair et unique pour faciliter l’identification et la gestion de votre jeu de données dans les opérations futures. |
schemaRef.id |
Identifiant de votre schéma XDM cible. |
tags.unifiedProfile |
Valeur booléenne qui indique à Experience Platform si les données doivent être ingérées dans le profil client en temps réel. |
Réponse
Une réponse réussie renvoie l’identifiant de votre jeu de données cible. Cet identifiant est requis ultérieurement pour créer une connexion cible.
code language-json |
---|
|
Créer une connexion source source
Une connexion source définit la manière dont les données sont importées dans Experience Platform à partir d’une source externe. Il spécifie à la fois le système source et le format des données entrantes, et il fait référence à une connexion de base contenant des détails d’authentification. Chaque connexion source est propre à votre organisation.
- Pour les sources basées sur des fichiers (telles que les stockages dans le cloud), une connexion source peut inclure des paramètres tels que le délimiteur de colonne, le type de codage, le type de compression, les expressions régulières pour la sélection de fichiers et le fait d’ingérer des fichiers de manière récursive ou non.
- Pour les sources basées sur un tableau (telles que les bases de données, les CRM et les fournisseurs d’automatisation marketing), une connexion source peut spécifier des détails tels que le nom du tableau et les mappages de colonnes.
Pour créer une connexion source, envoyez une requête POST au point d’entrée /sourceConnections
de l’API Flow Service et indiquez votre identifiant de connexion de base, l’identifiant de spécification de connexion et le chemin d’accès au fichier de données source.
Format d’API
POST /sourceConnections
Requête
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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": "ACME source connection",
"description": "A source connection for ACME contact data",
"baseConnectionId": "6990abad-977d-41b9-a85d-17ea8cf1c0e4",
"data": {
"format": "tabular"
},
"params": {
"tableName": "Contact",
"columns": [
{
"name": "TestID",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Name",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Datefield",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"version": "1.0"
}
}'
name
description
baseConnectionId
id
de votre connexion de base. Vous pouvez récupérer cet identifiant en authentifiant votre source sur Experience Platform à l’aide de l’API Flow Service.data.format
tabular
pour les sources basées sur des tableaux (telles que les bases de données, les CRM et les fournisseurs d’automatisation marketing).params.tableName
params.columns
connectionSpec.id
Réponse
Une réponse réussie renvoie l’identifiant de votre connexion source. Cet identifiant est requis pour créer un flux de données et ingérer vos données.
{
"id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
"etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}
Créer une connexion cible target
Une connexion cible représente la connexion à la destination où se trouvent les données ingérées. Pour créer une connexion cible, vous devez fournir l’identifiant fixe de spécification de connexion associé au lac de données. Cet identifiant de spécification de connexion est : c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Format d’API
POST /targetConnections
Requête
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-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": "ACME target connection",
"description": "ACME target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6889f4f89b982b2b90bc1207"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
name
description
data.schema.id
params.dataSetId
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.Mappage mapping
Mappez ensuite vos données source au schéma cible auquel votre jeu de données cible se conforme. Pour créer un mappage, envoyez une requête POST au point d’entrée mappingSets
de l’Data Prep API. Incluez votre identifiant de schéma XDM cible et les détails des jeux de mappages que vous souhaitez créer.
Format d’API
POST /mappingSets
Requête
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-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 '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "TestID",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.fullName",
"sourceAttribute": "Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.birthDate",
"sourceAttribute": "Datefield",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchema
$id
du schéma XDM cible.Réponse
Une réponse réussie renvoie les détails du mappage nouvellement créé, y compris son identifiant unique (id
). Cet identifiant est requis lors d’une étape ultérieure pour créer un flux de données.
{
"id": "93ddfa69c4864d978832b1e5ef6ec3b9",
"version": 0,
"createdDate": 1612309018666,
"modifiedDate": 1612309018666,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Récupérer des spécifications du flux de données flow-specs
Avant de pouvoir créer un flux de données, vous devez d’abord récupérer les spécifications du flux de données qui correspondent à votre source. Pour récupérer ces informations, envoyez une requête GET au point d’entrée /flowSpecs
de l’API Flow Service.
Format d’API
GET /flowSpecs?property=name=="{NAME}"
property=name=="{NAME}"
Nom de votre spécification de flux de données.
- Pour les sources basées sur des fichiers (telles que l’espace de stockage dans le cloud), définissez cette valeur sur
CloudStorageToAEP
. - Pour les sources basées sur des tableaux (telles que les bases de données, les CRM et les fournisseurs d’automatisation marketing), définissez cette valeur sur
CRMToAEP
.
Requête
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="CRMToAEP"' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Réponse
Une réponse réussie renvoie les détails de la spécification du flux de données responsable de l’importation des données de votre source dans Experience Platform. La réponse inclut la valeur id
unique de spécification de flux requise pour créer un flux de données.
Pour vous assurer que vous utilisez la spécification de flux de données appropriée, vérifiez le tableau items.sourceConnectionSpecIds
dans la réponse. Vérifiez que l’identifiant de spécification de connexion pour votre source est inclus dans cette liste.
code language-json |
---|
|
Créer un flux de données dataflow
Un flux de données est un pipeline configuré qui transfère des données entre les services Experience Platform. Il définit la manière dont les données sont ingérées à partir de sources externes (telles que des bases de données, un espace de stockage dans le cloud ou des API), traitées et acheminées vers des jeux de données cibles. Ces jeux de données sont ensuite utilisés par des services tels que le service d’identités, le profil client en temps réel et Destinations pour l’activation et l’analyse.
Pour créer un flux de données, vous devez fournir des valeurs pour les éléments suivants :
Au cours de cette étape, vous pouvez utiliser les paramètres suivants dans scheduleParams
pour configurer un planning d’ingestion pour votre flux de données :
startTime
frequency
Fréquence d’ingestion. Configurez la fréquence pour indiquer la fréquence d’exécution du flux de données. Vous pouvez définir la fréquence sur :
once
: définissez la fréquence suronce
pour créer une ingestion unique. Les paramètres d’intervalle et de renvoi ne sont pas disponibles pour les tâches d’ingestion uniques. Par défaut, la fréquence de planification est définie sur une seule fois.minute
: définissez la fréquence surminute
pour planifier le flux de données afin d’ingérer les données par minute.hour
: définissez la fréquence surhour
pour planifier le flux de données afin d’ingérer les données toutes les heures.day
: définissez la fréquence surday
pour planifier le flux de données afin d’ingérer les données par jour.week
: définissez la fréquence surweek
afin de planifier le flux de données pour l’ingestion de données sur une base hebdomadaire.
interval
Intervalle entre des ingestions consécutives (requis pour toutes les fréquences, à l’exception de once
). Configurez le paramètre d’intervalle pour établir la période entre chaque ingestion. Par exemple, si votre fréquence est définie sur le jour et que l’intervalle est de 15, le flux de données s’exécute tous les 15 jours. Vous ne pouvez pas définir l’intervalle sur zéro. La valeur d’intervalle minimale acceptée pour chaque fréquence est la suivante :
once
: s.o.minute
: 15hour
: 1day
: 1week
: 1
backfill
startTime
.Format d’API
POST /flows
Requête
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "ACME Contact Dataflow",
"description": "A dataflow for ACME contact data",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"b7581b59-c603-4df1-a689-d23d7ac440f3"
],
"targetConnectionIds": [
"320f119a-5ac1-4ab1-88ea-eb19e674ea2e"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "Datefield",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "93ddfa69c4864d978832b1e5ef6ec3b9",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1612310466",
"frequency":"minute",
"interval":"15",
"backfill": "true"
}
}'
name
description
flowSpec.id
sourceConnectionIds
targetConnectionIds
transformations.params.deltaColum
deltaColumn
est yyyy-MM-dd HH:mm:ss
. Par Microsoft Dynamics, le format pris en charge pour deltaColumn
est yyyy-MM-ddTHH:mm:ssZ
.transformations.params.deltaColumn.dateFormat
transformations.params.deltaColumn.timeZone
transformations.params.mappingId
scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
ou week
.scheduleParams.interval
scheduleParams.backfill
true
ou false
) qui détermine s’il faut ingérer des données historiques (renvoi) lors de la première création du flux de données.Réponse
Une réponse réussie renvoie l’identifiant (id
) du flux de données nouvellement créé.
{
"id": "ae0a9777-b322-4ac1-b0ed-48ae9e497c7e",
"etag": "\"770029f8-0000-0200-0000-6019e7d40000\""
}
Utiliser l’interface utilisateur pour valider le workflow de l’API validate-in-ui
Vous pouvez utiliser l’interface utilisateur d’Experience Platform pour valider la création de votre flux de données. Accédez au catalogue Sources dans l’interface utilisateur d’Experience Platform, puis sélectionnez Flux de données dans les onglets d’en-tête. Ensuite, utilisez la colonne Nom du flux de données et recherchez le flux de données que vous avez créé à l’aide de l’API Flow Service.
Vous pouvez valider davantage votre flux de données par le biais de l’interface Activité de flux de données. Utilisez le rail de droite pour afficher les informations utilisation de l’API de votre flux de données. Cette section affiche le même ID de flux de données, l’ID de jeu de données et l’ID de mappage que ceux générés lors du processus de création de flux de données dans Flow Service.
Étapes suivantes
Ce tutoriel vous a guidé tout au long du processus de création d’un flux de données dans Experience Platform à l’aide de l’API Flow Service. Vous avez appris à créer et configurer les composants nécessaires, notamment le schéma XDM cible, le jeu de données, la connexion source, la connexion cible et le flux de données lui-même. En suivant ces étapes, vous pouvez automatiser l’ingestion des données provenant de sources externes dans Experience Platform, ce qui permet aux services en aval tels que le profil client en temps réel et Destinations d’exploiter vos données ingérées pour des cas d’utilisation avancés.
Surveiller votre flux de données
Une fois votre flux de données créé, vous pouvez surveiller ses performances directement dans l’interface utilisateur d’Experience Platform. Cela inclut le suivi des taux d’ingestion, des mesures de succès et des erreurs qui se produisent. Pour plus d’informations sur la surveillance des flux de données, consultez le tutoriel sur la surveillance des comptes et des flux de données.
Mettre à jour votre flux de données
Pour mettre à jour des configurations pour la planification, le mappage ou des informations générales de vos flux de données, consultez le tutoriel sur la mise à jour des flux de données sources.
Supprimer le flux de données
Vous pouvez supprimer les flux de données qui ne sont plus nécessaires ou qui ont été créés de manière incorrecte à l’aide de la fonction Supprimer, disponible dans l’espace de travail Flux de données. Pour plus d’informations sur la suppression des flux de données, consultez le tutoriel sur la suppression de flux de données.