Créer une connexion source et un flux de données pour SugarCRM Accounts & Contacts à 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 SugarCRM Accounts & Contacts et d’un flux de données pour importer les données de comptes et de contacts SugarCRM dans Adobe Experience Platform à l’aide de l’Flow Service API.
Prise en main
Ce guide nécessite une compréhension professionnelle des composants suivants d’Experience Platform :
- Sources : Experience Platform permet d’ingérer des données provenant de diverses sources tout en vous offrant la possibilité de structurer, d’étiqueter et d’améliorer les données entrantes à l’aide des services de Platform.
- Sandbox : Experience Platform fournit des sandbox virtuels qui divisent une instance de plateforme unique en environnements virtuels distincts pour favoriser le développement et l’évolution d’applications d’expérience digitale.
Les sections suivantes contiennent des informations supplémentaires que vous devez connaître pour réussir à vous connecter à SugarCRM à l’aide de l’API Flow Service.
Collecter les informations d’identification requises
Pour connecter SugarCRM Accounts & Contacts à Platform, vous devez fournir des valeurs pour les propriétés de connexion suivantes :
hostdeveloper.salesfusion.comusernameabc.def@example.com@sugarmarketdemo000.compassword123456789Connecter SugarCRM Accounts & Contacts à Platform à l’aide de l’API Flow Service
Vous trouverez ci-dessous la procédure à suivre pour authentifier la source de SugarCRM, créer une connexion source et créer un flux de données pour que les données de vos comptes et contacts soient Experience Platform.
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 point d’entrée /connections et indiquez vos informations d’authentification SugarCRM Accounts & Contacts dans le corps de la requête.
Format d’API
POST /connections
Requête
La requête suivante permet de créer une connexion de base pour SugarCRM Accounts & Contacts :
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": "SugarCRM Accounts & Contacts base connection",
"description": "Create a live inbound connection to your SugarCRM Accounts & Contacts instance, to ingest both historic and scheduled data into Experience Platform",
"connectionSpec": {
"id": "59a4b493-a615-40f9-bd38-f823d0909a2b",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Refresh Code",
"params": {
"host": "developer.salesfusion.com",
"username": "{SUGARCRM_DEVELOPER_ACCOUNT_USERNAME}",
"password": "{SUGARCRM_DEVELOPER_ACCOUNT_PASSWORD}"
}
}
}'
namedescriptionconnectionSpec.idauth.specNameauth.params.hostauth.params.usernameauth.params.passwordRé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": "f5421911-6f6c-41c7-aafa-5d9d2ce51535",
"etag": "\"4d08164f-0000-0200-0000-6368b7bf0000\""
}
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 de GET.
Utilisez les appels suivants pour trouver le chemin d’accès au fichier que vous souhaitez importer dans 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=restrest.{OBJECT}json.fileType=jsonjson est le seul type de fichier pris en charge.{PREVIEW}{SOURCE_PARAMS}Définit les paramètres du fichier source que vous souhaitez importer dans Platform. Pour récupérer le type de format accepté pour {SOURCE_PARAMS}, vous devez coder l’intégralité de la chaîne en base64.
SugarCRM Accounts & Contacts prend en charge plusieurs API. Selon le type d’objet que vous utilisez, transmettez l’un des éléments suivants :
accounts: sociétés avec lesquelles votre organisation entretient une relation.contacts: personnes individuelles avec lesquelles votre organisation a une relation établie.
Le SugarCRM Accounts & Contacts prend en charge plusieurs API. Selon le type d’objet que vous utilisez, la requête à envoyer se présente comme suit :
Requête
Pour l’API SugarCRM Accounts, la valeur de {SOURCE_PARAMS} est transmise comme {"object_type":"accounts"}. Lorsqu’il est codé en base64, il équivaut à eyJvYmplY3RfdHlwZSI6ImFjY291bnRzIn0= comme illustré ci-dessous.
| code language-shell |
|---|
|
Pour SugarCRM’API Contacts, la valeur de {SOURCE_PARAMS} est transmise sous la forme {"object_type":"contacts"}. Lorsqu’il est codé en base64, il équivaut à eyJvYmplY3RfdHlwZSI6ImNvbnRhY3RzIn0= comme illustré ci-dessous.
| code language-shell |
|---|
|
Réponse
De même, en fonction du type d’objet que vous utilisez pour la réponse reçue, procédez comme suit :
Une réponse réussie renvoie une structure comme ci-dessous.
| code language-json |
|---|
|
Une réponse réussie renvoie une structure comme ci-dessous.
| code language-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 SugarCRM Accounts & Contacts :
Selon le type d’objet que vous utilisez, sélectionnez dans les onglets ci-dessous :
Pour l’API SugarCRM Accounts, la valeur de la propriété object_type doit être accounts.
| code language-shell |
|---|
|
Pour SugarCRM API Contacts, la valeur de la propriété object_type doit être contacts.
| code language-shell |
|---|
|
namedescriptionbaseConnectionIdconnectionSpec.iddata.formatjson est le seul à être pris en charge.object_typeSugarCRM Accounts & Contacts prend en charge plusieurs API. Selon le type d’objet que vous utilisez, transmettez l’un des éléments suivants :
accounts: sociétés avec lesquelles votre organisation entretient une relation.contacts: personnes individuelles avec lesquelles votre organisation a une relation établie.
pathobject_type.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": "8f1fc72a-f562-4a1d-8597-85b5ca1b1cd3",
"etag": "\"ed05f1e1-0000-0200-0000-6368b8710000\""
}
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 SugarCRM Accounts & Contacts :
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": "SugarCRM Target Connection Generic Rest",
"description": "SugarCRM Target Connection Generic Rest",
"connectionSpec": {
"id": "63d2b27b-69a5-45c9-a7fe-78148a25de3c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/b156e6f818f923e048199173c45e55e20fd2487f5eb03d22",
"version": "1.22"
}
},
"params": {
"dataSetId": "6365389d1d37d01c077a81da"
}
}'
namedescriptionconnectionSpec.id6b137bf6-d2a0-48c8-914b-d50f4942eb85.data.formatparams.dataSetIdRéponse
Une réponse réussie renvoie l’identifiant unique de la nouvelle connexion cible (id). Cet identifiant est requis aux étapes suivantes.
{
"id": "6b137bf6-d2a0-48c8-914b-d50f4942eb85",
"etag": "\"8405a268-0000-0200-0000-6368b8c30000\""
}
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/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 '{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/b156e6f818f923e048199173c45e55e20fd2487f5eb03d22",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "results.account",
"destination": "_extconndev.account"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.account_id",
"destination": "_extconndev.account_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.acount_name",
"destination": "_extconndev.account_name"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.account_score",
"destination": "_extconndev.account_score"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.billing_city",
"destination": "_extconndev.billing_city"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.contacts",
"destination": "_extconndev.contacts"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.created_by",
"destination": "_extconndev.created_by"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.created_by_id",
"destination": "_extconndev.created_by_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.created_date",
"destination": "_extconndev.created_date"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.custom_score_field",
"destination": "_extconndev.custom_score_field"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.key_account",
"destination": "_extconndev.key_account"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.owner",
"destination": "_extconndev.owner"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.owner_id",
"destination": "_extconndev.owner_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.phone",
"destination": "_extconndev.phone_no"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.updated_by",
"destination": "_extconndev.updated_by"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.updated_by_id",
"destination": "_extconndev.updated_by_id"
},
{
"sourceType": "ATTRIBUTE",
"source": "results.updated_date",
"destination": "_extconndev.updated_date"
}
]
}'
outputSchema.schemaRef.idmappings.sourceTypemappings.sourcemappings.destinationRé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": "059c69f7207b4d7e9b48c47e2fd966a6",
"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 SugarCRM Accounts & Contacts 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 la fréquence sur l’une des valeurs hour ou day. La valeur de l’intervalle désigne la période entre deux ingestions consécutives. La valeur de l’intervalle doit être définie sur 1 ou 24 selon scheduleParams.frequency sélection de hour ou day.
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": "SugarCRM Connector Description Flow Generic Rest",
"description": "SugarCRM Connector Description Flow Generic Rest",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"8f1fc72a-f562-4a1d-8597-85b5ca1b1cd3"
],
"targetConnectionIds": [
"6b137bf6-d2a0-48c8-914b-d50f4942eb85"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "059c69f7207b4d7e9b48c47e2fd966a6",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "hour",
"interval": 1
}
}'
namedescriptionflowSpec.id6499120c-0b15-42dc-936e-847ea3c24d72.flowSpec.version1.0.sourceConnectionIdstargetConnectionIdstransformationstransformations.nametransformations.params.mappingIdtransformations.params.mappingVersion0.scheduleParams.startTimescheduleParams.frequencyhour ou day.scheduleParams.interval1 ou 24 selon scheduleParams.frequency sélection de hour ou day.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": "fcd16140-81b4-422a-8f9a-eaa92796c4f4",
"etag": "\"9200a171-0000-0200-0000-6368c1da0000\""
}
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.