[Version bêta]{class="badge informative"}
Créez une connexion source et un flux de données pour diffuser des données YOURSOURCE à l’aide de l’API Flow Service
Au fur et à mesure que vous parcourez ce modèle, remplacez ou supprimez tous les paragraphes en italique (en commençant par celui-ci).
Commencez par mettre à jour les métadonnées (titre et description) en haut de la page. Veuillez ignorer toutes les instances de DNL sur cette page. Il s’agit d’une balise qui aide nos processus de traduction automatique à traduire correctement la page dans les différentes langues que nous prenons en charge. Nous ajouterons des balises à votre documentation une fois que vous l’aurez envoyée.
Vue d’ensemble
Donnez un bref aperçu de votre entreprise, y compris de la valeur qu'elle offre aux clients. Insérez un lien vers la page d’accueil de la documentation de votre produit pour en savoir plus.
Conditions préalables
Ajoutez dans cette section des informations sur tout ce que les clients doivent savoir avant de commencer à configurer la source dans l’interface utilisateur de Adobe Experience Platform. Cela peut concerner :
- ajout nécessaire à une liste autorisée
- exigences relatives au hachage des e-mails
- toutes les caractéristiques du compte de votre côté
- comment obtenir une clé API pour se connecter à votre plateforme
Collecter les informations d’identification requises
Pour connecter YOURSOURCE à Experience Platform, vous devez fournir des valeurs pour les propriétés de connexion suivantes :
Pour plus d’informations sur ces informations d’identification, consultez la documentation sur l’authentification YOURSOURCE. Ajoutez un lien vers la documentation d’authentification de votre plateforme ici.
Intégrer YOURSOURCE à votre webhook
La diffusion en continu de SDK nécessite que votre source soit en mesure de prendre en charge les Webhooks pour communiquer avec l’Experience Platform. Dans cette section, vous devez indiquer les étapes que vos utilisateurs devront suivre pour intégrer YOURSOURCE à un webhook.
Connectez YOURSOURCE à Platform à l’aide de l’API Flow Service
Le tutoriel suivant vous guide tout au long des étapes nécessaires à la création d’une connexion source YOURSOURCE et à la création d’un flux de données pour importer les données YOURSOURCE dans Platform à l’aide de l’API Flow Service.
Créer une connexion source source-connection
Créez une connexion source en adressant une requête de POST à l’API Flow Service, tout en fournissant l’identifiant de spécification de connexion de votre source, des détails tels que le nom et la description, ainsi que le format de vos données.
Format d’API
POST /sourceConnections
Requête
La requête suivante crée une connexion source pour YOURSOURCE :
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": "Streaming Source Connection for a Streaming SDK source",
"providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
"description": "Streaming Source Connection for a Streaming SDK source",
"connectionSpec": {
"id": "e77fd9d2-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"data": {
"format": "json"
}
}'
name
description
connectionSpec.id
data.format
json
est le seul à être pris en charge.Réponse
Une réponse réussie renvoie l’identifiant unique (id
) de la nouvelle connexion source. Cet identifiant est requis lors d’une étape ultérieure pour créer un flux de données.
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}
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ù les données ingérées doivent être stockées. Pour créer une connexion cible, vous devez fournir l’identifiant fixe de spécification de connexion qui correspond au lac de données. Cet identifiant 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 et de l’identifiant de spécification de connexion au lac de données. À lʼaide de ces identifiants, vous pouvez créer une connexion cible à l’aide de l’API Flow Service pour spécifier le jeu de données qui contiendra les données source entrantes.
Format d’API
POST /targetConnections
Requête
La requête suivante crée une connexion cible pour YOURSOURCE :
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": "Streaming Target Connection for a Streaming SDK source",
"description": "Streaming Target Connection for a Streaming SDK source",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json",
"schema": {
"id": "{TARGET_XDM_SCHEMA}",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "{TARGET_DATASET}"
}
}'
name
description
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
.data.format
params.dataSetId
Réponse
Une réponse réussie renvoie l’identifiant unique de la nouvelle connexion cible (id
). Cet identifiant est requis aux étapes suivantes.
{
"id": "7c96c827-3ffd-460c-a573-e9558f72f263",
"etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}
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 ce faire, il suffit d’adresser une requête de POST à Data Prep API avec des mappages de données définis dans la payload de la requête.
Format d’API
POST /conversion/mappingSets
Requête
curl -X POST \
'https://platform.adobe.io/data/foundation/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": "{TARGET_XDM_SCHEMA}",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "firstName",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "lastName",
"identity": false,
"version": 0
}
]
}'
xdmSchema
mappings.destinationXdmPath
mappings.sourceAttribute
mappings.identity
Réponse
Une réponse réussie renvoie les détails du mappage nouvellement créé, y compris son identifiant unique (id
). Cette valeur est requise lors d’une étape ultérieure pour créer un flux de données.
{
"id": "bf5286a9c1ad4266baca76ba3adc9366",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Créer un flux flow
La dernière étape pour importer des données de YOURSOURCE vers Platform consiste à créer un flux de données. Vous disposez à présent des valeurs requises suivantes :
Un flux de données est chargé de planifier et de collecter les données provenant d’une source. Vous pouvez créer un flux de données en exécutant une requête POST et en fournissant les valeurs mentionnées précédemment dans la payload.
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": "Streaming Dataflow for a Streaming SDK source",
"description": "Streaming Dataflow for a Streaming SDK source",
"flowSpec": {
"id": "e77fde5a-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": 0
}
}
]
}'
name
description
flowSpec.id
e77fde5a-22a8-11ed-861d-0242ac120002
.flowSpec.version
1.0
.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
.Réponse
Une réponse réussie renvoie l’identifiant (id
) du flux de données nouvellement créé. Vous pouvez utiliser cet identifiant pour surveiller, mettre à jour ou supprimer votre flux de données.
{
"id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
"etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}
Obtention de l’URL du point d’entrée de diffusion en continu
Une fois votre flux de données créé, vous pouvez récupérer votre URL de point d’entrée de diffusion en continu. Vous utiliserez cette URL de point d’entrée pour abonner votre source à un webhook, ce qui permettra à votre source de communiquer avec Experience Platform.
Pour récupérer l’URL de votre point d’entrée de diffusion en continu, envoyez une requête de GET au point d’entrée de /flows
et indiquez l’identifiant de votre flux de données.
Format d’API
GET /flows/{FLOW_ID}
Requête
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flows/993f908f-3342-4d9c-9f3c-5aa9a189ca1a' \
-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}'
Réponse
Une réponse réussie renvoie des informations sur votre flux de données, y compris votre URL de point d’entrée, marquée comme inletUrl
.
{
"items": [
{
"id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
"createdAt": 1669238699119,
"updatedAt": 1669238699119,
"createdBy": "acme@AdobeID",
"updatedBy": "acme@AdobeID",
"createdClient": "{CREATED_CLIENT}",
"updatedClient": "{UPDATED_CLIENT}",
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"imsOrgId": "{ORG_ID}",
"name": "Streaming Dataflow for a Streaming SDK source",
"description": "Streaming Dataflow for a Streaming SDK source",
"flowSpec": {
"id": "e77fde5a-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"state": "enabled",
"version": "\"a1011225-0000-0200-0000-63c78ae60000\"",
"etag": "\"a1011225-0000-0200-0000-63c78ae60000\"",
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"inheritedAttributes": {
"properties": {
"isSourceFlow": true
},
"sourceConnections": [
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"connectionSpec": {
"id": "bdb5b792-451b-42de-acf8-15f3195821de",
"version": "1.0"
}
}
],
"targetConnections": [
{
"id": "7c96c827-3ffd-460c-a573-e9558f72f263",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}
]
},
"options": {
"errorDiagnosticsEnabled": true,
"inletUrl": "https://dcs-int.adobedc.net/collection/ab65636c31778fb0455c439ffb48a5433a34d443f4c83c4b5beda9c5688797c5"
},
"transformations": [
{
"name": "Mapping",
"params": {
"mappingVersion": 0,
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366"
}
}
],
"runs": "/runs?property=flowId==e1514b79-f031-43b4-aab5-381a42f86ad4",
"providerRefId": "c9809ab5-71e0-4c7f-887b-61c95e4e20b5",
"lastOperation": {
"started": 0,
"updated": 0,
"operation": "enable"
}
}
]
}
Annexe
La section suivante fournit des informations sur les étapes que vous pouvez suivre pour surveiller, mettre à jour et supprimer votre flux de données.
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 obtenir des exemples d’API complets, consultez le guide sur la surveillance des flux de données sources à l’aide de l’API.
Mettre à jour votre flux de données
Mettez à jour les détails de votre flux de données, tels que son nom et sa description, ainsi que son planning d’exécution et les jeux de mappages associés en envoyant une requête de PATCH au point d’entrée /flows
de Flow Service’API , tout en fournissant l’identifiant de votre flux de données. Lors de l’exécution d’une requête de PATCH, vous devez fournir le etag
unique de votre flux de données dans l’en-tête If-Match
. Pour obtenir des exemples d’API complets, consultez le guide sur la mise à jour des flux de données sources à l’aide de l’API
Mettre à jour votre compte
Mettez à jour le nom, la description et les informations d’identification de votre compte source en adressant une requête de PATCH à l’API Flow Service et en fournissant votre identifiant de connexion de base comme paramètre de requête. Lors de l’exécution d’une requête de PATCH, vous devez indiquer le etag
unique de votre compte source dans l’en-tête If-Match
. Pour obtenir des exemples d’API complets, consultez le guide sur la mise à jour de votre compte source à l’aide de l’API.
Supprimer le flux de données
Supprimez votre flux de données en adressant une requête de DELETE à l’API Flow Service et en fournissant l’identifiant du flux de données à supprimer dans le cadre du paramètre de requête. Pour obtenir des exemples d’API complets, consultez le guide sur la suppression de vos flux de données à l’aide de l’API.
Supprimer votre compte
Supprimez votre compte en adressant une requête de DELETE à l’API Flow Service et en fournissant l’identifiant de connexion de base du compte que vous souhaitez supprimer. Pour obtenir des exemples d’API complets, consultez le guide sur la suppression de votre compte source à l’aide de l’API.