Activar audiencias en destinos basados en archivos mediante la API de Flow Service
Utilice las funciones mejoradas de exportación de archivos para acceder a la funcionalidad de personalización mejorada al exportar archivos desde Experience Platform:
- Opciones de nomenclatura de archivos adicionales.
- Posibilidad de establecer encabezados de archivo personalizados en los archivos exportados a través del paso de asignación mejorado.
- Capacidad para seleccionar tipo de archivo del archivo exportado.
- Capacidad para personalizar el formato de los archivos de datos CSV exportados.
Esta funcionalidad es compatible con las seis tarjetas de almacenamiento en la nube que se enumeran a continuación:
Este artículo explica el flujo de trabajo necesario para usar la API de Flow Service para exportar perfiles calificados de Adobe Experience Platform a una de las ubicaciones de almacenamiento en la nube vinculadas anteriormente.
Introducción get-started
Esta guía requiere una comprensión práctica de los siguientes componentes de Adobe Experience Platform:
- Experience Data Model (XDM) System: El marco estandarizado mediante el cual Experience Platform organiza los datos de experiencia del cliente.
- Segmentation Service: Adobe Experience Platform Segmentation Service crea audiencias en Adobe Experience Platform a partir de sus datos de Real-Time Customer Profile.
- Sandboxes: Experience Platform proporciona zonas protegidas virtuales que dividen una sola instancia de Experience Platform en entornos virtuales independientes para ayudar a desarrollar y evolucionar aplicaciones de experiencia digital.
Las secciones siguientes proporcionan información adicional que debe conocer para activar datos en destinos basados en archivos en Experience Platform.
Permisos necesarios permissions
Para exportar perfiles, necesita los permisos de control de acceso, Activar destinos, Ver perfiles y Ver segmentos para . Lea la descripción general del control de acceso o póngase en contacto con el administrador del producto para obtener los permisos necesarios.
Para exportar identidades, necesita el permiso de control de acceso de] Ver gráfico de identidad[.
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 muestra, consulte la sección sobre cómo leer llamadas de API de ejemplo en la guía de solución de problemas de Experience Platform.
Recopilar valores para encabezados obligatorios y opcionales gather-values-headers
Para realizar llamadas a las API de Experience Platform, primero debe completar el tutorial de autenticación de Experience Platform. Al completar el tutorial de autenticación, se proporcionan los valores para cada uno de los encabezados obligatorios en todas las llamadas de API de Experience Platform, como se muestra a continuación:
- Autorización: Portador
{ACCESS_TOKEN} - x-api-key:
{API_KEY} - x-gw-ims-org-id:
{ORG_ID}
Los recursos de Experience Platform se pueden aislar en zonas protegidas virtuales específicas. En las solicitudes a las API de Experience Platform, puede especificar el nombre y el ID de la zona protegida en la que se realizará la operación. Son parámetros opcionales.
- x-sandbox-name:
{SANDBOX_NAME}
Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado de tipo multimedia adicional:
- Tipo de contenido:
application/json
Documentación de referencia del API api-reference-documentation
Puede encontrar la documentación de referencia adjunta para todas las operaciones de API en este tutorial. Consulte Flow Service: documentación de la API de destinos en el sitio web de Adobe Developer. Le recomendamos que utilice este tutorial y la documentación de referencia de la API en paralelo.
Glosario glossary
Para obtener descripciones de los términos que encontrará en este tutorial de API, lea la sección del glosario de la documentación de referencia de la API.
Seleccione el destino donde desea exportar las audiencias select-destination
Antes de iniciar el flujo de trabajo para exportar perfiles, identifique la especificación de conexión y los ID de especificación de flujo del destino al que desea exportar las audiencias. Utilice la tabla siguiente como referencia.
4fce964d-3f37-408f-9778-e597338a21ee1a0514a6-33d4-4c7f-aff8-594799c475496d6b59bf-fb58-4107-9064-4d246c0e5bb2752d422f-b16f-4f0d-b1c6-26e448e3b388be2c3209-53bc-47e7-ab25-145db8b873e117be2013-2549-41ce-96e7-a70363bec29310440537-2a7b-4583-ac39-ed38d4b848e8cd2fc47e-e838-4f38-a581-8fff2f99b63ac5d93acb-ea8b-4b14-8f53-02138444ae99585c15c4-6cbf-4126-8f87-e26bff78b65736965a81-b1c6-401b-99f8-22508f1e6a26fd36aaa4-bf2b-43fb-9387-43785eeeb799Estos ID son necesarios para construir varias entidades del servicio de flujo en los siguientes pasos de este tutorial. También debe hacer referencia a partes de la propia especificación de conexión para configurar determinadas entidades y poder recuperar las especificaciones de conexión desde las API de Flow Service. Consulte los ejemplos siguientes de recuperación de especificaciones de conexión para todos los destinos de la tabla:
Solicitud
| accordion | ||
|---|---|---|
| Recuperar connection spec para Amazon S3 | ||
|
Respuesta
| accordion | ||
|---|---|---|
| Amazon S3 - Especificación de conexión | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Recuperar connection spec para Azure Blob Storage | ||
|
Respuesta
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Recuperar connection spec para Azure Data Lake Gen 2(ADLS Gen2) | ||
|
Respuesta
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Recuperar connection spec para Data Landing Zone(DLZ) | ||
|
Respuesta
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Recuperar connection spec para Google Cloud Storage | ||
|
Respuesta
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Recuperar connection spec para SFTP | ||
|
Respuesta
| accordion | ||
|---|---|---|
| SFTP: Connection spec | ||
|
Siga los pasos a continuación para configurar un flujo de datos de exportación de audiencia a un destino de almacenamiento en la nube. En algunos pasos, las solicitudes y respuestas difieren entre los distintos destinos de almacenamiento en la nube. En estos casos, utilice las pestañas de la página para recuperar las solicitudes y respuestas específicas del destino al que desea conectar y exportar audiencias. Asegúrese de usar los connection spec y flow spec correctos para el destino que está configurando.
Crear una conexión de Source create-source-connection
Después de decidir a qué destino están exportando las audiencias, debe crear una conexión de origen. La conexión de origen representa la conexión al almacén interno de perfiles de Experience Platform.
Solicitud
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea al copiar y pegar la solicitud en el terminal que desee.
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Una respuesta correcta devuelve el identificador (id) de la conexión de origen recién creada y un etag. Tenga en cuenta el ID de conexión de origen, ya que lo necesitará más adelante al crear el flujo de datos.
Crear una conexión base create-base-connection
Una conexión base almacena de forma segura las credenciales en su destino. Según el tipo de destino, las credenciales necesarias para autenticarse en ese destino pueden variar. Para encontrar estos parámetros de autenticación, primero recupere connection spec para el destino deseado tal como se describe en la sección Seleccione el destino donde exportar las audiencias y luego observe el authSpec de la respuesta. Haga referencia a las fichas siguientes para las propiedades de authSpec de todos los destinos admitidos.
| accordion | ||
|---|---|---|
| Amazon S3 - Connection spec mostrando auth spec | ||
|
Observe la línea resaltada con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros de autenticación en connection spec.
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec mostrando auth spec | ||
|
Observe la línea resaltada con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros de autenticación en connection spec.
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec mostrando auth spec | ||
|
Observe la línea resaltada con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros de autenticación en connection spec.
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Connection spec mostrando auth spec | |||||
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec mostrando auth spec | ||
|
Observe la línea resaltada con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros de autenticación en connection spec.
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP: Connection spec muestra auth spec | |||||
Observe la línea resaltada con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros de autenticación en connection spec.
|
Con las propiedades especificadas en la especificación de autenticación (que es authSpec de la respuesta) puede crear una conexión base con las credenciales necesarias, específicas para cada tipo de destino, como se muestra en los ejemplos siguientes:
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3: solicitud de conexión base con autenticación de clave de acceso y clave secreta | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitud de conexión base con autenticación de rol asumida | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Amazon S3 respuesta de conexión base | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Solicitud de conexión base | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Azure Blob Storage - Respuesta de conexión base | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Solicitud de conexión base | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Respuesta de conexión base | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Solicitud de conexión base | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Data Landing Zone - Respuesta de conexión base | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Solicitud de conexión base | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Google Cloud Storage - Respuesta de conexión base | ||
|
Solicitud
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFTP con contraseña: solicitud de conexión base | |||||||||||||||||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SFTP con clave SSH: solicitud de conexión base | |||||||||||||||||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| SFTP: respuesta de conexión base | ||
|
Añadir cifrado a los archivos exportados add-encryption
Opcionalmente, puede agregar cifrado a los archivos exportados. Para ello, debe agregar elementos del objeto encryption. Consulte el ejemplo de solicitud que aparece a continuación con los parámetros obligatorios resaltados:
| code language-json line-numbers data-start-1 data-line-offset-4 h-26-27 |
|---|
|
Solicitud
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea al copiar y pegar la solicitud en el terminal que desee.
| code language-shell line-numbers data-start-1 data-line-offset-4 h-19 |
|---|
|
Respuesta
| code language-json |
|---|
|
Observe el ID de conexión de la respuesta. Este ID será necesario en el siguiente paso al crear la conexión de destino.
Creación de una conexión de destino create-target-connection
A continuación, debe crear una conexión de destino. Las conexiones de destino almacenan los parámetros de exportación de las audiencias exportadas. Los parámetros de exportación incluyen la ubicación de exportación, el formato de archivo, la compresión y otros detalles. Por ejemplo, para los archivos CSV, puede seleccionar varias opciones de exportación. Obtenga información detallada sobre todas las opciones de exportación de CSV admitidas en la página configuraciones de formato de archivo.
Consulte las propiedades de targetSpec proporcionadas en connection spec del destino para conocer las propiedades admitidas para cada tipo de destino. Haga referencia a las fichas siguientes para las propiedades de targetSpec de todos los destinos admitidos.
| accordion | ||
|---|---|---|
| Amazon S3 - Connection spec mostrando parámetros de conexión de destino | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros target spec en la especificación de conexión. También puede ver en el ejemplo a continuación cuáles son los parámetros de destino no aplicables a los destinos de exportación de audiencia.
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec mostrando parámetros de conexión de destino | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros target spec en la especificación de conexión. También puede ver en el ejemplo a continuación cuáles son los parámetros de destino no aplicables a los destinos de exportación de audiencia.
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec mostrando parámetros de conexión de destino | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros target spec en la especificación de conexión. También puede ver en el ejemplo a continuación cuáles son los parámetros de destino no aplicables a los destinos de exportación de audiencia.
|
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec mostrando parámetros de conexión de destino | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros target spec en la especificación de conexión. También puede ver en el ejemplo a continuación cuáles son los parámetros de destino no aplicables a los destinos de exportación de audiencia.
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec mostrando parámetros de conexión de destino | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros target spec en la especificación de conexión. También puede ver en el ejemplo a continuación cuáles son los parámetros de destino no aplicables a los destinos de exportación de audiencia.
|
| accordion | ||
|---|---|---|
| SFTP: Connection spec muestra los parámetros de conexión de destino | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo connection spec siguiente, que proporciona información adicional sobre dónde encontrar los parámetros target spec en la especificación de conexión. También puede ver en el ejemplo a continuación cuáles son los parámetros de destino no aplicables a los destinos de exportación de audiencia.
|
Con la especificación anterior, puede construir una solicitud de conexión de destino específica para el destino de almacenamiento en la nube deseado, como se muestra en las pestañas a continuación.
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitud de conexión de destino | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Solicitud de conexión de destino con opciones de CSV | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Conexión de destino: respuesta | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Solicitud de conexión de destino | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Solicitud de conexión de destino con opciones de CSV | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Conexión de destino: respuesta | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Solicitud de conexión de destino | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Solicitud de conexión de destino con opciones de CSV | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Conexión de destino: respuesta | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Solicitud de conexión de destino | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Solicitud de conexión de destino con opciones de CSV | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Conexión de destino: respuesta | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Solicitud de conexión de destino | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Solicitud de conexión de destino con opciones de CSV | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Conexión de destino: respuesta | ||
|
Solicitud
| accordion | |||||
|---|---|---|---|---|---|
| SFTP: solicitud de conexión de destino | |||||
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP: solicitud de conexión de destino con opciones de CSV | |||||
|
Respuesta
| accordion | ||
|---|---|---|
| Conexión de destino: respuesta | ||
|
Observe target connection ID de la respuesta. Este ID será necesario en el siguiente paso al crear el flujo de datos para exportar audiencias.
Una respuesta correcta devuelve el identificador (id) de la conexión de origen de destino reciente y un etag. Tenga en cuenta el ID de conexión de destino, ya que lo necesitará más adelante al crear el flujo de datos.
Creación de un flujo de datos create-dataflow
El siguiente paso en la configuración de destino es crear un flujo de datos. Un flujo de datos vincula las entidades creadas anteriormente y también proporciona opciones para configurar la programación de exportación de audiencias. Para crear el flujo de datos, utilice las cargas útiles que se indican a continuación, según el destino de almacenamiento en la nube deseado, y reemplace los ID de entidad de flujo de los pasos anteriores. Tenga en cuenta que en este paso no se agrega ninguna información relacionada con la asignación de atributos o identidades al flujo de datos. Esto seguirá en el siguiente paso.
Solicitud
| accordion | ||
|---|---|---|
| Crear flujo de datos de exportación de audiencia a Amazon S3 destino: solicitud | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Crear flujo de datos: respuesta | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Crear flujo de datos de exportación de audiencia a Azure Blob Storage destino: solicitud | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Crear flujo de datos: respuesta | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Crear flujo de datos de exportación de audiencia a Azure Data Lake Gen 2(ADLS Gen2) destino: solicitud | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Crear flujo de datos: respuesta | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Crear flujo de datos de exportación de audiencia a Data Landing Zone destino: solicitud | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Crear flujo de datos: respuesta | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Crear flujo de datos de exportación de audiencia a Google Cloud Storage destino: solicitud | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Crear flujo de datos: respuesta | ||
|
Solicitud
| accordion | ||
|---|---|---|
| Crear flujo de datos de exportación de audiencia a destino SFTP: solicitud | ||
|
Observe las líneas resaltadas con comentarios en línea en el ejemplo de la solicitud, que proporcionan información adicional. Elimine los comentarios en línea de la solicitud al copiar y pegar la solicitud en el terminal que desee.
|
Respuesta
| accordion | ||
|---|---|---|
| Crear flujo de datos: respuesta | ||
|
Tenga en cuenta el ID de flujo de datos de la respuesta. Este ID será necesario en pasos posteriores.
Añadir audiencias a la exportación add-audiences
En este paso, también puede seleccionar qué audiencias desea exportar al destino. Para obtener información detallada sobre este paso y el formato de solicitud para agregar una audiencia al flujo de datos, vea los ejemplos en la sección Actualizar un flujo de datos de destino de la documentación de referencia de la API.
Configurar asignación de atributos e identidades attribute-and-identity-mapping
Después de crear el flujo de datos, debe configurar la asignación para los atributos e identidades que desea exportar. Complete los siguientes pasos en orden:
- Recupere el esquema de entrada.
- Recupere e inspeccione el esquema del socio.
- Cree el esquema de salida, incluidos todos los campos que desee exportar como destino de asignación.
- Confirme que cada destino de asignación existe en el esquema de salida.
- Cree el conjunto de asignaciones.
- Actualice el flujo de datos con el conjunto de asignaciones.
Por ejemplo, para obtener la siguiente asignación que se muestra en la interfaz de usuario, debe seguir los pasos enumerados arriba y detallados en los siguientes encabezados.
firstName, lastName o Email, ya debe existir en el esquema de salida antes de crear el conjunto de asignación. Si falta un campo de destino de asignación en el esquema de salida, falla la solicitud del conjunto de asignaciones.Creación de un esquema de entrada create-input-schema
Para crear un esquema de entrada, primero debe recuperar su esquema de unión y las identidades que se pueden exportar al destino. Este es el esquema de atributos e identidades que puede seleccionar como asignación de origen.
Vea a continuación ejemplos de solicitudes y respuestas para recuperar atributos e identidades.
Solicitud para obtener atributos
| code language-shell |
|---|
|
Respuesta
La respuesta que aparece a continuación se ha abreviado para que sea más breve.
| code language-json |
|---|
|
Solicitud para obtener identidades
| code language-shell |
|---|
|
Respuesta
La respuesta devuelve las identidades que puede utilizar al crear el esquema de entrada. Tenga en cuenta que esta respuesta devuelve las áreas de nombres de identidad standard y custom que configuró en Experience Platform.
| code language-json |
|---|
|
A continuación, debe copiar la respuesta de arriba y utilizarla para crear el esquema de entrada. Puede copiar la respuesta JSON completa de la respuesta anterior y colocarla en el objeto jsonSchema indicado a continuación.
Solicitud para crear esquema de entrada
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
El ID de la respuesta representa el identificador único del esquema de entrada que ha creado. Copie el ID de la respuesta, ya que lo reutilizará en un paso posterior.
Creación de un esquema de salida create-output-schema
A continuación, debe configurar el esquema de salida para la exportación. En primer lugar, debe buscar e inspeccionar el esquema de socio existente.
Solicitud
Tenga en cuenta que el ejemplo siguiente utiliza connection spec ID para Amazon S3. Sustituya este valor por el ID de especificación de conexión específico de su destino.
| code language-shell |
|---|
|
Respuesta con un esquema de ejemplo
Inspeccione la respuesta que obtenga al realizar la llamada anterior. Debe explorar en profundidad la respuesta para encontrar el objeto targetSpec.attributes.partnerSchema.jsonSchema
| code language-json |
|---|
|
A continuación, debe crear un esquema de salida. Copie la respuesta JSON que obtuvo arriba y péguela en el objeto jsonSchema abajo.
El esquema del asociado sólo contiene estructuras genéricas, como attributes, identityMap y segmentMembership. Antes de crear el conjunto de asignaciones en el siguiente paso, agregue una propiedad al objeto jsonSchema para cada campo al que desee asignar. La API de asignación valida cada destino de asignación con el esquema de salida, por lo que un campo de destino de asignación que no existe en el esquema de salida hace que la solicitud del conjunto de asignación falle.
La solicitud y respuesta de ejemplo siguientes muestran las propiedades firstName, lastName, Email, personalEmail_address y segmentMembership_status que ya se han agregado al esquema de salida junto con las estructuras genéricas attributes, identityMap y segmentMembership del esquema del asociado. Estas propiedades coinciden con los destinos de asignación utilizados en el conjunto de asignación ejemplo más adelante en esta sección.
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
El ID de la respuesta representa el identificador único del esquema de salida que ha creado. Copie el ID de la respuesta, ya que lo reutilizará en un paso posterior.
Crear conjunto de asignaciones create-mapping-set
A continuación, utilice la API de preparación de datos para crear el conjunto de asignaciones mediante el ID de esquema de entrada, el ID de esquema de salida y las asignaciones de campo deseadas.
Solicitud
| note important |
|---|
| IMPORTANT |
|
Antes de crear el conjunto de asignaciones, compruebe lo siguiente:
- Todos los campos de destino de asignación, como
firstName,lastNameyEmail, ya existen en el esquema de salida. - Cada ruta de origen existe en el esquema de entrada.
- Las asignaciones de identidad utilizan áreas de nombres de identidad válidas.
- Los campos de pertenencia a segmentos, como
segmentMembership_status, se definen en el esquema de salida si se hace referencia a ellos en una asignación. - El esquema de entrada, el esquema de salida y el conjunto de asignaciones pertenecen al mismo entorno limitado.
| code language-shell line-numbers data-start-1 data-line-offset-4 h-16-42 |
|---|
|
Respuesta
| code language-json |
|---|
|
MAPPER-3101-400 que indica que la ruta XDM no es válida, uno o más de los valores de asignación destination no existen en el esquema de salida. Añada los campos que faltan al esquema de salida y reintente la solicitud del conjunto de asignaciones.Tenga en cuenta el ID del conjunto de asignaciones, ya que lo necesitará en el siguiente paso para actualizar el flujo de datos existente con el ID del conjunto de asignaciones.
A continuación, obtenga el ID del flujo de datos que desea actualizar.
Consulte recuperar los detalles de un flujo de datos de destino para obtener información sobre cómo recuperar el ID de un flujo de datos.
Finalmente, debe PATCH el flujo de datos con la información del conjunto de asignaciones que acaba de crear.
Solicitud
| code language-shell |
|---|
|
Respuesta
La respuesta de la API de Flow Service devuelve el ID del flujo de datos actualizado.
| code language-json |
|---|
|
Realización de otras actualizaciones del flujo de datos other-dataflow-updates
Para realizar actualizaciones en el flujo de datos, utilice la operación PATCH. Por ejemplo, puede agregar una acción de marketing a los flujos de datos, actualizar los flujos de datos para seleccionar campos como claves obligatorias o claves de anulación de duplicación, agregar atributos de enriquecimiento para audiencias de carga personalizadas o agregar la generación de manifiestos de archivo a destinos existentes.
Añadir una acción de marketing add-marketing-action
Para agregar una acción de marketing, vea los ejemplos de solicitud y respuesta que aparecen a continuación.
If-Match al realizar una solicitud PATCH. El valor de este encabezado es la versión única del flujo de datos que desea actualizar. El valor de la etiqueta se actualiza con cada actualización correcta de una entidad de flujo, como flujo de datos, conexión de destino y otras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, donde {ID} es el identificador de flujo de datos que desea actualizar.If-Match entre comillas dobles, como en los ejemplos siguientes, al realizar PATCH solicitudes.Solicitud
| code language-shell |
|---|
|
Respuesta
Una respuesta correcta devuelve el código de respuesta 200 junto con el ID del flujo de datos actualizado y la etiqueta electrónica actualizada.
| code language-json |
|---|
|
Añadir una clave obligatoria add-mandatory-key
Para agregar una clave obligatoria, vea los ejemplos de solicitud y respuesta que aparecen a continuación.
If-Match al realizar una solicitud PATCH. El valor de este encabezado es la versión única del flujo de datos que desea actualizar. El valor de la etiqueta se actualiza con cada actualización correcta de una entidad de flujo, como flujo de datos, conexión de destino y otras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, donde {ID} es el identificador de flujo de datos que desea actualizar.If-Match entre comillas dobles, como en los ejemplos siguientes, al realizar PATCH solicitudes.Solicitud
| code language-shell |
|---|
|
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Añadir una clave de anulación de duplicación add-deduplication-key
Para agregar una clave de anulación de duplicación, consulte los ejemplos de solicitud y respuesta que aparecen a continuación
If-Match al realizar una solicitud PATCH. El valor de este encabezado es la versión única del flujo de datos que desea actualizar. El valor de la etiqueta se actualiza con cada actualización correcta de una entidad de flujo, como flujo de datos, conexión de destino y otras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, donde {ID} es el identificador de flujo de datos que desea actualizar.If-Match entre comillas dobles, como en los ejemplos siguientes, al realizar PATCH solicitudes.Solicitud
| code language-shell |
|---|
|
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Agregar generación de manifiesto de archivo al destino existente add-file-manifest
Los archivos JSON de manifiesto contienen información sobre la ubicación de exportación, el tamaño de exportación, etc. Se ha asignado un nombre al manifiesto con el formato manifest-<<destinationId>>-<<dataflowRunId>>.json. Ver archivo de manifiesto de ejemplo. El archivo de manifiesto incluye los campos siguientes:
flowRunId: la ejecución de flujo de datos que generó el archivo exportado.scheduledTime: la hora en UTC en que se exportó el archivo.exportResults.sinkPath: ruta de acceso de la ubicación de almacenamiento en la que se deposita el archivo exportado.exportResults.name: nombre del archivo exportado.size: tamaño del archivo exportado, en bytes.
Para agregar la generación de manifiesto de archivo a un destino existente, debe actualizar los parámetros de conexión de destino mediante la operación PATCH. Esto permite la generación de archivos de manifiesto para el destino, que proporciona metadatos sobre los archivos exportados.
If-Match al realizar una solicitud PATCH. El valor de este encabezado es la versión única de la conexión de destino que desea actualizar. El valor de la etiqueta se actualiza con cada actualización correcta de una entidad de flujo, como flujo de datos, conexión de destino y otras.https://platform.adobe.io/data/foundation/flowservice/targetConnections/{ID}, donde {ID} es el identificador de conexión de destino que desea actualizar.If-Match entre comillas dobles, como en los ejemplos siguientes, al realizar PATCH solicitudes.Solicitud
| code language-shell |
|---|
|
Añadir atributos de enriquecimiento add-enrichment-attributes
Los atributos de enriquecimiento se aplican cuando activa las audiencias Carga personalizada, que son audiencias introducidas en Experience Platform como archivos CSV. Utilice este flujo de trabajo para seleccionar qué atributos de esas audiencias incluir en el archivo exportado.
El flujo de trabajo requiere dos fases: en primer lugar, crear un conjunto de asignaciones que defina qué atributos se exportan (pasos 1-2) y, a continuación, hacer referencia a ese conjunto de asignaciones al añadir la audiencia al flujo de datos (paso 3).
InvalidParameterException: "One deduplication key (i.e. primary field) must be specified when activating audiences with enrichment info".Paso 1: Recuperar el conjunto de datos y el esquema de carga útil enrichment-step1
Para cada audiencia que tenga habilitado el enriquecimiento, recupere su conjunto de datos de carga útil y esquema XDM asociados. Las propiedades de esquema se utilizan como esquema de entrada y salida al crear conjuntos de asignaciones.
Paso 1a: recuperar audiencias en lotes con metadatos de conjunto de datos de carga útil
Envíe los ID de audiencia que desee enriquecer al extremo de obtención masiva del servicio de segmentación.
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Observe el campo originName y el payloadDatasetId de la respuesta. Necesita ambos en los siguientes pasos.
Paso 1b: recupere el conjunto de datos de carga útil
Utilice el payloadDatasetId de la respuesta anterior para recuperar el conjunto de datos del servicio de catálogo.
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Extraiga el valor schemaRef.id. Lo necesita en el siguiente paso.
Paso 1c: Recupere el esquema XDM del Registro de esquemas
Utilice schemaRef.id de la respuesta del conjunto de datos para recuperar el esquema XDM completo. Codifique la dirección URL del ID de esquema al utilizarlo como parámetro de ruta.
Por ejemplo, https://ns.adobe.com/acme/schemas/88d84a32a53affb2ca9f63b12da6eb4f8eb721ea31db176 se convierte en https%3A%2F%2Fns.adobe.com%2Facme%2Fschemas%2F88d84a32a53affb2ca9f63b12da6eb4f8eb721ea31db176.
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Paso 1d: Extraiga el esquema JSON
El esquema JSON que utiliza en el paso 2a depende del tipo de audiencia, identificado por originName del paso 1a.
Para audiencias donde originName no es AUDIENCE_ORCHESTRATION, extraiga solo el subobjeto con espacio de nombres de inquilino en properties[meta:tenantNamespace] y combínelo con el subobjeto de nivel superior title. Descartar campos del sistema como _id y timestamp.
Ejemplo de esquema JSON extraído:
| code language-json |
|---|
|
Para audiencias donde originName es AUDIENCE_ORCHESTRATION, use el conjunto completo de propiedades de nivel superior de la respuesta del Registro de esquemas. Agregue meta:xdmType: "object" y type: "object" explícitamente. title siempre se toma de la respuesta del Registro de esquemas de nivel superior.
Ejemplo de esquema JSON extraído:
| code language-json |
|---|
|
La siguiente tabla resume el origen del esquema y los campos que se deben utilizar para cada tipo de audiencia.
originName no es AUDIENCE_ORCHESTRATIONproperties[meta:tenantNamespace]originName es AUDIENCE_ORCHESTRATIONpropertiesPaso 2: Creación del conjunto de asignaciones enrichment-step2
La creación de un conjunto de asignaciones es una secuencia de dos llamadas: registre el esquema JSON del paso 1d como esquema de conversión para obtener un ID de esquema y, a continuación, cree el conjunto de asignaciones que haga referencia a ese ID de esquema.
Paso 2a: crear el esquema de conversión
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Paso 2b: crear el conjunto de asignaciones
Usar {CONVERSION_SCHEMA_ID} de la respuesta anterior como inputSchema.id y outputSchema.id. Cada clave de propiedad del esquema es source y destination. sourceType siempre debe ser text/x.schema-path.
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Almacene los valores id y version devueltos. Estos son los mappingSet.id y mappingSet.version a los que hace referencia en el siguiente paso.
Paso 3: Añadir atributos de enriquecimiento al flujo de datos enrichment-step3
Con el conjunto de asignaciones creado, utilice una solicitud PATCH para agregar la audiencia con su configuración de enriquecimiento al flujo de datos.
If-Match al realizar una solicitud PATCH. El valor de este encabezado es la versión única del flujo de datos que desea actualizar. El valor de la etiqueta se actualiza con cada actualización correcta de una entidad de flujo, como flujo de datos, conexión de destino y otras.https://platform.adobe.io/data/foundation/flowservice/flows/{ID}, donde {ID} es el identificador de flujo de datos que desea actualizar.If-Match entre comillas dobles, como en los ejemplos siguientes, al realizar PATCH solicitudes.Solicitud
| code language-shell |
|---|
|
El objeto enrichmentInfo tiene las siguientes propiedades:
enabledsourceTypeAUDIENCE_DATASET.mappingSet.idmappingSet.versionUna vez ejecutado el flujo, los atributos de enriquecimiento resueltos están disponibles en la plantilla de exportación en:
destination.enrichmentAttributes.{namespace}.{segmentId}
enrichmentInfo.enabled en false para todas las audiencias. En este caso, no se requieren conjuntos de asignaciones.Validar flujo de datos (obtener las ejecuciones del flujo de datos) get-dataflow-runs
Para comprobar las ejecuciones de un flujo de datos, utilice la API de ejecución de flujo de datos:
Solicitud
| code language-shell |
|---|
|
Respuesta
| code language-json |
|---|
|
Puede encontrar información sobre los diversos parámetros devueltos por el flujo de datos ejecuta la API en la documentación de referencia de la API.
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 de 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 Experience Platform para obtener más información sobre cómo interpretar las respuestas de error.
Próximos pasos next-steps
Se ha conectado correctamente Experience Platform a uno de los destinos de almacenamiento en la nube preferidos y se ha configurado un flujo de datos en el destino respectivo para exportar audiencias. Consulte las siguientes páginas para obtener más información, como cómo editar flujos de datos existentes mediante la API de Flow Service: