Crear un flujo de datos para orígenes de almacenamiento en la nube mediante la API Flow Service

Última actualización: 22 de octubre de 2025
  • Temas:

Creado para:

  • Desarrollador

Este tutorial trata los pasos para recuperar datos de una fuente de almacenamiento en la nube y llevarlos a Experience Platform mediante Flow Service API.

NOTA
Para crear un flujo de datos, ya debe tener un ID de conexión base válido con un origen de almacenamiento en la nube. Si no tiene este identificador, consulte la descripción general de orígenes para obtener una lista de orígenes de almacenamiento en la nube con los que puede crear una conexión base.

Introducción

Este tutorial 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.

    • Aspectos básicos de la composición de esquemas: obtenga información sobre los componentes básicos de los esquemas XDM, incluidos los principios clave y las prácticas recomendadas en la composición de esquemas.
    • Guía para desarrolladores de Schema Registry: Incluye información importante que necesita conocer para realizar correctamente llamadas a la API de Schema Registry. Esto incluye su {TENANT_ID}, el concepto de "contenedores" y los encabezados necesarios para realizar solicitudes (con especial atención al encabezado Aceptar y sus posibles valores).

  • Catalog Service: el catálogo es el sistema de registro para la ubicación y el linaje de datos dentro de Experience Platform.

  • Batch ingestion: la API de ingesta por lotes le permite ingerir datos en Experience Platform como archivos por lotes.

  • Zonas protegidas: 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.

Uso de API de Experience Platform

Para obtener información sobre cómo realizar llamadas correctamente a las API de Experience Platform, consulte la guía sobre introducción a las API de Experience Platform.

Crear una conexión de origen

Puede crear una conexión de origen realizando una petición POST al extremo sourceConnections de la API Flow Service al mismo tiempo que proporciona el identificador de conexión base, la ruta de acceso al archivo de origen que desea introducir y el identificador de especificación de conexión correspondiente del origen.

Al 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 datosValor de enumeración
Delimitadodelimited
JSONjson
Parquetparquet

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

Formato de API

POST /sourceConnections

Solicitud

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -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": "Cloud Storage source connection",
      "description: "Source connection for a cloud storage source",
      "baseConnectionId": "1f164d1b-debe-4b39-b4a9-df767f7d6f7c",
      "data": {
          "format": "delimited",
          "properties": {
              "columnDelimiter": "{COLUMN_DELIMITER}",
              "encoding": "{ENCODING}",
              "compressionType": "{COMPRESSION_TYPE}"
          }
      },
      "params": {
          "path": "/acme/summerCampaign/account.csv",
          "type": "file",
          "cdcEnabled": true
      },
      "connectionSpec": {
          "id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
          "version": "1.0"
      }
  }'
PropiedadDescripción
baseConnectionIdEl ID de conexión base del origen de almacenamiento en la nube.
data.formatEl formato de los datos que desea llevar a Experience Platform. Los valores admitidos son: delimited, JSON y parquet.
data.properties(Opcional) Conjunto de propiedades que se pueden aplicar a los datos al crear una conexión de origen.
data.properties.columnDelimiter(Opcional) Un delimitador de columna de un solo carácter que puede especificar al recopilar archivos planos. Cualquier valor de carácter único es un delimitador de columna admisible. Si no se proporciona, se usa una coma (,) como valor predeterminado. Nota: la propiedad columnDelimiter solo se puede usar al ingerir archivos delimitados.
data.properties.encoding(Opcional) Una propiedad que define el tipo de codificación que se utilizará al ingerir los datos en Experience Platform. Los tipos de codificación admitidos son: UTF-8 y ISO-8859-1. Nota: el parámetro encoding solo está disponible cuando se ingieren archivos CSV delimitados. Se incorporarán otros tipos de archivo con la codificación predeterminada, UTF-8.
data.properties.compressionType(Opcional) Una propiedad que define el tipo de archivo comprimido para la ingesta. Los tipos de archivo comprimidos admitidos son: bzip2, gzip, deflate, zipDeflate, tarGzip y tar. Nota: la propiedad compressionType solo se puede usar al ingerir archivos delimitados o JSON.
params.pathLa ruta del archivo de origen al que está accediendo. Este parámetro apunta a un archivo individual o a una carpeta completa. Nota: puede usar un asterisco en lugar del nombre de archivo para especificar la ingesta de una carpeta entera. Por ejemplo: /acme/summerCampaign/*.csv ingerirá toda la carpeta /acme/summerCampaign/.
params.typeEl tipo de archivo del archivo de datos de origen que está ingiriendo. Use el tipo file para ingerir un archivo individual y el tipo folder para ingerir una carpeta completa.
params.cdcEnabled

Un valor booleano que indica si la captura del historial de cambios está habilitada. Cuando se utiliza con esquemas relacionales, la captura de datos modificados se basa en la columna de control _change_request_type (u — actualizar, d — eliminar), que se evalúa durante la ingesta pero no se almacena en el esquema de destino. Estas fuentes de almacenamiento en la nube admiten esta propiedad:

  • Azure Blob
  • Data Landing Zone
  • Google Cloud Storage
  • SFTP

Para obtener una descripción general de esta capacidad, consulte Descripción general de Data Mirror. Para obtener información detallada sobre la implementación, lea la guía sobre el uso de cambiar la captura de datos en las fuentes y la referencia técnica de esquemas relacionales.

connectionSpec.idEl ID de especificación de conexión asociado con el origen de almacenamiento en la nube específico. Consulte el apéndice para obtener una lista de los ID de especificación de conexión.

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": "26b53912-1005-49f0-b539-12100559f0e2",
    "etag": "\"11004d97-0000-0200-0000-5f3c3b140000\""
}

Utilice expresiones regulares para seleccionar un conjunto específico de archivos para la ingesta

Puede utilizar expresiones regulares para introducir un conjunto concreto de archivos del origen a Experience Platform al crear una conexión de origen.

Formato de API

POST /sourceConnections

Solicitud

En el ejemplo siguiente, se utiliza una expresión regular en la ruta de acceso del archivo para especificar la ingesta de todos los archivos CSV que tienen premium en su nombre.

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -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": "Cloud Storage source connection",
      "description: "Source connection for a cloud storage source",
      "baseConnectionId": "1f164d1b-debe-4b39-b4a9-df767f7d6f7c",
      "data": {
          "format": "delimited"
      },
      "params": {
          "path": "/acme/summerCampaign/*premium*.csv",
          "type": "folder"
      },
      "connectionSpec": {
          "id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
          "version": "1.0"
      }
  }'

Configurar una conexión de origen para introducir datos de forma recursiva

Al crear una conexión de origen, puede utilizar el parámetro recursive para introducir datos de carpetas anidadas profundamente.

Formato de API

POST /sourceConnections

Solicitud

En el ejemplo siguiente, el parámetro recursive: true indica a Flow Service que lea todas las subcarpetas de forma recursiva durante el proceso de ingesta.

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -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": "Cloud Storage source connection",
      "description: "Source connection for a cloud storage source with recursive ingestion",
      "baseConnectionId": "1f164d1b-debe-4b39-b4a9-df767f7d6f7c",
      "data": {
          "format": "delimited"
      },
      "params": {
          "path": "/acme/summerCampaign/customers/premium/buyers/recursive",
          "type": "folder",
          "recursive": true
      },
      "connectionSpec": {
          "id": "4c10e202-c428-4796-9208-5f1f5732b1cf",
          "version": "1.0"
      }
  }'

Creación de un esquema XDM de destino

Para que los datos de origen se utilicen en Experience 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 Experience Platform en el que se incluyen los datos de origen.

Se puede crear un esquema XDM de destino realizando una petición POST a la API del 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

Se puede crear un conjunto de datos de destino realizando una petición POST en la API del 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

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 ID de especificación de conexión fija asociado al lago de datos. Este id. de especificación de conexión es: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Ahora tiene los identificadores únicos de un esquema de destino, un conjunto de datos de destino y el ID de especificación de conexión al lago de datos. Con estos identificadores, puede crear una conexión de destino utilizando la API Flow Service para especificar el conjunto de datos que contendrá los datos de origen entrantes.

Formato de API

POST /targetConnections

Solicitud

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "name": "Target Connection for a Cloud Storage connector",
        "description": "Target Connection for a Cloud Storage connector",
        "data": {
            "schema": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
                "version": "application/vnd.adobe.xed-full+json;version=1"
            }
        },
        "params": {
            "dataSetId": "5f3c3cedb2805c194ff0b69a"
        },
            "connectionSpec": {
            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
            "version": "1.0"
        }
    }'
PropiedadDescripción
data.schema.idEl $id del esquema XDM de destino.
data.schema.versionLa versión del esquema. Este valor debe establecerse application/vnd.adobe.xed-full+json;version=1, que devuelve la última versión secundaria del esquema.
params.dataSetIdEl ID del conjunto de datos de destinatario generado en el paso anterior. Nota: debe proporcionar un identificador de conjunto de datos válido al crear una conexión de destino. Si la ID del conjunto de datos no es válida, se producirá un error.
connectionSpec.idID de especificación de conexión utilizado para conectarse al lago de datos. Este identificador es: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Respuesta

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

{
    "id": "dbc5c132-bc2a-4625-85c1-32bc2a262558",
    "etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}

Creación de una asignación

Para que los datos de origen se incorporen en un conjunto de datos de destino, primero deben asignarse al esquema de destino al que se adhiere el conjunto de datos de destino.

Para crear un conjunto de asignaciones, realice una petición POST al extremo mappingSets de la Data Prep API y proporcione el esquema XDM de destino $id y los detalles de los conjuntos de asignaciones que desee crear.

CONSEJO
Puede asignar tipos de datos complejos, como matrices en archivos JSON, mediante un conector de origen de almacenamiento en la nube.

Formato de API

POST /conversion/mappingSets

Solicitud

curl -X POST \
    'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}' \
    -H 'Content-Type: application/json' \
    -d '{
        "version": 0,
        "xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
        "xdmVersion": "1.0",
        "id": null,
        "mappings": [
            {
                "destinationXdmPath": "_id",
                "sourceAttribute": "Id",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "person.name.firstName",
                "sourceAttribute": "FirstName",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "person.name.lastName",
                "sourceAttribute": "LastName",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            }
        ]
    }'
PropiedadDescripción
xdmSchemaID del esquema XDM de destino.

Respuesta

Una respuesta correcta devuelve detalles de la asignación recién creada, incluido su identificador único (id). Este valor es necesario en un paso posterior para crear un flujo de datos.

{
    "id": "bf5286a9c1ad4266baca76ba3adc9366",
    "version": 0,
    "createdDate": 1597784069368,
    "modifiedDate": 1597784069368,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}