Desarrollo de integraciones de ETL para Adobe Experience Platform

La guía de integración de ETL describe los pasos generales para crear conectores seguros y de alto rendimiento para Experience Platform e ingesta de datos en Platform.

Esta guía también incluye ejemplos de llamadas a la API para utilizar al diseñar un conector de ETL, con vínculos a documentación que describe cada Experience Platform y uso de su API, en más detalle.

A sample integration is available on GitHub via the ETL Ecosystem Integration Reference Code under the Apache License Version 2.0.

Flujo de trabajo

The following workflow diagram provides a high-level overview for the integration of Adobe Experience Platform components with an ETL application and connector.

Componentes de Adobe Experience Platform

Hay varios componentes de Experience Platform involucrados en las integraciones de conectores de ETL. La siguiente lista describe varios componentes y funcionalidades clave:

  • Sistema Identity Management de Adobe (IMS) : proporciona un marco para la autenticación en los servicios de Adobe.
  • Organización IMS - Una entidad corporativa que puede poseer o licenciar productos y servicios y permitir el acceso a sus miembros.
  • Usuario IMS - Miembros de una organización IMS. La relación entre Organización y Usuario es de varios a muchos.
  • Sandbox - A virtual partition a single Platform instance, to help develop and evolve digital experience applications.
  • Data Discovery - Records the metadata of ingested and transformed data in Experience Platform.
  • Data Access : proporciona a los usuarios una interfaz para acceder a sus datos en Experience Platform.
  • Data Ingestion – Pushes data to Experience Platform with Data Ingestion APIs.
  • Schema Registry - Defines and stores schema that describe the structure of data to be used in Experience Platform.

Introducción a Experience Platform API

Las secciones siguientes proporcionan información adicional que debe conocer o tener disponible para realizar llamadas a Experience Platform API.

Leer llamadas de API de ejemplo

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

Recopilar valores para encabezados necesarios

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

  • Autorización: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Todos los recursos de Experience Platform están aisladas para entornos limitados virtuales específicos. Todas las solicitudes a Platform Las API requieren un encabezado que especifique el nombre del simulador para pruebas en el que se realizará la operación:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Para obtener más información sobre los entornos limitados en Platform, consulte la documentación general de entorno limitado.

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

  • Content-Type: application/json

Flujo de usuario general

Para empezar, un usuario de ETL inicia sesión en el Experience Platform interfaz de usuario (IU) y crea conjuntos de datos para la ingesta mediante un conector estándar o un conector de servicio push.

En la interfaz de usuario, el usuario crea el conjunto de datos de salida seleccionando un esquema de conjunto de datos. La elección del esquema depende del tipo de datos (registro o serie temporal) que se incorporen en Platform. Al hacer clic en la pestaña Esquemas de la interfaz de usuario, el usuario podrá ver todos los esquemas disponibles, incluido el tipo de comportamiento que admite el esquema.

En la herramienta ETL, el usuario empezará a diseñar sus transformaciones de asignación después de configurar la conexión adecuada (con sus credenciales). Se supone que la herramienta ETL ya tiene Experience Platform conectores instalados (proceso no definido en esta Guía de integración).

Se han proporcionado en la sección Flujo de trabajo de ETL. Aunque las herramientas de ETL pueden tener un formato diferente, la mayoría exponen funcionalidades similares.

NOTA

El conector ETL debe especificar un filtro de marca de hora que marque la fecha de entrada de datos y desplazamiento (es decir, la ventana para la que se deben leer los datos). La herramienta ETL debe admitir la toma de estos dos parámetros en esta u otra interfaz de usuario relevante. En Adobe Experience Platform, estos parámetros se asignarán a fechas disponibles (si están presentes) o a fechas capturadas presentes en el objeto por lotes del conjunto de datos.

Ver lista de conjuntos de datos

Si se utiliza el origen de los datos para la asignación, se puede obtener una lista de todos los conjuntos de datos disponibles mediante la variable Catalog API.

Puede enviar una única solicitud de API para ver todos los conjuntos de datos disponibles (p. ej. GET /dataSets), siendo recomendable incluir parámetros de consulta que limiten el tamaño de la respuesta.

En los casos en los que se solicita información completa del conjunto de datos, la carga útil de respuesta puede superar los 3 GB de tamaño, lo que puede ralentizar el rendimiento general. Por lo tanto, el uso de parámetros de consulta para filtrar solo la información necesaria hará que Catalog consulta más eficaz.

Filtrado de listas

Al filtrar respuestas, puede utilizar varios filtros en una sola llamada separando parámetros con un signo & (&). Algunos parámetros de consulta aceptan listas de valores separados por comas, como el filtro "propiedades" en la solicitud de ejemplo siguiente.

Catalog las respuestas se miden automáticamente según los límites configurados, sin embargo, el parámetro de consulta "limit" puede utilizarse para personalizar las restricciones y limitar el número de objetos devueltos. El Catalog los límites de respuesta son:

  • Si no se especifica un parámetro de límite, el número máximo de objetos por carga útil de respuesta es de 20.
  • El límite global para el resto Catalog las consultas son 100 objetos.
  • Para consultas de conjuntos de datos, si observableSchema se solicita utilizando el parámetro de consulta de propiedades, el número máximo de conjuntos de datos devueltos es 20.
  • Parámetros de límite no válidos (incluidos limit=0) se encuentran con un error HTTP 400 que describe los intervalos adecuados.
  • Si los límites o desplazamientos se pasan como parámetros de consulta, tienen prioridad sobre los que se pasan como encabezados.

Los parámetros de consulta se tratan con más detalle en la sección Información general del servicio de catálogo.

Formato de API

GET /catalog/dataSets
GET /catalog/dataSets?{filter1}={value1},{value2}&{filter2}={value3}

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3&properties=name,description,schemaRef" \
  -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}"

Consulte la Información general del servicio de catálogo para ver ejemplos detallados de cómo realizar llamadas a la variable Catalog API.

Respuesta

La respuesta incluye tres (limit=3) conjuntos de datos que muestran "name", "description" y "schemaRef" como se indica en la properties parámetro de consulta.

{
    "5b95b155419ec801e6eee780": {
        "name": "Store Transactions",
        "description": "Retails Store Transactions",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c351fa2f5fee300000fa9e8": {
        "name": "Loyalty Members",
        "description": "Loyalty Program Members",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c1823b19e6f400000993885": {
        "name": "Web Traffic",
        "description": "Retail Web Traffic",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/2025a705890c6d4a4a06b16f8cf6f4ca",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Ver esquema del conjunto de datos

La propiedad "schemaRef" de un conjunto de datos contiene una URI que hace referencia al esquema XDM en el que se basa el conjunto de datos. The XDM schema ("schemaRef") represents all potential fields that could be used by the dataset, not necessarily the fields that are being used (see "observableSchema" below).

El esquema XDM es el esquema que se utiliza cuando se necesita presentar al usuario una lista de todos los campos disponibles en los que se puede escribir.

The first "schemaRef.id" value in the previous response object (https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18) is a URI that points to a specific XDM schema in the Schema Registry. The schema can be retrieved by making a lookup (GET) request to the Schema Registry API.

NOTA

La propiedad "schemaRef" reemplaza la propiedad ahora obsoleta "schema" . If "schemaRef" is absent from the dataset or does not contain a value, you will need to check for the presence of a "schema" property. This could be done by replacing "schemaRef" with "schema" in the properties query parameter in the previous call. More details on the "schema" property are available in the Dataset "schema" Property section that follows.

Formato de API

GET /schemaregistry/tenant/schemas/{url encoded schemaRef.id}

Solicitud

La solicitud utiliza la dirección URL codificada id URI del esquema (el valor del atributo "schemaRef.id") y requiere un encabezado Accept .

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F274f17bc5807ff307a046bab1489fb18 \
  -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 'Accept: application/vnd.adobe.xed-full+json; version=1' \

The response format depends on the type of Accept header sent in the request. Las solicitudes de búsqueda también requieren un version se incluya en el encabezado Accept . La siguiente tabla describe los encabezados Accept disponibles para las búsquedas:

Accept Descripción
application/vnd.adobe.xed-id+json Enumerar solicitudes, títulos, id y versiones (GET)
application/vnd.adobe.xed-full+json; version={major version} $refs y allOf resueltos, tiene títulos y descripciones
application/vnd.adobe.xed+json; version={major version} Sin procesar con $ref y allOf, tiene títulos y descripciones
application/vnd.adobe.xed-notext+json; version={major version} Sin procesar con $ref y todoOf, sin títulos ni descripciones
application/vnd.adobe.xed-full-notext+json; version={major version} $refs y allOf resueltos, sin títulos ni descripciones
application/vnd.adobe.xed-full-desc+json; version={major version} $refs y allOf resueltos, se incluyen los descriptores
NOTA

application/vnd.adobe.xed-id+json y application/vnd.adobe.xed-full+json; version={major version} son los encabezados Accept más utilizados. application/vnd.adobe.xed-id+json es preferible para listar recursos en la variable Schema Registry ya que solo devuelve "title", "id" y "version". application/vnd.adobe.xed-full+json; version={major version} es preferible para ver un recurso específico (por su "id"), ya que devuelve todos los campos (anidados en "propiedades"), así como los títulos y las descripciones.

Respuesta

El esquema JSON que se devuelve describe la información de nivel de estructura y campo ("type", "format", "Minimum", "maximum", etc.) de los datos, serializados como JSON. Si se utiliza un formato de serialización distinto de JSON para la ingesta (como Parquet o Scala), la variable Guía del Registro de Esquemas contiene una tabla que muestra el tipo JSON deseado ("meta:xdmType") y su representación correspondiente en otros formatos.

Junto con esta tabla, la variable Schema Registry La guía para desarrolladores contiene ejemplos detallados de todas las posibles llamadas que se pueden realizar mediante el Schema Registry API.

Propiedad "schema" del conjunto de datos (OBSOLETO - EOL 2019-05-30)

Los conjuntos de datos pueden contener una propiedad "schema" que ahora está obsoleta y permanece disponible temporalmente para la compatibilidad con versiones anteriores. Por ejemplo, una solicitud de lista (GET) similar a la realizada anteriormente, donde "schema" se sustituyó por "schemaRef" en la variable properties , puede devolver lo siguiente:

{
  "5ba9452f7de80400007fc52a": {
    "name": "Sample Dataset 1",
    "description": "Description of Sample Dataset 1.",
    "schema": "@/xdms/context/person"
  }
}

Si la propiedad "schema" de un conjunto de datos se rellena, esto indica que el esquema está en desuso /xdms y, cuando se admita, el conector ETL debe utilizar el valor de la propiedad "schema" con la variable /xdms punto final (un punto final obsoleto en la variable Catalog API) para recuperar el esquema heredado.

Formato de API

GET /catalog/{"schema" property without the "@"}

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/xdms/context/person?expansion=xdm" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
NOTA

Un parámetro de consulta opcional, expansion=xdm, indica a la API que amplíe y en línea todos los esquemas a los que se hace referencia. Puede que desee hacerlo al presentar una lista de todos los campos posibles al usuario.

Respuesta

Similar a los pasos para visualización del esquema del conjunto de datos, la respuesta contiene un esquema JSON que describe la estructura y la información a nivel de campo de los datos, serializados como JSON.

NOTA

Cuando el campo "schema" está vacío o ausente por completo, el conector debe leer el campo "schemaRef" y utilizar la variable API del Registro de esquemas como se muestra en los pasos anteriores a ver un esquema de conjunto de datos.

La propiedad "observableSchema"

La propiedad "observableSchema" de un conjunto de datos tiene una estructura JSON que coincide con la del esquema XDM JSON. El "observableSchema" contiene los campos que estaban presentes en los archivos de entrada entrantes. Al escribir datos en Experience Platform, no es necesario que un usuario utilice cada campo del esquema de destino. En su lugar, solo deben proporcionar los campos que se están utilizando.

El esquema observable es el esquema que se utiliza si se leen los datos o se presenta una lista de campos disponibles para leer o asignar.

{
    "598d6e81b2745f000015edcb": {
        "observableSchema": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "name": {
                    "type": "string",
                },
                "age": {
                    "type": "string",
                }
            }
        }
    }
}

Previsualización de datos

La aplicación ETL puede proporcionar la capacidad de obtener una vista previa de los datos ("Figura 8" en el flujo de trabajo de ETL). La API de acceso a datos ofrece varias opciones para obtener una vista previa de los datos.

Puede encontrar información adicional, incluidas instrucciones paso a paso para previsualizar datos mediante la API de acceso a datos, en la tutorial de acceso a datos.

Obtener detalles del conjunto de datos mediante el parámetro de consulta "propiedades"

Como se muestra en los pasos anteriores a ver una lista de conjuntos de datos, puede solicitar "archivos" utilizando el parámetro de consulta "propiedades".

Puede consultar la Información general del servicio de catálogo para obtener información detallada sobre la consulta de conjuntos de datos y filtros de respuesta disponibles.

Formato de API

GET /catalog/dataSets?limit={value}&properties={value}

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=1&properties=files" \
  -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

La respuesta incluirá un conjunto de datos (limit=1) que muestra la propiedad "files".

{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files"
  }
}

Enumerar archivos de conjuntos de datos utilizando el atributo "files"

También puede utilizar una solicitud de GET para obtener detalles del archivo mediante el atributo "files".

Formato de API

GET /catalog/dataSets/{DATASET_ID}/views/{VIEW_ID}/files

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Respuesta

La respuesta incluye el ID del archivo del conjunto de datos como propiedad de nivel superior, con detalles del archivo incluidos en el objeto ID del archivo del conjunto de datos.

{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542749145828,
        "updated": 1542749145828
    },
    "14d5758c107443e1a83c714e56ca79d0-1": {
        "batchId": "14d5758c107443e1a83c714e56ca79d0",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542752699111,
        "updated": 1542752699111
    },
    "ea40946ac03140ec8ac4f25da360620a-1": {
        "batchId": "ea40946ac03140ec8ac4f25da360620a",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

Obtener detalles del archivo

Los ID de archivo del conjunto de datos devueltos en la respuesta anterior se pueden usar en una solicitud de GET para obtener más detalles del archivo a través del Data Access API.

La variable información general sobre el acceso a los datos contiene detalles sobre cómo usar la variable Data Access API.

Formato de API

GET /export/files/{DATASET_FILE_ID}

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Respuesta

[
    {
    "name": "{FILE_NAME}.parquet",
    "length": 2576,
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet"
            }
        }
    }
]

Vista previa de datos de archivos

La propiedad "href" se puede usar para recuperar datos de vista previa a través del Data Access API.

Formato de API

GET /export/files/{FILE_ID}?path={FILE_NAME}.{FILE_FORMAT}

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

La respuesta a la solicitud anterior contiene una vista previa del contenido del archivo.

Más información sobre Data Access La API, incluidas las solicitudes y respuestas detalladas, está disponible en la información general sobre el acceso a los datos.

Obtener "fileDescription" del conjunto de datos

El componente de destino como salida de datos transformados, el ingeniero de datos elegirá un conjunto de datos de salida ("Figura 12" en el flujo de trabajo de ETL). El esquema XDM está asociado con el conjunto de datos de salida. Los datos que se escribirán se identificarán mediante el atributo "fileDescription" de la entidad del conjunto de datos de las API de detección de datos. Esta información se puede obtener mediante un ID de conjunto de datos ({DATASET_ID}). La propiedad "fileDescription" en la respuesta JSON proporcionará la información solicitada.

Formato de API

GET /catalog/dataSets/{DATASET_ID}
Propiedad Descripción
{DATASET_ID} La variable id del conjunto de datos al que está intentando acceder.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"

Respuesta

{
  "59c93f3da7d0c00000798f68": {
    "version": "1.0.4",
    "fileDescription": {
        "persisted": false,
        "format": "parquet"
    }
  }
}

Los datos se escribirán en Experience Platform using API de inserción de datos. La escritura de datos es un proceso asincrónico. Cuando los datos se escriben en Adobe Experience Platform, un lote se crea y marca como un éxito solo después de que los datos se hayan escrito completamente.

Entrada de datos Experience Platform debe escribirse en forma de archivos de parquet.

Fase de ejecución

A medida que comienza la ejecución, el conector (como se define en el componente de origen) lee los datos de Experience Platform usando la variable Data Access API. El proceso de transformación leerá los datos durante un intervalo de tiempo determinado. Internamente, consulta lotes de conjuntos de datos de origen. Durante la consulta, se utilizará un archivo parametrizado (móvil para datos de series temporales o datos incrementales) de fecha de inicio y de lista de archivos de conjuntos de datos para esos lotes, y se empezará a realizar solicitudes de datos para esos archivos de conjuntos de datos.

Transformaciones de ejemplo

La variable transformaciones de ETL de muestra documento contiene varias transformaciones de ejemplo, como el manejo de identidades y las asignaciones de tipo de datos. Utilice estas transformaciones como referencia.

Leer datos de Experience Platform

Al usar la variable Catalog API, puede recuperar todos los lotes entre una hora de inicio y de finalización especificadas y ordenarlos según el orden en que se crearon.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?dataSet=DATASETID&createdAfter=START_TIMESTAMP&createdBefore=END_TIMESTAMP&sort=desc:created" \
  -H "Accept: application/json" \
  -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}"

Los detalles sobre los lotes de filtrado se encuentran en la Tutorial de acceso a datos.

Obtención de archivos de un lote

Una vez que tenga el ID del lote que está buscando ({BATCH_ID}), es posible recuperar una lista de archivos pertenecientes a un lote específico mediante el Data Access API. Los detalles para ello están disponibles en la sección Data Access tutorial.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/files" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Acceso a archivos mediante el ID de archivo

Uso del ID exclusivo de un archivo ({FILE_ID), el Data Access API se puede utilizar para acceder a los detalles específicos del archivo, incluido su nombre, tamaño en bytes y un vínculo para descargarlo.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{FILE_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

La respuesta puede apuntar a un solo archivo o a un directorio. Los detalles de cada uno se encuentran en la Data Access tutorial.

Acceso al contenido del archivo

La variable Data Access API para acceder al contenido de un archivo específico. Para recuperar el contenido, se realiza una solicitud de GET con el valor devuelto por _links.self.href al acceder a un archivo mediante el ID de archivo.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{DATASET_FILE_ID}?path=filename1.csv" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

La respuesta a esta solicitud contiene el contenido del archivo . Para obtener más información, incluidos los detalles sobre la paginación de respuestas, consulte la Cómo consultar datos mediante la API de acceso a datos tutorial.

Validación de registros para la conformidad con esquemas

Cuando se escriben los datos, los usuarios pueden optar por validarlos de acuerdo con las reglas de validación definidas en el esquema XDM. Puede encontrar más información sobre la validación de esquemas en la Código de referencia de integración de ecosistema de ETL en GitHub.

Si utiliza la implementación de referencia que se encuentra en GitHub, puede activar la validación de esquema en esta implementación mediante la propiedad system -DenableSchemaValidation=true.

La validación se puede realizar para tipos XDM lógicos, utilizando atributos como minLength y maxlength para cadenas, minimum y maximum para enteros, etc. La variable Guía del desarrollador de API del Registro del Esquema contiene una tabla que describe los tipos XDM y las propiedades que se pueden utilizar para la validación.

NOTA

Los valores mínimo y máximo proporcionados para varios integer Los tipos son los valores MIN y MAX que el tipo puede admitir, pero estos valores se pueden restringir aún más a mínimos y máximos de su elección.

Crear un lote

Una vez procesados los datos, la herramienta ETL vuelve a escribir los datos en Experience Platform usando la variable API de ingesta de lotes. Para poder agregar datos a un conjunto de datos, estos deben vincularse a un lote que luego se cargará en un conjunto de datos específico.

Solicitud

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -d '{
        "datasetId":"{DATASET_ID}"
      }'

Los detalles para crear un lote, incluidas las solicitudes de muestra y las respuestas, se pueden encontrar en la Información general sobre la ingesta de lotes.

Escribir en el conjunto de datos

Después de crear correctamente un nuevo lote, los archivos se pueden cargar en un conjunto de datos específico. Se pueden publicar varios archivos en un lote hasta que se promocione. Los archivos se pueden cargar mediante la API de carga de archivo pequeño; sin embargo, si los archivos son demasiado grandes y se supera el límite de la puerta de enlace, puede utilizar la API de carga de archivos grandes. Puede encontrar los detalles para utilizar la carga de archivos grande y pequeña en el Información general sobre la ingesta de lotes.

Solicitud

Entrada de datos Experience Platform debe escribirse en forma de archivos de parquet.

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/dataSets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "accept: application/json" \
  -H "x-gw-ims-org-id:{ORG_ID}" \
  -H "Authorization:Bearer ACCESS_TOKEN" \
  -H "x-api-key: API_KEY" \
  -H "content-type: application/octet-stream" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Marcar la carga por lotes como completada

Una vez cargados todos los archivos en el lote, se puede indicar que el lote ha finalizado. Al hacer esto, la variable Catalog Las entradas "DataSetFile" se crean para los archivos completados y se asocian al lote generado. La variable Catalog a continuación, se marca como correcto, lo que déclencheur los flujos descendentes a la ingesta de los datos disponibles.

Los datos se dirigen primero a la ubicación de ensayo de Adobe Experience Platform y, después, se mueven a la ubicación final después de la catalogación y validación. Los lotes se marcarán como correctos una vez que todos los datos se hayan movido a una ubicación permanente.

Solicitud

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization:Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Si se realiza correctamente, la respuesta devolverá el estado HTTP 200 OK y el cuerpo de respuesta estará vacío.

La herramienta ETL se asegurará de anotar la marca de tiempo de los conjuntos de datos de origen a medida que se leen los datos.

En la siguiente ejecución de transformación, probablemente por programación o invocación de evento, ETL empezará a solicitar los datos de la marca de tiempo guardada anteriormente y todos los datos a partir de ahora.

Obtener el estado del último lote

Antes de ejecutar nuevas tareas en la herramienta ETL, debe asegurarse de que el último lote se haya completado correctamente. La variable Catalog Service API proporciona una opción específica del lote que proporciona los detalles de los lotes relevantes.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?limit=1&sort=desc:created" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Respuesta

Se pueden programar nuevas tareas si el valor anterior de "estado" del lote es "éxito", como se muestra a continuación:

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "CLIENT_USER_ID@AdobeID",
    "updatedUser": "CLIENT_USER_ID@AdobeID",
    "updated": 1494349963467,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Obtener el estado del último lote por ID

Se puede recuperar un estado de lote individual mediante la variable Catalog Service API al emitir una solicitud de GET utilizando {BATCH_ID}. La variable {BATCH_ID} se utilizaría igual que el ID devuelto cuando se creó el lote.

Solicitud

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "Accept: application/json" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Respuesta: Correcto

La siguiente respuesta muestra un "éxito":

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Respuesta: Fallo

En caso de error, los "errores" se pueden extraer de la respuesta y mostrarse en la herramienta ETL como mensajes de error.

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "failure",
    "errors": [
        {
            "code": "200",
            "description": "Error in validating schema for file: 'adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv' with errorMessage=adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv is not a Parquet file. expected magic number at tail [80, 65, 82, 49] but found [57, 98, 55, 10] and errorType=java.lang.RuntimeException",
            "rows": []
        }
    ],
    "version": "1.0.1",
    "availableDates": {}
}

Eventos y datos incrementales frente a instantáneas frente a perfiles

Los datos se pueden representar en una matriz de dos por dos de la siguiente manera:

Eventos incrementales Perfiles incrementales
Eventos de instantánea (menos probable) Perfiles de instantánea

Los datos de evento suelen aparecer cuando hay columnas de marca de hora indexadas en cada fila.

Los datos de perfil suelen aparecer cuando no hay una marca de hora en los datos y cada fila se puede identificar con una clave principal/compuesta.

Los datos incrementales son aquellos en los que solo los datos nuevos o actualizados llegan al sistema y se anexan a los datos actuales en los conjuntos de datos.

Los datos de instantánea se producen cuando todos los datos entran en el sistema y sustituyen algunos o todos los datos anteriores de un conjunto de datos.

En el caso de eventos incrementales, la herramienta ETL debe utilizar las fechas disponibles/crear fecha de la entidad del lote. En caso de servicio push, las fechas disponibles no estarán presentes, por lo que la herramienta utilizará la fecha creada o actualizada por lotes para marcar los incrementos. Es necesario procesar cada lote de eventos incrementales.

Para perfiles incrementales, la herramienta ETL utilizará fechas creadas o actualizadas de la entidad por lotes. Normalmente, se requiere procesar cada lote de datos de perfil incrementales.

Los eventos de instantáneas son muy menos probables debido al tamaño de los datos. Pero si esto fuera necesario, la herramienta ETL debe seleccionar solo el último lote para el procesamiento.

Cuando se utilizan perfiles de instantánea, la herramienta ETL tendrá que elegir el último lote de datos que llegaron al sistema. Sin embargo, si el requisito es realizar un seguimiento de las versiones de los cambios, es necesario procesar todos los lotes. El procesamiento de deduplicación dentro del proceso de ETL ayudará a controlar los costos de almacenamiento.

Reproducción por lotes y reprocesamiento de datos

Es posible que se requiera la reproducción por lotes y el reprocesamiento de datos en los casos en que un cliente descubra que durante los últimos "n" días, los datos que se están procesando con ETL no se han producido del modo esperado o puede que los datos de origen en sí no hayan sido correctos.

Para ello, los administradores de datos del cliente utilizarán la variable Platform IU para eliminar los lotes que contienen datos dañados. Entonces, es probable que se deba volver a ejecutar el ETL, lo que se rerellenará con los datos correctos. Si la fuente en sí tenía datos dañados, el ingeniero/administrador de datos deberá corregir los lotes de origen y volver a introducir los datos (ya sea en Adobe Experience Platform o a través de conectores ETL).

Based upon the type of data being generated, it will be the data engineer's choice to remove a single batch or all batches from certain datasets. Los datos se eliminarán o archivarán según Experience Platform directrices.

It is a likely scenario that the ETL functionality to purge data will be important.

Una vez finalizada la depuración, los administradores del cliente deberán reconfigurar Adobe Experience Platform para reiniciar el procesamiento de los servicios principales desde el momento en que se eliminen los lotes.

Concurrent batch processing

