Introducción a las API de Adobe Experience Platform

Adobe Experience Platform se desarrolla bajo la filosofía "API First". Con las API de Platform, puede realizar mediante programación operaciones básicas de CRUD (crear, leer, actualizar, eliminar) con datos, como configurar atributos calculados, acceder a datos o entidades, exportar datos, eliminar datos o lotes innecesarios, etc.

Todas las API de cada servicio de Experience Platform comparten el mismo conjunto de encabezados de autenticación y utilizan sintaxis similares para sus operaciones de CRUD. La siguiente guía describe los pasos necesarios para empezar a utilizar las API de Platform.

Autenticación y encabezados

Para realizar llamadas correctamente a los extremos de Platform, debe completar el tutorial de autenticación. Al completar el tutorial de autenticación, se proporcionan los valores de cada uno de los encabezados necesarios en las llamadas de API de Experience Platform, como se muestra a continuación:

Encabezado de zona protegida

Todos los recursos de Experience Platform están aislados para zonas protegidas virtuales específicas. Las solicitudes a las API de Platform requieren un encabezado que especifique el nombre de la zona protegida en la que se realizará la operación:

Para obtener más información sobre las zonas protegidas en Platform, consulte la documentación de información general sobre las zonas protegidas.

Encabezado de tipo de contenido

Todas las solicitudes con una carga útil en el cuerpo de la solicitud (como llamadas de POST, PUT y PATCH) deben incluir un encabezado Content-Type. Los valores aceptados son específicos de cada extremo de API. Si se necesita un valor Content-Type específico para un extremo, su valor se mostrará en las solicitudes de API de ejemplo proporcionadas por las guías de API para servicios de Platform individuales.

Fundamentos de API de Experience Platform

Las API de Adobe Experience Platform emplean varias tecnologías y sintaxis subyacentes que son importantes de comprender para administrar de forma eficaz los recursos de Platform.

Para obtener más información sobre las tecnologías de API subyacentes que utiliza Platform, incluidos los objetos de esquema JSON de ejemplo, visite la guía Aspectos básicos de la API del Experience Platform.

Colecciones de Postman para API de Experience Platform

Postman es una plataforma de colaboración para el desarrollo de API que le permite configurar entornos con variables preestablecidas, compartir colecciones de API, optimizar solicitudes de CRUD y mucho más. La mayoría de los servicios de API de Platform tienen colecciones de Postman que se pueden utilizar para ayudar a realizar llamadas de API.

Para obtener más información acerca de Postman, incluyendo cómo configurar un entorno, una lista de colecciones disponibles y cómo importar colecciones, visite la Documentación de Platform Postman.

Lectura de llamadas de API de muestra sample-api

Los formatos de solicitud varían según la API de plataforma que se utilice. La mejor manera de aprender a estructurar las llamadas de API es siguiendo los ejemplos proporcionados en la documentación del servicio de Platform concreto que está utilizando.

La documentación de Experience Platform muestra ejemplos de llamadas de API de dos maneras diferentes. En primer lugar, la llamada se presenta en su formato de API, una representación de plantilla que muestra únicamente la operación (GET, POST, PUT, PATCH, DELETE) y el extremo que se está utilizando (por ejemplo, /global/classes). Algunas plantillas también muestran la ubicación de las variables para ilustrar cómo se debe formular una llamada, como GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}.

Las llamadas se muestran como comandos cURL en una solicitud, que incluye los encabezados necesarios y la "ruta base" completa necesaria para interactuar correctamente con la API. La ruta base debe prefijarse a todos los extremos. Por ejemplo, el extremo /global/classes mencionado se convierte en https://platform.adobe.io/data/foundation/schemaregistry/global/classes. Verá el formato de la API/patrón de solicitud en toda la documentación y se espera que utilice la ruta completa que se muestra en la solicitud de ejemplo al realizar sus propias llamadas a las API de Platform.

Ejemplo de solicitud de API

A continuación se muestra un ejemplo de solicitud de API que muestra el formato que encontrará en la documentación.

Formato de API

El formato de la API muestra la operación (GET) y el punto final que se está utilizando. Las variables se indican con llaves (en este caso, {CONTAINER_ID}).

GET /{CONTAINER_ID}/classes

Solicitud

En esta solicitud de ejemplo, las variables del formato API reciben valores reales en la ruta de solicitud. Además, todos los encabezados requeridos se muestran como valores de encabezado de muestra o como variables donde se debe incluir información confidencial (como tokens de seguridad e ID de acceso).

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+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}'

Respuesta

La respuesta ilustra lo que esperaría recibir después de una llamada correcta a la API, según la solicitud enviada. En ocasiones, la respuesta se trunca en cuanto al espacio, lo que significa que puede ver más información o información adicional que la mostrada en el ejemplo.

{
    "results": [
        {
            "title": "XDM ExperienceEvent",
            "$id": "https://ns.adobe.com/xdm/context/experienceevent",
            "meta:altId": "_xdm.context.experienceevent",
            "version": "1"
        },
        {
            "title": "XDM Individual Profile",
            "$id": "https://ns.adobe.com/xdm/context/profile",
            "meta:altId": "_xdm.context.profile",
            "version": "1"
        }
    ],
    "_links": {}
}

Mensajes de error

La Guía de solución de problemas de la plataforma proporciona una lista de errores que pueden producirse al utilizar cualquier servicio de Experience Platform.

Para obtener guías de solución de problemas sobre servicios de Platform individuales, consulte el directorio de solución de problemas del servicio.

Para obtener más información sobre extremos específicos en las API de Platform, incluidos los encabezados y cuerpos de solicitud necesarios, consulte las guías de la API de Platform.

Guías de API de Platform api-guides

Para obtener más información sobre los extremos específicos y las operaciones disponibles para cada servicio, consulte la documentación de referencia de la API en Adobe I/O.

Pasos siguientes

Este documento introdujo los encabezados necesarios, las guías disponibles y proporcionó un ejemplo de llamada de API. Ahora que tiene los valores de encabezado necesarios para realizar llamadas de API en Adobe Experience Platform, seleccione un extremo de API que desee explorar en la tabla de guías de API de Platform.

Para obtener respuestas a las preguntas más frecuentes, consulte la Guía de solución de problemas de la plataforma.

Para configurar un entorno de Postman y explorar las colecciones de Postman disponibles, consulte la Guía de Platform Postman.