Créez un YOURSOURCE connexion à l’aide de la fonction Flow Service API
Lorsque 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. Ignorez 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 multiples langues prises en charge. Nous ajouterons des balises à votre documentation après l’avoir envoyée.
Vue d’ensemble
Fournissez un bref aperçu de votre entreprise, y compris la valeur qu’elle fournit aux clients. Insérez un lien vers la page d’accueil de la documentation du produit pour en savoir plus.
Conditions préalables
Ajoutez dans cette section des informations sur tout ce dont les clients doivent tenir compte avant de commencer à configurer la source dans l’interface utilisateur de Adobe Experience Platform. Il peut s’agir :
- à ajouter à une liste autorisée
- conditions requises pour le hachage des emails
- toute spécification de compte de votre côté ;
- Comment obtenir une clé API pour se connecter à votre plateforme
Collecter les informations d’identification requises
Pour vous connecter YOURSOURCE pour Experience Platform, vous devez fournir des valeurs pour les propriétés de connexion suivantes :
Pour plus d’informations sur ces informations d’identification, voir YOURSOURCE documentation d’authentification. Veuillez ajouter un lien vers la documentation d’authentification de votre plateforme ici.
Connexion YOURSOURCE vers Platform à l’aide de la méthode Flow Service API
Le tutoriel suivant décrit les étapes à suivre pour créer un YOURSOURCE connexion source et créer un flux de données à importer YOURSOURCE données vers Platform à l’aide de la fonction Flow Service API.
Créer une connexion de base base-connection
Une connexion de base conserve les informations échangées entre votre source et Platform, y compris les informations d’authentification de votre source, l’état actuel de la connexion et votre identifiant de connexion de base unique. L’identifiant de connexion de base vous permet d’explorer et de parcourir des fichiers à partir de votre source et d’identifier les éléments spécifiques que vous souhaitez ingérer, y compris des informations concernant leurs types et formats de données.
Pour créer un identifiant de connexion de base, envoyez une requête de POST au /connections
point de terminaison lors de la fourniture de YOURSOURCE informations d’identification d’authentification dans le corps de la requête.
Format d’API
POST /connections
Requête
La requête suivante crée une connexion de base pour YOURSOURCE:
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-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": "{YOURSOURCE} base connection",
"description": "{YOURSOURCE} base connection to authenticate to Platform",
"connectionSpec": {
"id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
"version": "1.0"
},
"auth": {
"specName": "OAuth generic-rest-connector",
"params": {
"accessToken": "{ACCESS_TOKEN}",
"refreshToken": "{REFRESH_TOKEN}",
"expirationDate": "{EXPIRATION_DATE}"
}
}
}'
name
description
connectionSpec.id
auth.specName
auth.params.
Réponse
Une réponse réussie renvoie la nouvelle connexion de base, y compris son identifiant de connexion unique (id
). Cet identifiant est nécessaire pour explorer la structure de fichiers et le contenu de votre source à l’étape suivante.
{
"id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}
Explorer votre source explore
À l’aide de l’identifiant de connexion de base généré à l’étape précédente, vous pouvez explorer les fichiers et répertoires en exécutant des requêtes GET.
Utilisez les appels suivants pour trouver le chemin d’accès au fichier que vous souhaitez importer Platform:
Format d’API
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Lors de l’exécution de requêtes GET pour explorer la structure et le contenu des fichiers de votre source, vous devez inclure les paramètres de requête répertoriés dans le tableau ci-dessous :
{BASE_CONNECTION_ID}
objectType=rest
rest
.{OBJECT}
fileType=json
json
est le seul type de fichier pris en charge.{PREVIEW}
{SOURCE_PARAMS}
{SOURCE_PARAMS}
, vous devez coder l’intégralité de la chaîne list_id
en base64. Dans l’exemple ci-dessous, "list_id": "10c097ca71"
encodé en base64 équivaut à eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=
.Requête
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/70383d02-2777-4be7-a309-9dd6eea1b46d/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=' \
-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 la structure du fichier interrogé.
{
"data": [
{
"members": [
{
"id": "cff65fb4c5f5828666ad846443720efd",
"email_address": "roykent@gmail.com",
"unique_email_id": "72c758cbf1",
"full_name": "Roy Kent",
"web_id": 547094062,
"email_type": "html",
"status": "subscribed",
"merge_fields": {
"FNAME": "Roy",
"LNAME": "Kent",
"ADDRESS": {
"addr1": "",
"addr2": "",
"city": "Richmond",
"state": "Virginia",
"zip": "",
"country": "US"
},
"PHONE": "",
"BIRTHDAY": ""
},
"stats": {
"avg_open_rate": 0,
"avg_click_rate": 0
},
"ip_signup": "",
"timestamp_signup": "",
"ip_opt": "103.43.112.97",
"timestamp_opt": "2021-06-01T15:31:36+00:00",
"member_rating": 2,
"last_changed": "2021-06-01T15:31:36+00:00",
"language": "",
"vip": false,
"email_client": "",
"location": {
"latitude": 0,
"longitude": 0,
"gmtoff": 0,
"dstoff": 0,
"country_code": "",
"timezone": ""
},
"source": "Admin Add",
"tags_count": 0,
"tags": [
],
"list_id": "10c097ca71"
}
],
"list_id": "10c097ca71",
"total_items": 2,
"_links": [
{
"rel": "self",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
},
{
"rel": "parent",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
},
{
"rel": "create",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "POST",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/POST.json"
}
]
}
]
}
Créer une connexion source source-connection
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.
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": "{YOURSOURCE} Source Connection",
"description": "{YOURSOURCE} Source Connection",
"baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"connectionSpec": {
"id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"server": "us6",
"listId": "10c097ca71"
}
}'
name
description
baseConnectionId
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 vers laquelle les données ingérées doivent être stockées. Pour créer une connexion cible, vous devez fournir l’identifiant de spécification de connexion fixe qui correspond au Data Lake. Cet identifiant est c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Vous disposez à présent des identifiants uniques d’un schéma et d’un jeu de données cibles et de l’identifiant de spécification de connexion au Data Lake. À 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": "{YOURSOURCE} Target Connection",
"description": "{YOURSOURCE} Target Connection",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"dataSetId": "5ef4551c52e054191a61a99f"
}
}'
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 vous suffit d’adresser une requête de POST à Data Prep API avec des mappages de données définis dans le payload de la requête.
Format d’API
POST /conversion/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/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "FirstName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "LastName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"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 obtenir 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.
Pour planifier une ingestion, vous devez d’abord définir la valeur de l’heure de début en temps Unix en secondes. Vous devez ensuite définir la valeur de fréquence sur l’une des cinq options suivantes : once
, minute
, hour
, day
ou week
. La valeur interval désigne toutefois la période entre deux ingestion consécutives, la création d’une ingestion unique ne nécessite pas de définition d’un intervalle. Pour toutes les autres fréquences, la valeur de l’intervalle doit être égale ou supérieure à 15
.
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": "{YOURSOURCE} dataflow",
"description": "{YOURSOURCE} dataflow",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "minute",
"interval": 15
}
}'
name
description
flowSpec.id
6499120c-0b15-42dc-936e-847ea3c24d72
.flowSpec.version
1.0
.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
.scheduleParams.startTime
scheduleParams.frequency
once
, minute
, hour
, day
ou week
.scheduleParams.interval
once
et doit être supérieur ou égal à 15
pour d’autres valeurs de fréquence.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\""
}
Annexe
La section suivante fournit des informations sur les étapes de surveillance, de mise à jour et de suppression de 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 consulter des exemples complets d’API, reportez-vous au guide sur surveillance de vos 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 PATCH à la variable /flows
point d’entrée 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 l’unique de votre flux de données etag
dans le If-Match
en-tête . Pour consulter des exemples complets d’API, reportez-vous au guide sur mise à jour des flux de données de 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 au Flow Service API tout en fournissant votre identifiant de connexion de base en tant que paramètre de requête. Lors de l’exécution d’une requête de PATCH, vous devez fournir l’unique de votre compte source etag
dans le If-Match
en-tête . Pour consulter des exemples complets d’API, reportez-vous au guide sur 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 à la fonction Flow Service API tout en fournissant l’identifiant du flux de données que vous souhaitez supprimer dans le cadre du paramètre de requête . Pour consulter des exemples complets d’API, reportez-vous au guide sur suppression de vos flux de données à l’aide de l’API.
Suppression de votre compte
Supprimez votre compte en adressant une requête de DELETE à la fonction Flow Service API tout en fournissant l’identifiant de connexion de base du compte que vous souhaitez supprimer. Pour consulter des exemples complets d’API, reportez-vous au guide sur suppression de votre compte source à l’aide de l’API.