A criterio del cliente, los administradores/ingenieros de datos pueden decidir extraer, transformar y cargar datos de manera secuencial o concurrente según las características de un conjunto de datos en particular. Esto también se basará en el caso de uso al que se dirige el cliente con los datos transformados.

Por ejemplo, si el cliente persiste en un almacén de persistencia actualizable y la secuencia o el orden de los eventos es importante, es posible que el cliente tenga que procesar estrictamente los trabajos con transformaciones de ETL secuenciales.

En otros casos, los datos desordenados se pueden procesar mediante aplicaciones o procesos descendentes que se ordenan internamente mediante una marca de tiempo especificada. En estos casos, las transformaciones de ETL paralelas pueden ser viables para mejorar los tiempos de procesamiento.

Para los lotes de origen, también dependerá de las preferencias del cliente y de la restricción del consumidor. Si los datos de origen se pueden recopilar en paralelo independientemente de la regencia o el orden de una fila, el proceso de transformación puede crear lotes de procesos con un mayor grado de paralelismo (optimización basada en el procesamiento por orden). Pero si la transformación tiene que cumplir con las marcas de tiempo o cambiar la orden de prioridad, la API de acceso a datos o el programador/invocación de herramientas de ETL tendrán que asegurarse de que los lotes no se procesen de forma desordenada siempre que sea posible.

Aplazamiento

El aplazamiento es un proceso en el que los datos de entrada aún no están lo suficientemente completos para enviarse a procesos descendentes, pero pueden utilizarse en el futuro. Los clientes determinarán su tolerancia individual para la limitación de datos en caso de correspondencias futuras en comparación con el coste del procesamiento para informar su decisión de apartar datos y reprocesarlos en la siguiente ejecución de transformación, con la esperanza de que se puedan enriquecer y reconciliar/vincular en algún momento futuro dentro del período de retención. Este ciclo está en curso hasta que la fila se procese lo suficiente o se considere demasiado antigua para seguir invirtiendo en. Cada iteración genera datos diferidos, que son un superconjunto de todos los datos diferidos de iteraciones anteriores.

Adobe Experience Platform no identifica actualmente los datos diferidos, por lo que las implementaciones de cliente deben confiar en las configuraciones del manual ETL y Dataset para crear otro conjunto de datos en Platform reflejo del conjunto de datos de origen que se puede usar para mantener los datos diferidos. En este caso, los datos diferidos serán similares a los datos de instantáneas. En cada ejecución de la transformación ETL, los datos de origen se unen con los datos diferidos y se envían para su procesamiento.

Cambio

Fecha Acción Descripción
19-01-2019 Se ha eliminado la propiedad "fields" de los conjuntos de datos Anteriormente, los conjuntos de datos incluían una propiedad "fields" que contenía una copia del esquema. Esta capacidad ya no debe usarse. Si se encuentra la propiedad "fields", se debe ignorar y usar en su lugar el "observationSchema" o "schemaRef".
2019-03-15 Propiedad "schemaRef" agregada a conjuntos de datos La propiedad "schemaRef" de un conjunto de datos contiene una URI que hace referencia al esquema XDM en el que se basa el conjunto de datos y representa todos los campos potenciales que podría utilizar el conjunto de datos.
2019-03-15 Todos los identificadores de usuario final se asignan a la propiedad "identityMap". "identityMap" es una encapsulación de todos los identificadores únicos de un asunto, como ID de CRM, ECID o ID de programa de fidelidad. Este mapa lo utiliza Identity Service para resolver todas las identidades conocidas y anónimas de un sujeto, formando un único gráfico de identidad para cada usuario final.
30-05-2019 EOL y Eliminar la propiedad "schema" de los conjuntos de datos La propiedad "schema" del conjunto de datos proporcionó un vínculo de referencia al esquema mediante el desaprobada /xdms en la variable Catalog API. Esto se ha reemplazado por un "schemaRef" que proporciona el "id", "version" y "contentType" del esquema como se hace referencia en el nuevo Schema Registry API.

En esta página