Conéctese a destinos de flujo continuo y active los datos mediante la API de Flow Service

Este tutorial muestra cómo usar llamadas de API para conectarse a los datos de Adobe Experience Platform, crear una conexión a un destino de almacenamiento de nube de streaming (Amazon Kinesis o Azure Event Hubs), crear un flujo de datos al nuevo destino creado y activar los datos en el nuevo destino creado.

Este tutorial utiliza el destino Amazon Kinesis en todos los ejemplos, pero los pasos son idénticos para Azure Event Hubs.

Si prefiere usar la interfaz de usuario de Platform para conectarse a un destino y activar datos, consulte los tutoriales Conectar un destino y Activar datos de audiencia en destinos de exportación de audiencias de streaming.

Introducción

Esta guía requiere una comprensión práctica de los siguientes componentes de Adobe Experience Platform:

Las secciones siguientes proporcionan información adicional que necesitará conocer para activar los datos en los destinos de flujo continuo en Platform.

Recopilar credenciales necesarias

Para completar los pasos de este tutorial, debe tener las siguientes credenciales listas, según el tipo de destinos a los que conecte y active audiencias.

Lectura de llamadas de API de muestra reading-sample-api-calls

Este tutorial proporciona llamadas de API de ejemplo para demostrar cómo dar formato a las solicitudes. Estas incluyen rutas, encabezados obligatorios y cargas de solicitud con el formato correcto. También se proporciona el JSON de muestra devuelto en las respuestas de la API. Para obtener información sobre las convenciones utilizadas en la documentación de las llamadas de API de ejemplo, consulte la sección sobre cómo leer las llamadas de API de ejemplo en la guía de solución de problemas del Experience Platform.

Recopilar valores para encabezados obligatorios y opcionales gather-values

Para realizar llamadas a las API de Platform, primero debe completar el tutorial de autenticación. Al completar el tutorial de autenticación, se proporcionan los valores de cada uno de los encabezados necesarios en todas las llamadas a la API de Experience Platform, como se muestra a continuación:

Los recursos de Experience Platform se pueden aislar en zonas protegidas virtuales específicas. En las solicitudes a las API de Platform, puede especificar el nombre y el ID de la zona protegida en la que se realizará la operación. Son parámetros opcionales.

Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado de tipo de medios adicional:

Documentación de Swagger swagger-docs

Puede encontrar la documentación de referencia adjunta para todas las llamadas a la API en este tutorial en Swagger. Consulte la documentación de la API de Flow Service en Adobe I/O. Le recomendamos que utilice este tutorial y la página de documentación de Swagger en paralelo.

Obtener la lista de destinos de streaming disponibles get-the-list-of-available-streaming-destinations

Como primer paso, debe decidir a qué destino de flujo continuo activar los datos. Para empezar, realice una llamada a para solicitar una lista de destinos disponibles a los que pueda conectar y activar audiencias. Realice la siguiente solicitud de GET al extremo connectionSpecs para devolver una lista de destinos disponibles:

Formato de API

GET /connectionSpecs

Solicitud

curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

Respuesta

Una respuesta correcta contiene una lista de destinos disponibles y sus identificadores únicos (id). Almacene el valor del destino que planea utilizar, ya que será necesario en pasos adicionales. Por ejemplo, si desea conectarse y enviar audiencias a Amazon Kinesis o Azure Event Hubs, busque el siguiente fragmento en la respuesta:

{
    "id": "86043421-563b-46ec-8e6c-e23184711bf6",
  "name": "Amazon Kinesis",
  ...
  ...
}

{
    "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
  "name": "Azure Event Hubs",
  ...
  ...
}

Conexión a los datos del Experience Platform connect-to-your-experience-platform-data

de información general

A continuación, debe conectarse a los datos del Experience Platform para poder exportar datos de perfil y activarlos en su destino preferido. Consta de dos subpasos que se describen a continuación.

Autorizar el acceso a los datos en Experience Platform

Formato de API

POST /connections

Solicitud

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'

Respuesta

Una respuesta correcta contiene el identificador único de la conexión base (id). Almacene este valor tal como se requiere en el siguiente paso para crear la conexión de origen.

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Conexión a los datos del Experience Platform connect-to-platform-data

Formato de API

POST /sourceConnections

Solicitud

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "json"
            },
            "params": {}
}'

Respuesta

Una respuesta correcta devuelve el identificador único (id) de la conexión de origen recién creada al servicio de perfil. Esto confirma que se ha conectado correctamente a los datos del Experience Platform. Almacene este valor tal como se requiere en un paso posterior.

{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

Conectar con destino de flujo continuo connect-to-streaming-destination

de información general

En este paso, está configurando una conexión al destino de flujo continuo deseado. Consta de dos subpasos que se describen a continuación.

Autorizar el acceso al destino de flujo continuo

Formato de API

POST /connections

Solicitud

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connection for Amazon Kinesis/ Azure Event Hubs",
    "description": "summer advertising campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{AUTHENTICATION_CREDENTIALS}",
        "params": { // use these values for Amazon Kinesis connections
            "accessKeyId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}",
            "region": "{REGION}"
        },
        "params": { // use these values for Azure Event Hubs connections
            "sasKeyName": "{SAS_KEY_NAME}",
            "sasKey": "{SAS_KEY}",
            "namespace": "{EVENT_HUB_NAMESPACE}"
        }
    }
}'

Respuesta

Una respuesta correcta contiene el identificador único de la conexión base (id). Almacene este valor tal como se requiere en el siguiente paso para crear una conexión de destino.

{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Especificar la ubicación de almacenamiento y el formato de datos

Formato de API

POST /targetConnections

Solicitud

curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Amazon Kinesis/ Azure Event Hubs target connection",
    "description": "Connection to Amazon Kinesis/ Azure Event Hubs",
    "baseConnectionId": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json"
    },
    "params": { // use these values for Amazon Kinesis connections
        "stream": "{NAME_OF_DATA_STREAM}",
        "region": "{REGION}"
    },
    "params": { // use these values for Azure Event Hubs connections
        "eventHubName": "{EVENT_HUB_NAME}"
    }
}'

Respuesta

Una respuesta correcta devuelve el identificador único (id) de la conexión de destino recién creada con el destino de flujo continuo. Almacene este valor tal como se requiere en pasos posteriores.

{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

Creación de un flujo de datos

Con los ID que obtuvo en los pasos anteriores, ahora puede crear un flujo de datos entre los datos del Experience Platform y el destino al que activará los datos. Piense en este paso como si construyera la canalización, a través de la cual fluirán los datos posteriormente, entre Experience Platform y el destino deseado.

Para crear un flujo de datos, realice una solicitud de POST como se muestra a continuación, proporcionando los valores mencionados a continuación dentro de la carga útil.

Realice la siguiente solicitud del POST para crear un flujo de datos.

Formato de API

POST /flows

Solicitud

curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-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": "Azure Event Hubs",
  "description": "Azure Event Hubs",
  "flowSpec": {
    "id": "{FLOW_SPEC_ID}",
    "version": "1.0"
  },
  "sourceConnectionIds": [
    "{SOURCE_CONNECTION_ID}"
  ],
  "targetConnectionIds": [
    "{TARGET_CONNECTION_ID}"
  ],
  "transformations": [
    {
      "name": "GeneralTransform",
      "params": {
        "profileSelectors": {
          "selectors": [

          ]
        },
        "segmentSelectors": {
          "selectors": [

          ]
        }
      }
    }
  ]
}

Respuesta

Una respuesta correcta devuelve el identificador (id) del flujo de datos recién creado y un etag. Tenga en cuenta ambos valores. al igual que lo hará en el siguiente paso, para activar audiencias.

{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

Activar datos en el nuevo destino activate-data

Una vez creadas todas las conexiones y el flujo de datos, ahora puede activar los datos de perfil en la plataforma de flujo continuo. En este paso, se selecciona qué audiencias y qué atributos de perfil se envían al destino y se pueden programar y enviar datos al destino.

Para activar audiencias en su nuevo destino, debe realizar una operación de PATCH de JSON, similar al ejemplo siguiente. Puede activar varias audiencias y atributos de perfil en una llamada. Para obtener más información acerca del PATCH JSON, consulte la especificación RFC.

Formato de API

PATCH /flows

Solicitud

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
  {
    "op": "add",
    "path": "/transformations/0/params/segmentSelectors/selectors/-",
    "value": {
      "type": "PLATFORM_SEGMENT",
      "value": {
        "name": "Name of the audience that you are activating",
        "description": "Description of the audience that you are activating",
        "id": "{SEGMENT_ID}"
      }
    }
  },
  {
    "op": "add",
    "path": "/transformations/0/params/profileSelectors/selectors/-",
    "value": {
      "type": "JSON_PATH",
      "value": {
        "operator": "EXISTS",
        "path": "{PROFILE_ATTRIBUTE}"
      }
    }
  }
]

Respuesta

Busque una respuesta 202 OK. No se devuelve ningún cuerpo de respuesta. Para comprobar que la solicitud es correcta, consulte el paso siguiente, Validación del flujo de datos.

Validación del flujo de datos

de información general

Como último paso del tutorial, debe validar que las audiencias y los atributos de perfil se hayan asignado correctamente al flujo de datos.

Para validar esto, realice la siguiente solicitud de GET:

Formato de API

GET /flows

Solicitud

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {ORG_ID}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"'

Respuesta

La respuesta devuelta debe incluir en el parámetro transformations las audiencias y los atributos de perfil que envió en el paso anterior. Un parámetro transformations de muestra en la respuesta podría ser similar al siguiente:

"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                        "selectors": [
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "personalEmail.address",
                                    "operator": "EXISTS"
                                }
                            },
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "person.lastname",
                                    "operator": "EXISTS"
                                }
                            }
                        ]
                    },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

Datos exportados

{
  "person": {
    "email": "yourstruly@adobe.com"
  },
  "segmentMembership": {
    "ups": {
      "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
        "lastQualificationTime": "2020-03-03T21:24:39Z",
        "status": "exited"
      },
      "7841ba61-23c1-4bb3-a495-00d695fe1e93": {
        "lastQualificationTime": "2020-03-04T23:37:33Z",
        "status": "realized"
      }
    }
  },
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

Utilizando colecciones Postman para conectarse a destinos de flujo continuo collections

Para conectarse a los destinos de flujo continuo descritos en este tutorial de una manera más ágil, puede usar Postman.

Postman es una herramienta que puede usar para hacer llamadas a la API y administrar bibliotecas de llamadas y entornos predefinidos.

Para este tutorial específico, se han adjuntado las siguientes Postman colecciones:

Haga clic aquí para descargar el archivo de colecciones.

Cada colección incluye las solicitudes y variables de entorno necesarias, para AWS Kinesis y Azure Event Hub, respectivamente.

Cómo utilizar las colecciones Postman how-to-use-postman-collections

Para conectarse correctamente a los destinos mediante las colecciones Postman adjuntas, siga estos pasos:

Administración de errores de API api-error-handling

Los extremos de la API en este tutorial siguen los principios generales del mensaje de error de la API del Experience Platform. Consulte Códigos de estado de API y errores de encabezado de solicitud en la guía de solución de problemas de Platform para obtener más información sobre la interpretación de respuestas de error.

Pasos siguientes next-steps

Al seguir este tutorial, ha conectado correctamente Platform a uno de sus destinos de flujo continuo preferidos y ha configurado un flujo de datos en el destino correspondiente. Los datos salientes ahora se pueden utilizar en el destino para el análisis de clientes o cualquier otra operación de datos que desee realizar. Consulte las siguientes páginas para obtener más información: