Documentación Experience Platform Guía de conectores de origen

Crear un flujo de datos para Mailchimp Campaign mediante la API de Flow Service

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Temas:

Creado para:

Desarrollador

El siguiente tutorial lo acompañará durante los pasos para crear una conexión de origen y un flujo de datos para llevar datos de Mailchimp Campaign a Platform mediante la Flow Service API.

Requisitos previos

Antes de poder conectar Mailchimp a Adobe Experience Platform mediante el código de actualización de OAuth 2, primero debe recuperar el token de acceso de MailChimp… Consulte la Mailchimp guía de OAuth 2 para obtener instrucciones detalladas sobre cómo encontrar el token de acceso.

Crear una conexión base base-connection

Una vez que haya recuperado sus credenciales de autenticación Mailchimp, ahora puede iniciar el proceso de creación del flujo de datos para llevar los datos de Mailchimp Campaign a Platform. El primer paso para crear un flujo de datos es crear una conexión base.

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.

Mailchimp admite tanto la autenticación básica como el código de actualización de OAuth 2. Consulte los siguientes ejemplos para obtener instrucciones sobre cómo autenticarse con cualquiera de los tipos de autenticación.

Crear una conexión base Mailchimp mediante autenticación básica

Para crear una conexión base de Mailchimp con autenticación básica, realice una solicitud de POST al extremo /connections de la API Flow Service y proporcione las credenciales para authorizationTestUrl, username y password.

Formato de API

POST /connections

Solicitud

La siguiente solicitud crea una conexión base para Mailchimp:

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "Mailchimp base connection with basic authentication",
      "description": "Mailchimp Campaign base connection with basic authentication",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "auth": {
          "specName": "Basic Authentication",
          "params": {
              "authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
              "username": "{USERNAME}",
              "password": "{PASSWORD}"
          }
      }
  }'

Propiedad

Descripción

name

Nombre de la conexión base. Asegúrese de que el nombre de la conexión base sea descriptivo, ya que puede utilizarlo para buscar información sobre la conexión base.

description

(Opcional) Una propiedad que puede incluir para proporcionar más información sobre la conexión base.

connectionSpec.id

El ID de especificación de conexión de su origen. Este identificador se puede recuperar una vez que su origen se haya registrado y aprobado mediante la API Flow Service.

auth.specName

El tipo de autenticación que utiliza para conectar el origen a Platform.

auth.params.authorizationTestUrl

(Opcional) La dirección URL de prueba de autorización se utiliza para validar credenciales al crear una conexión base. Si no se proporcionan, las credenciales se comprueban automáticamente durante el paso de creación de la conexión de origen.

auth.params.username

El nombre de usuario que corresponde con su cuenta de Mailchimp. Esto es necesario para la autenticación básica.

auth.params.password

La contraseña correspondiente a su cuenta de Mailchimp. Esto es necesario para la autenticación básica.

Respuesta

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": "9601747c-6874-4c02-bb00-5732a8c43086",
    "etag": "\"3702dabc-0000-0200-0000-615b5b5a0000\""
}

Crear una conexión base Mailchimp mediante el código de actualización de OAuth 2

Para crear una conexión base Mailchimp con el código de actualización de OAuth 2, realice una solicitud de POST al extremo /connections y proporcione las credenciales para authorizationTestUrl y accessToken.

Formato de API

POST /connections

Solicitud

La siguiente solicitud crea una conexión base para Mailchimp:

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "Mailchimp base connection with OAuth 2 refresh code",
      "description": "Mailchimp Campaign base connection with OAuth 2 refresh code",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "auth": {
          "specName": "oAuth2RefreshCode",
          "params": {
              "authorizationTestUrl": "https://login.mailchimp.com/oauth2/metadata",
              "accessToken": "{ACCESS_TOKEN}"
          }
      }
  }'

Propiedad

Descripción

name

Nombre de la conexión base. Asegúrese de que el nombre de la conexión base sea descriptivo, ya que puede utilizarlo para buscar información sobre la conexión base.

description

(Opcional) Una propiedad que puede incluir para proporcionar más información sobre la conexión base.

connectionSpec.id

El ID de especificación de conexión de su origen. Este identificador se puede recuperar después de registrar el origen mediante la API Flow Service.

auth.specName

El tipo de autenticación que utiliza para autenticar el origen en Platform.

auth.params.authorizationTestUrl

(Opcional) La URL de prueba de autorización se utiliza para validar credenciales al crear una conexión base. Si no se proporcionan, las credenciales se comprueban automáticamente durante el paso de creación de la conexión de origen.

auth.params.accessToken

El token de acceso correspondiente utilizado para autenticar el origen. Esto es necesario para la autenticación basada en OAuth.

Respuesta

{
    "id": "9601747c-6874-4c02-bb00-5732a8c43086",
    "etag": "\"3702dabc-0000-0200-0000-615b5b5a0000\""
}

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. 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:

Parámetro

Descripción

{BASE_CONNECTION_ID}

El ID de conexión base generado en el paso anterior.

{OBJECT_TYPE}

El tipo de objeto que desea explorar. Para orígenes REST, este valor predeterminado es rest.

{OBJECT}

El objeto que desea explorar.

{FILE_TYPE}

Este parámetro solo es necesario cuando se visualiza un directorio específico. Su valor representa la ruta del directorio que desea explorar.

{PREVIEW}

Un valor booleano que define si el contenido de la conexión admite la vista previa.

{SOURCE_PARAMS}

Una cadena codificada en base64 de su campaign_id.

TIP

Para recuperar el tipo de formato aceptado para {SOURCE_PARAMS}, debe codificar toda la cadena campaignId en base64. Por ejemplo, {"campaignId": "c66a200cda"} codificado en base64 equivale a eyJjYW1wYWlnbklkIjoiYzY2YTIwMGNkYSJ9.

Formato de API

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&objectType={OBJECT_TYPE}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}

Solicitud

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/connections/05c595e5-edc3-45c8-90bb-fcf556b57c4b/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJjYW1wYWlnbklkIjoiYzY2YTIwMGNkYSJ9' \
  -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}'

Respuesta

Una respuesta correcta devuelve la estructura del archivo consultado.

{
    "data": [
        {
            "emails": [
                {
                    "campaign_id": "c66a200cda",
                    "list_id": "10c097ca71",
                    "list_is_active": true,
                    "email_id": "cff65fb4c5f5828666ad846443720efd",
                    "email_address": "kendall2134@gmail.com",
                    "_links": [
                        {
                            "rel": "parent",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/CollectionResponse.json"
                        },
                        {
                            "rel": "self",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity/cff65fb4c5f5828666ad846443720efd",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/Response.json"
                        },
                        {
                            "rel": "member",
                            "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/cff65fb4c5f5828666ad846443720efd",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
                        }
                    ]
                },
                {
                    "campaign_id": "c66a200cda",
                    "list_id": "10c097ca71",
                    "list_is_active": true,
                    "email_id": "a16b82774b211afaf60902d1afd8abc5",
                    "email_address": "logan9935890967@gmail.com",
                    "_links": [
                        {
                            "rel": "parent",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/CollectionResponse.json"
                        },
                        {
                            "rel": "self",
                            "href": "https://us6.api.mailchimp.com/3.0/reports/c66a200cda/email-activity/a16b82774b211afaf60902d1afd8abc5",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Reports/EmailActivity/Response.json"
                        },
                        {
                            "rel": "member",
                            "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members/a16b82774b211afaf60902d1afd8abc5",
                            "method": "GET",
                            "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.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.

Para crear una conexión de origen, también debe definir un valor de enumeración para el atributo de formato de datos.

Utilice los siguientes valores de enumeración para orígenes basados en archivos:

Formato de datos

Valor de enumeración

Delimitado

delimited

JSON

json

Parquet

parquet

Para todos los orígenes basados en tablas, establezca el valor en tabular.

Formato de API

POST /sourceConnections

Solicitud

La siguiente solicitud crea una conexión de origen para Mailchimp:

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "MailChimp source connection to ingest campaign ID",
      "description": "MailChimp Campaign source connection to ingest campaign ID",
      "baseConnectionId": "4cea039f-f1cc-4fa5-9136-db8dd4c7fbfa",
      "connectionSpec": {
          "id": "c8ce8c8c-37fb-4162-9fbf-c2f181e04a7a",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      },
      "params": {
          "campaignId": "c66a200cda"
      }
  }'

Propiedad

Descripción

name

Nombre de la conexión de origen. Asegúrese de que el nombre de la conexión de origen sea descriptivo, ya que puede utilizarlo para buscar información sobre la conexión de origen.

description

Un valor opcional que puede incluir para proporcionar más información sobre la conexión de origen.

baseConnectionId

Identificador de conexión base de Mailchimp. Este ID se generó en un paso anterior.

connectionSpec.id

El ID de especificación de conexión que corresponde a su origen.

data.format

Formato de los datos de Mailchimp que desea introducir.

params.campaignId

El identificador de campaña Mailchimp identifica una campaña Mailchimp específica, que a su vez le permite enviar correos electrónicos a sus listas o audiencias.

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": "d6557bf1-7347-415f-964c-9316bd4cbf56",
    "etag": "\"e205c206-0000-0200-0000-615b5c070000\""
}

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 donde aterrizan los datos introducidos. Para crear una conexión de destino, debe proporcionar el identificador de especificación de conexión fija que corresponda a Data Lake. Este identificador es: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Ahora tiene los identificadores únicos de un esquema de destino de un conjunto de datos de destino y el ID de especificación de conexión de Data Lake. 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 Mailchimp:

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "MailChimp target connection",
      "description": "MailChimp Campaign target connection",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "parquet_xdm",
          "schema": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/570630b91eb9d5cf5db0436756abb110d02912917a67da2d",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "6155e3a9bd13651949515f14"
      }
  }'

Propiedad

Descripción

name

Nombre de la conexión de destino. Asegúrese de que el nombre de la conexión de destino sea descriptivo, ya que puede utilizarlo para buscar información sobre la conexión de destino.

description

Un valor opcional que puede incluir para proporcionar más información sobre la conexión de destino.

connectionSpec.id

Identificador de especificación de conexión que corresponde a Data Lake. Este identificador fijo es: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

data.format

Formato de los datos de Mailchimp que desea llevar a Platform.

params.dataSetId

ID del conjunto de datos de destino recuperado en un paso anterior.

Respuesta

Una respuesta correcta devuelve el identificador único (id) de la nueva conexión de destino. Este ID es necesario en pasos posteriores.

{
    "id": "9463fe9c-027d-4347-a423-894fcd105647",
    "etag": "\"b902e822-0000-0200-0000-615b5c370000\""
}

IMPORTANT

Actualmente no se admiten funciones de preparación de datos para Mailchimp Campaign.

Creación de un flujo flow

El último paso para llevar los datos de Mailchimp a Platform es crear un flujo de datos. Por ahora, tiene preparados los siguientes valores obligatorios:

ID de conexión de Source
ID de conexión de destino

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 una de las cinco opciones: once, minute, hour, day o week. El valor de intervalo designa el período entre dos ingestas consecutivas y la creación de una ingesta única (once) no requiere que se establezca un intervalo. Para todas las demás frecuencias, el valor del intervalo debe establecerse en igual o mayor que 15.

Formato de API

POST /flows

Solicitud

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/flows' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
      "name": "MailChimp Campaign dataflow",
      "description": "MailChimp Campaign dataflow",
      "flowSpec": {
          "id": "6499120c-0b15-42dc-936e-847ea3c24d72",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "d6557bf1-7347-415f-964c-9316bd4cbf56"
      ],
      "targetConnectionIds": [
          "9463fe9c-027d-4347-a423-894fcd105647"
      ],
      "scheduleParams": {
          "startTime": "1632809759",
          "frequency": "minute",
          "interval": 15
      }
  }'

Propiedad

Descripción

name

Nombre del flujo de datos. Asegúrese de que el nombre del flujo de datos sea descriptivo, ya que puede utilizarlo para buscar información en él.

description

(Opcional) Una propiedad que puede incluir para proporcionar más información sobre el flujo de datos.

flowSpec.id

ID de especificación de flujo necesario para crear un flujo de datos. Este identificador fijo es: 6499120c-0b15-42dc-936e-847ea3c24d72.

flowSpec.version

La versión correspondiente del ID de especificación de flujo. El valor predeterminado es 1.0.

sourceConnectionIds

Id. de conexión de origen generado en un paso anterior.

targetConnectionIds

Id. de conexión de destino generado en un paso anterior.

scheduleParams.startTime

Hora de inicio designada para el momento en el que comienza la primera ingesta de datos.

scheduleParams.frequency

Frecuencia con la que el flujo de datos recopilará datos. Los valores aceptables incluyen: once, minute, hour, day o week.

scheduleParams.interval

El intervalo designa el período entre dos ejecuciones de flujo consecutivas. El valor del intervalo debe ser un entero distinto de cero. El intervalo no es necesario cuando la frecuencia está establecida como once y debe ser mayor o igual que 15 para otros valores de frecuencia.

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": "be2d5249-eeaf-4a74-bdbd-b7bf62f7b2da",
    "etag": "\"7e010621-0000-0200-0000-615b5c9b0000\""
}

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 orígenes y flujos de datos 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.

recommendation-more-help

337b99bb-92fb-42ae-b6b7-c7042161d089