Crear una conexión de origen y un flujo de datos para SugarCRM Accounts & Contacts mediante la API de Flow Service
El siguiente tutorial lo acompañará durante los pasos para crear una conexión de origen de SugarCRM Accounts & Contacts y un flujo de datos para llevar los datos de cuentas y contactos de SugarCRM a Adobe Experience Platform mediante la Flow Service API.
Introducción
Esta guía requiere una comprensión práctica de los siguientes componentes de Experience Platform:
- Fuentes: El Experience Platform permite la ingesta de datos de varias fuentes, al tiempo que le ofrece la capacidad de estructurar, etiquetar y mejorar los datos entrantes mediante los servicios de Platform.
- Zonas protegidas: El Experience Platform proporciona zonas protegidas virtuales que dividen una sola instancia de Platform en entornos virtuales independientes para ayudar a desarrollar y evolucionar aplicaciones de experiencia digital.
Las secciones siguientes proporcionan información adicional que necesitará conocer para conectarse correctamente a SugarCRM mediante la API Flow Service.
Recopilar credenciales necesarias
Para conectar SugarCRM Accounts & Contacts a Platform, debe proporcionar valores para las siguientes propiedades de conexión:
hostdeveloper.salesfusion.comusernameabc.def@example.com@sugarmarketdemo000.compassword123456789Conectar SugarCRM Accounts & Contacts a la plataforma mediante la API Flow Service
A continuación se describen los pasos que debe seguir para autenticar el origen de SugarCRM, crear una conexión de origen y crear un flujo de datos para llevar los datos de cuentas y contactos al Experience Platform.
Crear una conexión base base-connection
Una conexión base retiene información entre el origen y Platform, incluidas las credenciales de autenticación del origen, el estado actual de la conexión y el ID único de conexión base. El ID de conexión base le permite explorar y navegar por archivos desde el origen e identificar los elementos específicos que desea introducir, incluida la información sobre sus tipos de datos y formatos.
Para crear un identificador de conexión base, realice una solicitud de POST al extremo /connections y proporcione sus credenciales de autenticación SugarCRM Accounts & Contacts como parte del cuerpo de la solicitud.
Formato de API
POST /connections
Solicitud
La siguiente solicitud crea una conexión base para 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.passwordRespuesta
Una respuesta correcta devuelve la conexión base recién creada, incluido su identificador de conexión único (id). Este ID es necesario para explorar la estructura de archivos y el contenido de origen en el siguiente paso.
{
"id": "f5421911-6f6c-41c7-aafa-5d9d2ce51535",
"etag": "\"4d08164f-0000-0200-0000-6368b7bf0000\""
}
Explorar su origen explore
Con el ID de conexión base que generó en el paso anterior, puede explorar archivos y directorios realizando solicitudes de GET.
Utilice las siguientes llamadas para encontrar la ruta del archivo que desea introducir en Platform:
Formato de API
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Al realizar solicitudes para explorar la estructura de archivos y el contenido de origen, debe incluir los parámetros de GET que se enumeran en la tabla siguiente:
{BASE_CONNECTION_ID}objectType=restrest.{OBJECT}json.fileType=jsonjson es el único tipo de archivo compatible.{PREVIEW}{SOURCE_PARAMS}Define parámetros para el archivo de origen que desea llevar a Platform. Para recuperar el tipo de formato aceptado para {SOURCE_PARAMS}, debe codificar toda la cadena en base64.
SugarCRM Accounts & Contacts admite varias API. Según el tipo de objeto que esté aprovechando, pase uno de los siguientes:
accounts: Compañías con las que su organización tiene una relación.contacts: Personas individuales con las que su organización tiene una relación establecida.
SugarCRM Accounts & Contacts admite varias API. Según el tipo de objeto que utilice, la solicitud que se va a enviar es la siguiente:
Solicitud
Para la API de cuentas SugarCRM, el valor de {SOURCE_PARAMS} se pasa como {"object_type":"accounts"}. Cuando se codifica en base64, equivale a eyJvYmplY3RfdHlwZSI6ImFjY291bnRzIn0=, como se muestra a continuación.
| code language-shell |
|---|
|
Para la API de contactos de SugarCRM, el valor de {SOURCE_PARAMS} se pasa como {"object_type":"contacts"}. Cuando se codifica en base64, equivale a eyJvYmplY3RfdHlwZSI6ImNvbnRhY3RzIn0=, como se muestra a continuación.
| code language-shell |
|---|
|
Respuesta
Del mismo modo, según el tipo de objeto que aproveche, la respuesta recibida es la siguiente:
Una respuesta correcta devuelve una estructura como se muestra a continuación.
| code language-json |
|---|
|
Una respuesta correcta devuelve una estructura como se muestra a continuación.
| code language-json |
|---|
|
Crear una conexión de origen source-connection
Puede crear una conexión de origen realizando una solicitud de POST a la API Flow Service. Una conexión de origen consta de un identificador de conexión, una ruta de acceso al archivo de datos de origen y un identificador de especificación de conexión.
Formato de API
POST /sourceConnections
Solicitud
La siguiente solicitud crea una conexión de origen para SugarCRM Accounts & Contacts:
Según el tipo de objeto que esté aprovechando, seleccione una de las pestañas siguientes:
Para la API de cuentas SugarCRM, el valor de propiedad object_type debe ser accounts.
| code language-shell |
|---|
|
Para la API de contactos de SugarCRM, el valor de la propiedad object_type debe ser contacts.
| code language-shell |
|---|
|
namedescriptionbaseConnectionIdconnectionSpec.iddata.formatjson.object_typeSugarCRM Accounts & Contacts admite varias API. Según el tipo de objeto que esté aprovechando, pase uno de los siguientes:
accounts: Compañías con las que su organización tiene una relación.contacts: Personas individuales con las que su organización tiene una relación establecida.
pathobject_type.Respuesta
Una respuesta correcta devuelve el identificador único (id) de la conexión de origen recién creada. Este ID es necesario en un paso posterior para crear un flujo de datos.
{
"id": "8f1fc72a-f562-4a1d-8597-85b5ca1b1cd3",
"etag": "\"ed05f1e1-0000-0200-0000-6368b8710000\""
}
Creación de un esquema XDM de destino target-schema
Para que los datos de origen se utilicen en Platform, se debe crear un esquema de destino para estructurar los datos de origen según sus necesidades. A continuación, el esquema de destino se utiliza para crear un conjunto de datos de Platform en el que se incluyen los datos de origen.
Se puede crear un esquema XDM de destino realizando una solicitud de POST a la API de Registro de esquemas.
Para ver los pasos detallados sobre cómo crear un esquema XDM de destino, consulte el tutorial de creación de un esquema mediante la API.
Crear un conjunto de datos de destinatario target-dataset
Se puede crear un conjunto de datos de destino realizando una solicitud de POST a la API de servicio de catálogo, que proporcione el ID del esquema de destino en la carga útil.
Para ver los pasos detallados sobre cómo crear un conjunto de datos de destino, consulte el tutorial de creación de un conjunto de datos mediante la API.
Creación de una conexión de destino target-connection
Una conexión de destino representa la conexión con el destino en el que se van a almacenar los datos introducidos. Para crear una conexión de destino, debe proporcionar el ID de especificación de conexión fija que corresponda al lago de datos. Este identificador es: c604ff05-7f1a-43c0-8e18-33bf874cb11c.
Ahora tiene los identificadores únicos de un esquema de destino, un conjunto de datos de destino y el ID de especificación de conexión al lago de datos. Con estos identificadores, puede crear una conexión de destino utilizando la API Flow Service para especificar el conjunto de datos que contendrá los datos de origen entrantes.
Formato de API
POST /targetConnections
Solicitud
La siguiente solicitud crea una conexión de destino para 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.dataSetIdRespuesta
Una respuesta correcta devuelve el identificador único (id) de la nueva conexión de destino. Este ID es necesario en pasos posteriores.
{
"id": "6b137bf6-d2a0-48c8-914b-d50f4942eb85",
"etag": "\"8405a268-0000-0200-0000-6368b8c30000\""
}
Creación de una asignación mapping
Para que los datos de origen se incorporen en un conjunto de datos de destino, primero deben asignarse al esquema de destino al que se adhiere el conjunto de datos de destino. Esto se logra realizando una solicitud de POST a Data Prep API con asignaciones de datos definidas dentro de la carga útil de la solicitud.
Formato de API
POST /conversion/mappingSets
Solicitud
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.destinationRespuesta
Una respuesta correcta devuelve detalles de la asignación recién creada, incluido su identificador único (id). Este valor es necesario en un paso posterior para crear un flujo de datos.
{
"id": "059c69f7207b4d7e9b48c47e2fd966a6",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Creación de un flujo flow
El último paso para llevar datos de SugarCRM Accounts & Contacts a Platform es crear un flujo de datos. Por ahora, tiene preparados los siguientes valores obligatorios:
Un flujo de datos es responsable de programar y recopilar datos de una fuente. Puede crear un flujo de datos realizando una solicitud de POST mientras proporciona los valores mencionados anteriormente dentro de la carga útil.
Para programar una ingesta, primero debe establecer el valor de la hora de inicio en un tiempo récord en segundos. A continuación, debe establecer el valor de frecuencia en hour o day. El valor de intervalo designa el periodo entre dos ingestas consecutivas. El valor del intervalo debe establecerse como 1 o 24 según la selección de scheduleParams.frequency de hour o day.
Formato de API
POST /flows
Solicitud
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 o day.scheduleParams.interval1 o 24 según la selección de scheduleParams.frequency de hour o day.Respuesta
Una respuesta correcta devuelve el identificador (id) del flujo de datos recién creado. Puede utilizar este ID para monitorizar, actualizar o eliminar el flujo de datos.
{
"id": "fcd16140-81b4-422a-8f9a-eaa92796c4f4",
"etag": "\"9200a171-0000-0200-0000-6368c1da0000\""
}
Apéndice
En la siguiente sección se proporciona información sobre los pasos que puede seguir para monitorizar, actualizar y eliminar el flujo de datos.
Monitorización del flujo de datos
Una vez creado el flujo de datos, puede monitorizar los datos que se están introduciendo a través de él para ver información sobre las ejecuciones de flujo, el estado de finalización y los errores. Para ver ejemplos completos de API, lee la guía sobre supervisión de los flujos de datos de origen mediante la API.
Actualizar el flujo de datos
Actualice los detalles del flujo de datos, como su nombre y descripción, así como su programación de ejecución y los conjuntos de asignaciones asociados realizando una solicitud del PATCH al extremo /flows de la API Flow Service, proporcionando al mismo tiempo el ID del flujo de datos. Al realizar una solicitud de PATCH, debe proporcionar el etag único del flujo de datos en el encabezado If-Match. Para ver ejemplos completos de la API, lea la guía sobre actualización de flujos de datos de origen mediante la API
Actualice su cuenta
Actualice el nombre, la descripción y las credenciales de su cuenta de origen realizando una solicitud de PATCH a la API Flow Service y proporcionando al mismo tiempo el identificador de conexión base como parámetro de consulta. Al realizar una solicitud de PATCH, debe proporcionar el etag único de su cuenta de origen en el encabezado If-Match. Para ver ejemplos completos de API, lee la guía de actualización de tu cuenta de origen mediante la API.
Eliminar el flujo de datos
Elimine el flujo de datos realizando una solicitud de DELETE a la API Flow Service mientras proporciona el ID del flujo de datos que desea eliminar como parte del parámetro query. Para ver ejemplos completos de API, lea la guía sobre eliminación de flujos de datos mediante la API.
Eliminar su cuenta
Elimine la cuenta realizando una solicitud de DELETE a la API Flow Service y proporcionando al mismo tiempo el identificador de conexión base de la cuenta que desea eliminar. Para ver ejemplos completos de API, lee la guía sobre eliminar tu cuenta de origen mediante la API.