Ce didacticiel décrit les étapes à suivre pour récupérer les données d'une application de paiement tierce et les intégrer à la plate-forme par le biais des connecteurs source et de l'API Flow Service.
Ce didacticiel vous oblige à avoir accès à une demande de paiement via une connexion valide, ainsi qu'à des informations sur le fichier que vous souhaitez importer dans la plate-forme (y compris le chemin et la structure du fichier). Si vous ne disposez pas de ces informations, consultez le didacticiel sur l'exploration d'une application de paiement à l'aide de l'API Flow Service avant de tenter ce tutoriel.
Ce didacticiel nécessite également une bonne compréhension des composants suivants de Adobe Experience Platform :
{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).Les sections suivantes fournissent des informations supplémentaires dont vous aurez besoin pour vous connecter à une application de paiement à l'aide de l'API Flow Service.
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 API, consultez la section sur la lecture d’exemples d’appels API dans le guide de dépannage d’Experience Platform.
Pour lancer des appels aux API Platform, vous devez d’abord suivre le tutoriel sur l’authentification. Le tutoriel sur l’authentification indique les valeurs de chacun des en-têtes requis dans tous les appels API Experience Platform, comme illustré ci-dessous :
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}
Toutes les ressources en Experience Platform, y compris celles appartenant à Flow Service, sont isolées dans des sandbox virtuels spécifiques. Toutes les requêtes envoyées aux API Platform nécessitent un en-tête spécifiant le nom de l’environnement de test dans lequel l’opération sera effectuée :
x-sandbox-name: {SANDBOX_NAME}
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
Vous pouvez créer une connexion source en adressant une requête de 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 de format de données.
Utilisez les valeurs d’énumération suivantes pour les connecteurs basés sur des fichiers :
Sur le format des données saisies | Valeur maximale |
---|---|
Délimité | delimited |
JSON | json |
Parquet | parquet |
Pour tous les connecteurs basés sur une table, définissez la valeur sur 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "PayPal source connection",
"connectionId": "24151d58-ffa7-4960-951d-58ffa7396097",
"description": "PayPal source connection",
"data": {
"format": "tabular",
}
},
"params": {
"path": "PayPal.Catalog_Products"
},
"connectionSpec": {
"id": "221c7626-58f6-4eec-8ee2-042b0226f03b",
"version": "1.0"
}
}'
Propriété | Description |
---|---|
connectionId |
ID de connexion unique de l’application de paiement tierce à laquelle vous accédez. |
params.path |
Chemin d’accès du fichier source. |
connectionSpec.id |
ID de spécification de connexion de votre application de paiement. |
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 à une cible.
{
"id": "2c48a152-3d49-43cb-88a1-523d49e3cbcb",
"etag": "\"8000c843-0000-0200-0000-5e8917ea0000\""
}
Pour que les données source soient utilisées dans Platform, un schéma de cible doit être créé pour structurer les données source en fonction de vos besoins. Le schéma de cible est ensuite utilisé pour créer un jeu de données de plateforme dans lequel les données source sont contenues. Ce schéma XDM de cible étend également la classe XDM Individual Profile.
Un schéma XDM de cible peut être créé en exécutant une requête de POST à l'API de registre de Schéma.
Format d’API
POST /tenant/schemas
Requête
L'exemple de demande suivant crée un schéma XDM qui étend la classe XDM Individual Profile.
curl -X POST \
'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
-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 '{
"type": "object",
"title": "PayPal target XDM schema",
"description": "PayPal target XDM schema",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
}
],
"meta:containerId": "tenant",
"meta:resourceType": "schemas",
"meta:xdmType": "object",
"meta:class": "https://ns.adobe.com/xdm/context/profile"
}'
Réponse
Une réponse réussie renvoie les détails du schéma nouvellement créé, y compris son identifiant unique ($id
). Cet identifiant est requis dans les étapes suivantes pour créer un jeu de données de cible, un mappage et un flux de données.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/14d89c5bb88e2ff488f23db896be469e7e30bb166bda8722",
"meta:altId": "_{TENANT_ID}.schemas.14d89c5bb88e2ff488f23db896be469e7e30bb166bda8722",
"meta:resourceType": "schemas",
"version": "1.0",
"title": "PayPal target XDM schema",
"type": "object",
"description": "PayPal target XDM",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
"type": "object",
"meta:xdmType": "object"
}
],
"refs": [
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details",
"https://ns.adobe.com/xdm/context/profile"
],
"imsOrg": "{IMS_ORG}",
"meta:extensible": false,
"meta:abstract": false,
"meta:extends": [
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1586042956286,
"repo:lastModifiedDate": 1586042956286,
"xdm:createdClientId": "{CREATED_CLIENT_ID}",
"xdm:lastModifiedClientId": "{LAST_MODIFIED_CLIENT_ID}",
"xdm:createdUserId": "{CREATED_USER_ID}",
"xdm:lastModifiedUserId": "{LAST_MODIFIED_USER_ID}",
"eTag": "952e8912724d7f43cbc1471e3987bc5b6899519c186126b7c50619f2dddf8650"
},
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:containerId": "tenant",
"meta:tenantNamespace": "_{TENANT_ID}"
}
Un jeu de données de cible peut être créé en exécutant une requête de POST à l'API du service de catalogue, en fournissant l'identifiant du schéma de cible dans la charge utile.
Format d’API
POST /dataSets
Requête
curl -X POST \
'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
-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": "PayPal target dataset",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/14d89c5bb88e2ff488f23db896be469e7e30bb166bda8722",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
}
}'
Propriété | Description |
---|---|
schemaRef.id |
$id du schéma XDM de cible. |
Réponse
Une réponse réussie renvoie un tableau contenant l’ID du jeu de données nouvellement créé au format "@/datasets/{DATASET_ID}"
. L’identifiant du jeu de données est une chaîne en lecture seule générée par le système et utilisée pour référencer le jeu de données dans les appels API. Stockez l’ID du jeu de données de cible tel qu’il est requis dans les étapes suivantes pour créer une connexion à une cible et un flux de données.
[
"@/dataSets/5e8918669cbbee18ad9771f3"
]
Une connexion de cible représente la connexion à la destination où se trouvent les données saisies. Pour créer une connexion de cible, vous devez fournir l’identifiant de spécification de connexion fixe associé au lac Data. Cet identifiant de spécification de connexion est : c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Vous disposez désormais des identifiants uniques d’un schéma de cible d’un jeu de données de cible et de l’ID de spécification de connexion au lac de données. L'API Flow Service vous permet de créer une connexion de 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
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Target Connection for payments",
"description": "Target Connection for payments",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/14d89c5bb88e2ff488f23db896be469e7e30bb166bda8722",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "5e8918669cbbee18ad9771f3"
},
"connectionSpec": {
"id": "221c7626-58f6-4eec-8ee2-042b0226f03b",
"version": "1.0"
}
}'
Propriété | Description |
---|---|
data.schema.id |
$id du schéma XDM de cible. |
params.dataSetId |
ID du jeu de données de cible. |
connectionSpec.id |
ID de spécification de connexion utilisé pour la connexion au lac Data. Cet ID est : c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
Réponse
Une réponse réussie renvoie l'identifiant unique de la nouvelle connexion à la cible (id
). Cette valeur est requise à une étape ultérieure pour créer un flux de données.
{
"id": "c8e12917-ac33-44d7-a129-17ac3364d7b7",
"etag": "\"0f015874-0000-0200-0000-5e8918e60000\""
}
Pour que les données source soient assimilées à un jeu de données de cible, elles doivent d’abord être mises en correspondance avec le schéma de cible auquel adhère le jeu de données de cible. Pour ce faire, il effectue une requête de POST à l'API du service de conversion avec des mappages de données définis dans la charge utile de la demande.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/14d89c5bb88e2ff488f23db896be469e7e30bb166bda8722",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Product_Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "product.name",
"sourceAttribute": "Product_Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "product.description",
"sourceAttribute": "Description",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "product.type",
"sourceAttribute": "Type",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
Propriété | Description |
---|---|
xdmSchema |
$id du schéma XDM de cible. |
Réponse
Une réponse réussie renvoie les détails du nouveau mappage, y compris son identifiant unique (id
). Cet identifiant est nécessaire à une étape ultérieure pour créer un flux de données.
{
"id": "b54a8dc38e8d4e31a2dc096e413ae8e5",
"version": 0,
"createdDate": 1586043319604,
"modifiedDate": 1586043319604,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Un flux de données est chargé de collecter les données provenant de sources et de les intégrer à la plate-forme. Pour créer un flux de données, vous devez d'abord obtenir les spécifications du flux de données en exécutant une demande de GET à l'API Flow Service. Les spécifications de flux de données sont responsables de la collecte de données à partir d'une base de données externe ou d'un système NoSQL.
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Réponse
Une réponse réussie renvoie les détails de la spécification de flux de données responsable de l'introduction des données de votre source dans la plate-forme. La réponse comprend la spécification de flux unique id
requise pour créer un nouveau flux de données.
{
"items": [
{
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"name": "CRMToAEP",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"sourceConnectionSpecIds": [
"3416976c-a9ca-4bba-901a-1f08f66978ff",
"38ad80fe-8b06-4938-94f4-d4ee80266b07",
"d771e9c1-4f26-40dc-8617-ce58c4b53702",
"3c9b37f8-13a6-43d8-bad3-b863b941fedd",
"cc6a4487-9e91-433e-a3a3-9cf6626c1806",
"3000eb99-cd47-43f3-827c-43caf170f015",
"26d738e0-8963-47ea-aadf-c60de735468a",
"74a1c565-4e59-48d7-9d67-7c03b8a13137",
"cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"4f63aa36-bd48-4e33-bb83-49fbcd11c708",
"cb66ab34-8619-49cb-96d1-39b37ede86ea",
"eb13cb25-47ab-407f-ba89-c0125281c563",
"1f372ff9-38a4-4492-96f5-b9a4e4bd00ec",
"37b6bf40-d318-4655-90be-5cd6f65d334b",
"a49bcc7d-8038-43af-b1e4-5a7a089a7d79",
"221c7626-58f6-4eec-8ee2-042b0226f03b",
"a8b6a1a4-5735-42b4-952c-85dce0ac38b5",
"6a8d82bc-1caf-45d1-908d-cadabc9d63a6",
"aac9bbd4-6c01-46ce-b47e-51c6f0f6db3f",
"8e6b41a8-d998-4545-ad7d-c6a9fff406c3",
"ecde33f2-c56f-46cc-bdea-ad151c16cd69",
"102706fb-a5cd-42ee-afe0-bc42f017ff43",
"09182899-b429-40c9-a15a-bf3ddbc8ced7",
"0479cc14-7651-4354-b233-7480606c2ac3",
"d6b52d86-f0f8-475f-89d4-ce54c8527328",
"a8f4d393-1a6b-43f3-931f-91a16ed857f4",
"1fe283f6-9bec-11ea-bb37-0242ac130002"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"optionSpec": {
"name": "OptionSpec",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"errorDiagnosticsEnabled": {
"title": "Error diagnostics.",
"description": "Flag to enable detailed and sample error diagnostics summary.",
"type": "boolean",
"default": false
},
"partialIngestionPercent": {
"title": "Partial ingestion threshold.",
"description": "Percentage which defines the threshold of errors allowed before the run is marked as failed.",
"type": "number",
"exclusiveMinimum": 0
}
}
}
},
"transformationSpecs": [
{
"name": "Copy",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"deltaColumn": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"dateFormat": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"required": [
"name"
]
}
},
"required": [
"deltaColumn"
]
}
},
{
"name": "Mapping",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for different mapping from source to target",
"properties": {
"mappingId": {
"type": "string"
},
"mappingVersion": {
"type": "string"
}
}
}
}
],
"scheduleSpec": {
"name": "PeriodicSchedule",
"type": "Periodic",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"startTime": {
"description": "epoch time",
"type": "integer"
},
"frequency": {
"type": "string",
"enum": [
"once",
"minute",
"hour",
"day",
"week"
]
},
"interval": {
"type": "integer"
},
"backfill": {
"type": "boolean",
"default": true
}
},
"required": [
"startTime",
"frequency"
],
"if": {
"properties": {
"frequency": {
"const": "once"
}
}
},
"then": {
"allOf": [
{
"not": {
"required": [
"interval"
]
}
},
{
"not": {
"required": [
"backfill"
]
}
}
]
},
"else": {
"required": [
"interval"
],
"if": {
"properties": {
"frequency": {
"const": "minute"
}
}
},
"then": {
"properties": {
"interval": {
"minimum": 15
}
}
},
"else": {
"properties": {
"interval": {
"minimum": 1
}
}
}
}
}
},
"attributes": {
"notification": {
"category": "sources",
"flowRun": {
"enabled": true
}
}
},
"permissionsInfo": {
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
],
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
]
}
}
]
}
La dernière étape de la collecte des données consiste à créer un flux de données. A ce stade, les valeurs requises suivantes doivent être préparées :
Un flux de données est responsable de la planification et de la collecte des données d’une source. Vous pouvez créer un flux de données en exécutant une requête de POST tout en fournissant les valeurs mentionnées précédemment dans la charge utile.
Pour planifier une assimilation, vous devez d'abord définir la valeur du temps de début en secondes. Ensuite, vous devez définir la valeur de fréquence sur l’une des cinq options suivantes : once
, minute
, hour
, day
ou week
. La valeur d'intervalle désigne la période entre deux ingérations consécutives et la création d'une assimilation ponctuelle ne nécessite pas la 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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Dataflow between payments Platform",
"description": "Inbound data to Platform",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"2c48a152-3d49-43cb-88a1-523d49e3cbcb"
],
"targetConnectionIds": [
"c8e12917-ac33-44d7-a129-17ac3364d7b7"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "updatedAt",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "b54a8dc38e8d4e31a2dc096e413ae8e5",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1567411548",
"frequency": "minute",
"interval":"30"
}
}'
Propriété | Description |
---|---|
flowSpec.id |
ID de la spécification de flux récupéré à l’étape précédente. |
sourceConnectionIds |
L'identifiant de connexion source a été récupéré lors d'une étape précédente. |
targetConnectionIds |
L'ID de connexion de cible a été récupéré lors d'une étape précédente. |
transformations.params.mappingId |
ID de mappage récupéré lors d’une étape précédente. |
transformations.params.deltaColum |
Colonne désignée utilisée pour différencier les données nouvelles et existantes. Les données incrémentielles seront ingérées en fonction de l’horodatage de la colonne sélectionnée. Le format de date pris en charge pour deltaColumn est yyyy-MM-dd HH:mm:ss . |
transformations.params.mappingId |
ID de mappage associé à votre base de données. |
scheduleParams.startTime |
Heure de début du flux de données dans l’époque. |
scheduleParams.frequency |
Fréquence à laquelle le flux de données va collecter les données. Les valeurs acceptables sont les suivantes : 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 entier non nul. L'intervalle n'est pas requis lorsque la fréquence est définie sur once et doit être supérieur ou égal à 15 pour les autres valeurs de fréquence. |
Réponse
Une réponse réussie renvoie l'ID id
du flux de données nouvellement créé.
{
"id": "e0bd8463-0913-4ca1-bd84-6309134ca1f6",
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
Une fois votre flux de données créé, vous pouvez surveiller les données qui y sont ingérées afin d’afficher des informations sur les exécutions de flux, l’état d’achèvement et les erreurs. Pour plus d'informations sur la façon de surveiller les flux de données, consultez le didacticiel sur la surveillance des flux de données dans l'API .
En suivant ce didacticiel, vous avez créé un connecteur source pour collecter les données d'une application de paiement sur une base planifiée. Les données entrantes peuvent désormais être utilisées par les services Plateforme en aval tels que Real-time Customer Profile et Data Science Workspace. Pour plus d’informations, voir les documents suivants :