Para conectarse a un destino, necesita el Administrar destinos permiso de control de acceso.
Para activar los datos, necesita el Administrar destinos, Activar destinos, Ver perfiles, y Ver segmentos permisos de control de acceso.
Lea el información general de control de acceso o póngase en contacto con el administrador del producto para obtener los permisos necesarios.
En este tutorial se muestra cómo utilizar las llamadas de API para conectarse a los datos de Adobe Experience Platform y crear una conexión a un destino de almacenamiento de nube de flujo continuo (Amazon Kinesis o Azure Event Hubs), cree un flujo de datos al nuevo destino creado y active los datos en el nuevo destino creado.
Este tutorial utiliza el Amazon Kinesis en todos los ejemplos, pero los pasos son idénticos para Azure Event Hubs.
Si prefiere utilizar la interfaz de usuario de Platform para conectarse a un destino y activar datos, consulte la Conectar un destino y Activar datos de audiencia en destinos de exportación de audiencia de flujo continuo tutoriales.
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.
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.
accessKeyId
, secretKey
, region
o connectionUrl
sasKeyName
, sasKey
, namespace
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 llamadas de API de ejemplo en la guía de solución de problemas del Experience Platform.
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:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
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.
{SANDBOX_NAME}
Para obtener más información sobre los entornos limitados de Experience Platform, consulte la documentación general de zona protegida.
Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado de tipo de medios adicional:
application/json
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.
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 a connectionSpecs
extremo 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 de código en la respuesta:
{
"id": "86043421-563b-46ec-8e6c-e23184711bf6",
"name": "Amazon Kinesis",
...
...
}
{
"id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
"name": "Azure Event Hubs",
...
...
}
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.
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"
}
}'
{CONNECTION_SPEC_ID}
: utilice el ID de especificación de conexión para el servicio de perfil - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.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"
}
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": {}
}'
{BASE_CONNECTION_ID}
: utilice el ID que ha obtenido en el paso anterior.{CONNECTION_SPEC_ID}
: utilice el ID de especificación de conexión para el servicio de perfil - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
.Respuesta
Una respuesta correcta devuelve el identificador único (id
) para 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"
}
En este paso, está configurando una conexión al destino de flujo continuo deseado. Consta de dos subpasos que se describen a continuación.
Formato de API
POST /connections
Solicitud
El ejemplo siguiente incluye comentarios de código con el prefijo //
. Estos comentarios resaltan dónde se deben utilizar valores diferentes para distintos destinos de flujo continuo. Elimine los comentarios antes de utilizar el fragmento.
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}"
}
}
}'
{CONNECTION_SPEC_ID}
: utilice el ID de especificación de conexión obtenido en el paso Obtener la lista de destinos disponibles.{AUTHENTICATION_CREDENTIALS}
: indique el nombre del destino de flujo continuo: Aws Kinesis authentication credentials
o Azure EventHub authentication credentials
.{ACCESS_ID}
: Para Amazon Kinesis conexiones. Su ID de acceso para la ubicación de almacenamiento de Amazon Kinesis.{SECRET_KEY}
: Para Amazon Kinesis conexiones. Su clave secreta para su ubicación de almacenamiento de Amazon Kinesis.{REGION}
: Para Amazon Kinesis conexiones. La región en su Amazon Kinesis cuenta en la que Platform transmitirá los datos.{SAS_KEY_NAME}
: Para Azure Event Hubs conexiones. Rellene el nombre de clave SAS. Obtenga información sobre la autenticación en Azure Event Hubs con claves SAS en el Documentación de Microsoft.{SAS_KEY}
: Para Azure Event Hubs conexiones. Rellene la clave SAS. Obtenga información sobre la autenticación en Azure Event Hubs con claves SAS en el Documentación de Microsoft.{EVENT_HUB_NAMESPACE}
: Para Azure Event Hubs conexiones. Rellene el Azure Event Hubs área de nombres donde Platform transmitirá los datos. Para obtener más información, consulte Crear un área de nombres de Event Hubs en el Microsoft documentación.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"
}
Formato de API
POST /targetConnections
Solicitud
El ejemplo siguiente incluye comentarios de código con el prefijo //
. Estos comentarios resaltan dónde se deben utilizar valores diferentes para distintos destinos de flujo continuo. Elimine los comentarios antes de utilizar el fragmento.
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}"
}
}'
{BASE_CONNECTION_ID}
: utilice el ID de conexión base que obtuvo en el paso anterior.{CONNECTION_SPEC_ID}
: utilice la especificación de conexión obtenida en el paso Obtener la lista de destinos disponibles.{NAME_OF_DATA_STREAM}
: Para Amazon Kinesis conexiones. Proporcione el nombre del flujo de datos existente en su Amazon Kinesis cuenta. Platform exportará datos a este flujo.{REGION}
: Para Amazon Kinesis conexiones. Región de la cuenta de Kinesis de Amazon donde Platform transmitirá los datos.{EVENT_HUB_NAME}
: Para Azure Event Hubs conexiones. Rellene el Azure Event Hub Nombre donde Platform transmitirá los datos. Para obtener más información, consulte Crear un centro de eventos en el Microsoft documentación.Respuesta
Una respuesta correcta devuelve el identificador único (id
) para la conexión de destino recién creada a su destino de flujo continuo. Almacene este valor tal como se requiere en pasos posteriores.
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
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": [
]
}
}
}
]
}
{FLOW_SPEC_ID}
: el ID de especificación de flujo para destinos basados en perfiles es 71471eba-b620-49e4-90fd-23f1fa0174d8
. Utilice este valor en la llamada de.{SOURCE_CONNECTION_ID}
: utilice el ID de conexión de origen obtenido en el paso Conectar con el Experience Platform.{TARGET_CONNECTION_ID}
: utilice el ID de conexión de destino obtenido en el paso Conectar con destino de flujo continuo.Respuesta
Una respuesta correcta devuelve el ID (id
) del flujo de datos recién creado y una 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"
}
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 sobre el 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}"
}
}
}
]
Propiedad | Descripción |
---|---|
{DATAFLOW_ID} |
En la dirección URL, utilice el ID del flujo de datos que creó en el paso anterior. |
{ETAG} |
Obtenga la {ETAG} a partir de la respuesta del paso anterior, Creación de un flujo de datos. El formato de respuesta del paso anterior tiene comillas de escape. Debe utilizar los valores sin escape en el encabezado de la solicitud. Consulte el ejemplo siguiente:
El valor de la etiqueta se actualiza con cada actualización correcta de un flujo de datos. |
{SEGMENT_ID} |
Proporcione el ID de audiencia que desea exportar a este destino. Para recuperar los ID de audiencia de las audiencias que desea activar, consulte recuperar una definición de audiencia en la referencia de la API de Experience Platform. |
{PROFILE_ATTRIBUTE} |
Por ejemplo, "person.lastName" |
op |
La llamada de operación utilizada para definir la acción necesaria para actualizar el flujo de datos. Las operaciones incluyen: add , replace , y remove . Para añadir una audiencia a un flujo de datos, utilice el add operación. |
path |
Define la parte del flujo que se va a actualizar. Al añadir una audiencia a un flujo de datos, utilice la ruta especificada en el ejemplo. |
value |
El nuevo valor con el que desea actualizar el parámetro. |
id |
Especifique el ID de la audiencia que está agregando al flujo de datos de destino. |
name |
Opcional. Especifique el nombre de la audiencia que está agregando al flujo de datos de destino. Tenga en cuenta que este campo no es obligatorio y puede añadir correctamente una audiencia al flujo de datos de destino sin proporcionar su nombre. |
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.
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}"'
{DATAFLOW_ID}
: utilice el flujo de datos del paso anterior.{ETAG}
: utilice la etiqueta del paso anterior.Respuesta
La respuesta devuelta debe incluir en transformations
Los parámetros utilizan los atributos de audiencias y perfil enviados en el paso anterior. Una muestra transformations
en la respuesta podría tener el siguiente aspecto:
"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
Además de los atributos de perfil y las audiencias del paso Activar datos en el nuevo destino, los datos exportados en AWS Kinesis y Azure Event Hubs también incluirá información sobre el mapa de identidad. Representa las identidades de los perfiles exportados (por ejemplo, ECID, ID móvil, ID de Google, dirección de correo electrónico, etc.). Vea el ejemplo siguiente.
{
"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"
}
]
}
}
Para conectarse a los destinos de flujo continuo descritos en este tutorial de una manera más ágil, puede utilizar Postman.
Postman es una herramienta que puede utilizar para realizar llamadas de API y administrar bibliotecas de llamadas y entornos predefinidos.
Para este tutorial específico, haga lo siguiente Postman se han adjuntado colecciones:
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.
Para conectarse correctamente a los destinos de mediante el adjunto Postman colecciones, siga estos pasos:
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 cómo interpretar las respuestas de error.
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: