Connect Data Landing Zone a Adobe Experience Platform mediante la API de servicio de flujo

Data Landing Zone es una funcionalidad de almacenamiento de datos basada en la nube para el almacenamiento temporal de archivos aprovisionado con Adobe Experience Platform. Los datos se eliminan automáticamente del Data Landing Zone después de siete días.

Este tutorial le guía por los pasos para crear un Data Landing Zone conexión de origen utilizando la variable Flow Service API. Este tutorial también proporciona instrucciones sobre cómo recuperar su Data Landing Zone, así como ver y actualizar sus credenciales.

Primeros pasos

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

  • Fuentes: Experience Platform permite la ingesta de datos de varias fuentes, al mismo tiempo que le ofrece la capacidad de estructurar, etiquetar y mejorar los datos entrantes mediante los servicios de Platform.
  • Sandboxes: Experience Platform proporciona entornos limitados virtuales que dividen una sola instancia de Platform en entornos virtuales independientes para ayudar a desarrollar y desarrollar aplicaciones de experiencia digital.

Las secciones siguientes proporcionan información adicional que debe conocer para crear correctamente un Data Landing Zone conexión de origen utilizando la variable Flow Service API.

Este tutorial también requiere que lea la guía de introducción a las API de Platform para aprender a autenticarse en las API de Platform e interpretar las llamadas de ejemplo que se proporcionan en la documentación.

Recuperar una zona de aterrizaje utilizable

El primer paso en el uso de API para acceder a Data Landing Zone es realizar una solicitud de GET a la /landingzone punto final del Connectors API mientras proporciona type=user_drop_zone como parte del encabezado de la solicitud.

Formato de API

GET /connectors/landingzone?type=user_drop_zone
Encabezados Descripción
user_drop_zone La variable user_drop_zone permite que la API distinga un contenedor de zona de aterrizaje de los demás tipos de contenedores disponibles.

Solicitud

La siguiente solicitud recupera una zona de aterrizaje existente.

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
  -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'

Respuesta

La siguiente respuesta devuelve información sobre una zona de aterrizaje, incluida su correspondiente containerName y containerTTL.

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}
Propiedad Descripción
containerName Nombre de la zona de aterrizaje que recuperó.
containerTTL La configuración de tiempo de vida aplicada a sus datos dentro de la zona de aterrizaje. Cualquier valor de una zona de aterrizaje determinada se elimina al cabo de siete días.

Recuperar Data Landing Zone credenciales

Para recuperar credenciales para un Data Landing Zone, realice una solicitud de GET a la /credentials punto final del Connectors API.

Formato de API

GET /connectors/landingzone/credentials?type=user_drop_zone

Solicitud

El siguiente ejemplo de solicitud recupera las credenciales de una zona de aterrizaje existente.

curl -X GET \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
  -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' \

Respuesta

La siguiente respuesta devuelve la información de credenciales de su zona de aterrizaje, incluida la SASToken y SASUri, así como el storageAccountName que corresponde al contenedor de su zona de aterrizaje.

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D"
}
Propiedad Descripción
containerName Nombre de la zona de aterrizaje.
SASToken Token de firma de acceso compartido para su zona de aterrizaje. Esta cadena contiene toda la información necesaria para autorizar una solicitud.
SASUri El URI de firma de acceso compartido para su zona de aterrizaje. Esta cadena es una combinación de la URI con la zona de aterrizaje a la que se está autenticando y su token SAS correspondiente,

Actualizar Data Landing Zone credenciales

Puede actualizar su SASToken realizando una solicitud de POST al /credentials punto final del Connectors API.

Formato de API

POST /connectors/landingzone/credentials?type=user_drop_zone&action=refresh
Encabezados Descripción
user_drop_zone La variable user_drop_zone permite que la API distinga un contenedor de zona de aterrizaje de los demás tipos de contenedores disponibles.
refresh La variable refresh la acción le permite restablecer las credenciales de la zona de aterrizaje y generar automáticamente una nueva SASToken.

Solicitud

La siguiente solicitud actualiza las credenciales de la zona de aterrizaje.

curl -X POST \
  'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
  -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' \

Respuesta

La siguiente respuesta devuelve valores actualizados para su SASToken y SASUri.

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D"
}

Explorar la estructura y el contenido del archivo de la zona de aterrizaje

Puede explorar la estructura de archivos y el contenido de su zona de aterrizaje realizando una solicitud de GET al connectionSpecs punto final del Flow Service API.

Formato de API

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
Parámetro Descripción
{CONNECTION_SPEC_ID} El ID de especificación de conexión correspondiente a Data Landing Zone. Este ID fijo es: 26f526f2-58f4-4712-961d-e41bf1ccc0e8.

Solicitud

curl -X GET \
    'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Respuesta

Una respuesta correcta devuelve una matriz de archivos y carpetas que se encuentran en el directorio consultado. Tome nota de la path del archivo que desea cargar, tal como debe proporcionarlo en el siguiente paso para inspeccionar su estructura.

[
    {
        "type": "file",
        "name": "account.csv",
        "path": "dlz-user-container/account.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "file",
        "name": "data8.csv",
        "path": "dlz-user-container/data8.csv",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "folder",
        "name": "userdata1",
        "path": "dlz-user-container/userdata1/",
        "canPreview": false,
        "canFetchSchema": false
    }
]

Vista previa de la estructura y el contenido del archivo de la zona de aterrizaje

Para inspeccionar la estructura de un archivo en la zona de aterrizaje, realice una solicitud de GET y proporcione la ruta del archivo y escriba como parámetro de consulta.

Formato de API

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
Parámetro Descripción Ejemplo
{CONNECTION_SPEC_ID} El ID de especificación de conexión correspondiente a Data Landing Zone. Este ID fijo es: 26f526f2-58f4-4712-961d-e41bf1ccc0e8.
{OBJECT_TYPE} Tipo del objeto al que desea acceder. file
{OBJECT} Ruta y nombre del objeto al que desea acceder. dlz-user-container/data8.csv
{FILE_TYPE} Tipo de archivo.
  • delimited
  • json
  • parquet
{PREVIEW} Un valor booleano que define si se admite la previsualización de archivos.
  • true
  • false
  • Solicitud

    curl -X GET \
        'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'x-api-key: {API_KEY}' \
        -H 'x-gw-ims-org-id: {ORG_ID}' \
        -H 'x-sandbox-name: {SANDBOX_NAME}'
    

    Respuesta

    Una respuesta correcta devuelve la estructura del archivo consultado, incluidos los nombres de archivo y los tipos de datos.

    {
        "format": "flat",
        "schema": {
            "columns": [
                {
                    "name": "Id",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "FirstName",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "LastName",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "Email",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "Phone",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                }
            ]
        },
        "data": [
            {
                "Email": "rsmith@abc.com",
                "FirstName": "Richard",
                "Phone": "111111111",
                "Id": "12345",
                "LastName": "Smith"
            },
            {
                "Email": "morgan@bac.com",
                "FirstName": "Morgan",
                "Phone": "22222222222",
                "Id": "67890",
                "LastName": "Hart"
            }
        ]
    }
    

    Uso determineProperties para detectar automáticamente la información de propiedad de un archivo de Data Landing Zone

    Puede usar la variable determineProperties para detectar automáticamente la información de propiedad del contenido del archivo de Data Landing Zone cuando realice una llamada de GET para explorar el contenido y la estructura del origen.

    determineProperties casos de uso

    La siguiente tabla describe los distintos escenarios que puede encontrar al usar la variable determineProperties parámetro de consulta o proporcione manualmente información sobre el archivo.

    determineProperties queryParams Respuesta
    True N/A If determineProperties se proporciona como parámetro de consulta, se produce la detección de las propiedades del archivo y la respuesta devuelve un nuevo valor properties clave que incluye información sobre el tipo de archivo, el tipo de compresión y el delimitador de columna.
    N/D True Si los valores para el tipo de archivo, el tipo de compresión y el delimitador de columna se proporcionan manualmente como parte de queryParams, se utilizan para generar el esquema y se devuelven las mismas propiedades como parte de la respuesta.
    True True Si ambas opciones se realizan simultáneamente, se devuelve un error.
    N/D N/D Si no se proporciona ninguna de las dos opciones, se devuelve un error porque no hay forma de obtener propiedades para la respuesta.

    Formato de API

    GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
    
    Parámetro Descripción Ejemplo
    determineProperties Este parámetro de consulta permite que Flow Service API para detectar información sobre las propiedades del archivo, incluida información sobre el tipo de archivo, el tipo de compresión y el delimitador de columna. true

    Solicitud

    curl -X GET \
        'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
        -H 'Authorization: Bearer {ACCESS_TOKEN}' \
        -H 'x-api-key: {API_KEY}' \
        -H 'x-gw-ims-org-id: {ORG_ID}' \
        -H 'x-sandbox-name: {SANDBOX_NAME}'
    

    Respuesta

    Una respuesta correcta devuelve la estructura del archivo consultado, incluidos los nombres de archivo y los tipos de datos, así como un properties clave que contiene información sobre fileType, compressionTypey columnDelimiter.

     Clic en mí
    {
        "properties": {
            "fileType": "delimited",
            "compressionType": "tarGzip",
            "columnDelimiter": "~"
        },
        "format": "flat",
        "schema": {
            "columns": [
                {
                    "name": "id",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "firstName",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "lastName",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "email",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                },
                {
                    "name": "birthday",
                    "type": "string",
                    "xdm": {
                        "type": "string"
                    }
                }
            ]
        },
        "data": [
            {
                "birthday": "1313-0505-19731973",
                "firstName": "Yvonne",
                "lastName": "Thilda",
                "id": "100",
                "email": "Yvonne.Thilda@yopmail.com"
            },
            {
                "birthday": "1515-1212-19731973",
                "firstName": "Mary",
                "lastName": "Pillsbury",
                "id": "101",
                "email": "Mary.Pillsbury@yopmail.com"
            },
            {
                "birthday": "0505-1010-19751975",
                "firstName": "Corene",
                "lastName": "Joeann",
                "id": "102",
                "email": "Corene.Joeann@yopmail.com"
            },
            {
                "birthday": "2727-0303-19901990",
                "firstName": "Dari",
                "lastName": "Greenwald",
                "id": "103",
                "email": "Dari.Greenwald@yopmail.com"
            },
            {
                "birthday": "1717-0404-19651965",
                "firstName": "Lucy",
                "lastName": "Magdalen",
                "id": "199",
                "email": "Lucy.Magdalen@yopmail.com"
            }
        ]
    }
    
    Propiedad Descripción
    properties.fileType El tipo de archivo correspondiente del archivo consultado. Los tipos de archivo admitidos son: delimited, jsony parquet.
    properties.compressionType El tipo de compresión correspondiente utilizado para el archivo consultado. Los tipos de compresión admitidos son:
    • bzip2
    • gzip
    • zipDeflate
    • tarGzip
    • tar
    properties.columnDelimiter El delimitador de columna correspondiente utilizado para el archivo consultado. Cualquier valor de carácter único es un delimitador de columna permitido. El valor predeterminado es una coma (,).

    Crear una conexión de origen

    Una conexión de origen crea y administra la conexión con el origen externo desde el que se introducen los datos. Una conexión de origen consiste en información como el origen de datos, el formato de datos y el ID de conexión de origen necesario para crear un flujo de datos. Una instancia de conexión de origen es específica para un inquilino y una organización IMS.

    Para crear una conexión de origen, realice una solicitud de POST al /sourceConnections punto final del Flow Service API.

    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": "Data Landing Zone source connection",
            "data": {
                "format": "delimited"
            },
            "params": {
                "path": "dlz-user-container/data8.csv"
            },
            "connectionSpec": {
                "id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
                "version": "1.0"
            }
        }'
    
    Propiedad Descripción
    name El nombre de su Data Landing Zone conexión de origen.
    data.format El formato de los datos que desea traer a Platform.
    params.path La ruta al archivo que desea traer a Platform.
    connectionSpec.id El ID de especificación de conexión correspondiente a Data Landing Zone. Este ID fijo es: 26f526f2-58f4-4712-961d-e41bf1ccc0e8.

    Respuesta

    Una respuesta correcta devuelve el identificador único (id) de la conexión de origen recién creada. Este ID es necesario en el siguiente tutorial para crear un flujo de datos.

    {
        "id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
        "etag": "\"1400d460-0000-0200-0000-613be3520000\""
    }
    

    Pasos siguientes

    Al seguir este tutorial, ha recuperado su Data Landing Zone credenciales, exploró su estructura de archivos para encontrar el archivo que desea traer a Platform y creó una conexión de origen para comenzar a llevar los datos a Platform. Ahora puede continuar con el siguiente tutorial, en el que aprenderá a cree un flujo de datos para llevar los datos de almacenamiento en la nube a Platform mediante el Flow Service API.

    En esta página