Créez un flux de données pour les sources de succès client à l’aide de l’API Flow Service.
Ce tutoriel décrit les étapes à suivre pour récupérer des données d’une source de succès client et les apporter à Platform à l’aide de l’API Flow Service.
- Pour créer un flux de données, vous devez déjà disposer d’un identifiant de connexion de base valide avec une source de succès client. Si vous ne disposez pas de cet ID, consultez la présentation des sources pour obtenir la liste des sources de succès client avec lesquelles vous pouvez créer une connexion de base.
- Pour que l’Experience Platform puisse ingérer des données, les fuseaux horaires de toutes les sources par lots basées sur un tableau doivent être configurés en UTC.
Prise en main
Ce tutoriel nécessite une compréhension du fonctionnement des composants suivants d’Adobe Experience Platform :
-
Experience Data Model (XDM) System : framework normalisé selon lequel Experience Platform organise les données de l’expérience client.
- Principes de base de la composition des schémas : découvrez les blocs de création de base des schémas XDM, y compris les principes clés et les bonnes pratiques en matière de composition de schémas.
- Guide du développeur de Schema Registry : inclut des informations importantes à connaître avant dʼeffectuer des appels vers l’API Schema Registry. Cela inclut votre
{TENANT_ID}
, le concept de « conteneurs » et les en-têtes requis pour effectuer des requêtes (avec une attention particulière à l’en-tête Accept et à ses valeurs possibles).
-
Catalog Service : le catalogue représente le système d’enregistrement de l’emplacement et de la liaison des données dans Experience Platform.
-
Batch ingestion : l’API Batch Ingestion vous permet d’ingérer des données dans Experience Platform sous forme de fichiers par lots.
-
Sandbox : Experience Platform fournit des sandbox virtuels qui divisent une instance Platform unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.
Utiliser les API Platform
Pour plus d’informations sur la manière d’effectuer correctement des appels vers les API Platform, consultez le guide de Prise en main des API Platform.
Créer une connexion source source
Vous pouvez créer une connexion source en effectuant une requête POST à l’API Flow Service. Une connexion source se compose d’un identifiant de connexion, d’un chemin d’accès au fichier de données source et d’un identifiant de spécification de connexion.
Pour créer une connexion source, vous devez également définir une valeur d’énumération pour l’attribut du format de données.
Utilisez les valeurs d’énumération suivantes pour les connecteurs basés sur des fichiers :
delimited
json
parquet
Pour tous les connecteurs basés sur un tableau, définissez la valeur tabular
.
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": "Source connection for Customer Success",
"baseConnectionId": "f1da3694-38a9-403d-9a36-9438a9203d42",
"description": "Source connection for a Customer Success connector",
"data": {
"format": "tabular",
},
"params": {
"tableName": "Account",
"columns": [
{
"name": "Id",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Name",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Phone",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "CreatedDate",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "cb66ab34-8619-49cb-96d1-39b37ede86ea",
"version": "1.0"
}
}'
baseConnectionId
params.path
connectionSpec.id
Réponse
Une réponse réussie renvoie l’identifiant unique (id
) de la connexion source nouvellement créée. Cet identifiant est requis lors des étapes suivantes pour créer une connexion cible.
{
"id": "17faf955-2cf8-4b15-baf9-552cf88b1540",
"etag": "\"2900a761-0000-0200-0000-5ed18cea0000\""
}
Créer un schéma XDM cible target-schema
Pour que les données sources soient utilisées dans Platform, un schéma cible doit être créé pour structurer les données sources en fonction de vos besoins. Le schéma cible est ensuite utilisé pour créer un jeu de données Platform contenant les données sources.
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, suivez le tutoriel sur la création d’un schéma à l’aide de l’API.
Créer un jeu de données cible target-dataset
Un jeu de données cible peut être créé en adressant une requête POST à l’API Catalog Service et 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, suivez le tutoriel sur la création d’un jeu de données à l’aide de l’API.
Créer une connexion cible target-connection
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 indiquer l’identifiant de spécification de connexion fixe associé au lac de données. Cet identifiant de spécification de connexion est : c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Vous disposez désormais des identifiants uniques d’un schéma cible, d’un jeu de données cible, ainsi que l’identifiant de spécification de connexion au lac de données. À lʼaide de l’API Flow Service, vous pouvez créer une connexion cible en spécifiant ces identifiants ainsi que le jeu de données qui contiendra les données source entrantes.
Format d’API
POST /targetConnections
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": "Target Connection for a customer success connector",
"description": "Target Connection for a customer success connector",
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/deb3e1096c35d8311b5d80868c4bd5b3cdfd4b3150e7345f",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "5e543e8a60b15218ad44b95f"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
data.schema.id
$id
du schéma XDM cible.data.schema.version
application/vnd.adobe.xed-full+json;version=1
, qui renvoie la dernière version mineure du schéma.params.dataSetId
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.Réponse
Une réponse réussie renvoie l’identifiant unique de la nouvelle connexion cible (id
). Cette valeur est requise lors d’une étape ultérieure pour créer un flux de données.
{
"id": "1f5af99c-f1ef-4076-9af9-9cf1ef507678",
"etag": "\"530013e2-0000-0200-0000-5ebc4c110000\""
}
Créer un mappage mapping
Pour que les données sources soient ingérées dans un jeu de données cible, elles doivent d’abord être mappées au schéma cible auquel le jeu de données cible se rattache.
Pour créer un jeu de mappage, envoyez une requête POST au point dʼentrée mappingSets
de lʼData Prep API et indiquez votre schéma XDM cible $id
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/b750bd161fef405bc324d0c8809b02c494d73e60e7ae9b3e",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.fullName",
"sourceAttribute": "Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "_repo.createDate",
"sourceAttribute": "CreatedDate",
"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": "7c3547d3cfc14f568a51c32b4c0ed739",
"version": 0,
"createdDate": 1590792069173,
"modifiedDate": 1590792069173,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Récupérer des spécifications du flux de données specs
Un flux de données est chargé de collecter des données à partir de sources et de les importer dans Platform. Pour créer un flux de données, vous devez d’abord obtenir les spécifications du flux de données en adressant une requête GET à l’API Flow Service. Les spécifications de flux de données sont chargées de collecter les données d’un système de réussite client tiers.
Format d’API
GET /flowSpecs?property=name=="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 Platform. La réponse inclut la valeur id
unique de spécification de flux requise pour créer un flux de données.
code language-json |
---|
|
flowSpec.id
sourceConnectionIds
targetConnectionIds
transformations.params.mappingId
transformations.params.deltaColum
deltaColumn
est yyyy-MM-dd HH:mm:ss
.transformations.params.mappingId
scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
ou week
.scheduleParams.interval
L’intervalle désigne la période entre deux exécutions consécutives de flux. La valeur de l’intervalle doit être un nombre entier non nul. La valeur minimale de l’intervalle accepté pour chaque fréquence est la suivante :
- Une fois : n/a
- Minute : 15
- Heure : 1
- Jour : 1
- Semaine : 1
Réponse
Une réponse réussie renvoie l’identifiant id
du nouveau flux de données.
{
"id": "e0bd8463-0913-4ca1-bd84-6309134ca1f6",
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
Surveiller votre flux de données
Une fois votre flux de données créé, vous pouvez surveiller les données ingérées pour afficher des informations sur les exécutions du flux, le statut d’achèvement et les erreurs. Pour plus d’informations sur la surveillance des flux de données, consultez le tutoriel sur la surveillance des flux de données dans l’API
Étapes suivantes
Vous êtes arrivé au bout de ce tutoriel, félicitations ! Grâce à celui-ci, vous avez créé un connecteur source pour collecter des données d’un système de succès client à intervalles réguliers. Les données entrantes peuvent désormais être utilisées par des services Platform en aval tels que Real-Time Customer Profile et Data Science Workspace. Consultez les documents suivants pour plus d’informations :
Annexe
La section suivante répertorie les différents connecteurs de source de stockage dans le cloud et leurs spécifications de connexion.
Spécification de connexion
cb66ab34-8619-49cb-96d1-39b37ede86ea
eb13cb25-47ab-407f-ba89-c0125281c563