Introducción a REST APIs

Información sobre requisitos generales, autenticación, parámetros de consulta opcionales, solicitud URLsy otras referencias.

Requisitos y recomendaciones de API

Cosas que debe y debe hacer al trabajar con Audience Manager APIs.

Tenga en cuenta lo siguiente al trabajar con API de Audience Manager código:

• Parámetros de solicitud: todos los parámetros de solicitud son obligatorios a menos que se especifique lo contrario.
• Encabezados de solicitud: al utilizar Adobe Developer tokens, debe proporcionar el x-api-key encabezado. Puede obtener su API clave siguiendo las instrucciones de la Integración de cuenta de servicio página.
• JSONtipo de contenido: Especificar content-type: application/json y accept: application/json en el código.
• Solicitudes y respuestas: Envío de solicitudes como una solicitud con el formato correcto JSON objeto. Audience Manager responde con JSON datos con formato. Las respuestas del servidor pueden contener datos solicitados, un código de estado o ambos.
• Acceso: Su Audience Manager El consultor de le proporcionará un ID de cliente y una clave que le permitirán realizar API solicitudes.
• Documentación y ejemplos de código: Texto en cursiva representa una variable que se proporciona o se pasa al realizar o recibir API datos. Reemplazar en cursiva texto con su propio código, parámetros u otra información necesaria.

Autenticación

El Audience Manager REST APIs admite dos métodos de autenticación.

• Autenticación JWT (cuenta de servicio) usando Adobe Developer. Adobe Developer es el ecosistema y la comunidad de desarrolladores de Adobe. Incluye API para todos los productos de Adobe. Esta es la forma recomendada de configurar y utilizar Adobe APIs.
• Autenticación de OAuth (obsoleta). Aunque este método esté obsoleto, los clientes con OAuth Las integraciones de pueden seguir utilizando este método.

JWT (Service Account) Autenticación mediante Adobe Developer

Información general de Adobe Developer

Adobe Developer es el ecosistema y la comunidad de desarrolladores de Adobe. Incluye API para todos los productos de Adobe.

Esta es la forma recomendada de configurar y utilizar Adobe APIs.

Requisitos previos

Antes de poder configurar JWT autenticación, asegúrese de que tiene acceso a la Consola de Adobe Developer in Adobe Developer. Póngase en contacto con el administrador de su organización para solicitudes de acceso.

Autenticación

Siga los pasos a continuación para configurar JWT (Service Account) autenticación mediante Adobe Developer:

1. Inicie sesión en Consola de Adobe Developer.
2. Siga los pasos de Conexión de cuenta de servicio.
   • Durante Paso 2: Añadir una API al proyecto mediante la autenticación de cuenta de servicio, elija la Audience Manager API opción.
3. Pruebe la conexión estableciendo la primera API llamada de basada en las instrucciones de Paso 3.

Permisos de RBAC de cuenta técnica

Si su cuenta de Audience Manager utiliza Control de acceso basado en roles, debe crear una cuenta de usuario técnica de Audience Manager y agregarla al grupo RBAC de Audience Manager que realizará las llamadas de API.

Siga los pasos a continuación para crear una cuenta de usuario técnica y agregarla a un grupo RBAC:

1. Crear un GET llamada a https://aam.adobe.io/v1/users/self. La llamada creará una cuenta de usuario técnica que puede ver en el Admin Console, en el Users página.

   

2. Inicie sesión en su cuenta de Audience Manager y agregar la cuenta de usuario técnica al grupo de usuarios que realizará las llamadas de API.

OAuth Autenticación (obsoleta)

El Audience Manager REST API sigue OAuth 2.0 estándares para la autenticación y renovación de tokens. Las secciones siguientes describen cómo autenticarse y comenzar a trabajar con APIs.

Crear un genérico API Usuario

Le recomendamos que cree una cuenta de usuario técnica independiente para trabajar con Audience Manager APIs. Es una cuenta genérica que no está vinculada a un usuario específico de su organización ni asociada a él. Este tipo de API La cuenta de usuario de le ayuda a lograr dos cosas:

• Identificar qué servicio llama al API (p. ej., llamadas desde sus aplicaciones que usan nuestro APIu otras herramientas que hacen que API solicitudes).
• Proporcionar acceso ininterrumpido al APIs. Una cuenta vinculada a una persona específica puede eliminarse cuando abandone la compañía. Esto evitará que trabaje con el disponible API código. Una cuenta genérica que no esté vinculada a un empleado en particular le ayuda a evitar este problema.

Como ejemplo o caso de uso para este tipo de cuenta, supongamos que desea cambiar muchos segmentos a la vez con Herramientas de administración masiva. Bueno, para ello, su cuenta de usuario necesita API acceso. En lugar de agregar permisos a un usuario específico, cree un de tipo no específico, API cuenta de usuario que tiene las credenciales, la clave y el secreto adecuados para realizar API llamadas. Esto también resulta útil si desarrolla sus propias aplicaciones que utilizan Audience Manager APIs.

Trabaje con su Audience Manager consultor para configurar un genérico, APICuenta de usuario solo de.

Flujo de trabajo de autenticación de contraseña

Autenticación de contraseña acceso seguro nuestro REST API. Los pasos siguientes describen el flujo de trabajo para la autenticación de contraseña desde un JSON cliente en el explorador.

Paso 1: Solicitud API Acceso

Póngase en contacto con su administrador de Soluciones para socios. Ellos le proporcionarán una API ID de cliente y secreto. El ID y el secreto le autentican en el API.

Nota: Si desea recibir un token de actualización, especifique eso cuando solicite API acceso.

Paso 2: Solicitar el token

Pase una solicitud de token con su preferido JSON cliente. Cuando genere la solicitud:

• Utilice un POST método al que llamar https://api.demdex.com/oauth/token.
• Convierta su ID de cliente y secreto en una cadena codificada en base 64. Separe el ID y el secreto con dos puntos durante el proceso de conversión. Por ejemplo, las credenciales de testId : testSecret convertir a dGVzdElkOnRlc3RTZWNyZXQ=.
• Pase el HTTP headers Authorization:Basic <base-64 clientID:clientSecret> y Content-Type: application/x-www-form-urlencoded . Por ejemplo, el encabezado podría tener este aspecto:
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• Configure el cuerpo de la solicitud de la siguiente manera:
  
  grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>

Paso 3: Recibir el token

El JSON La respuesta de contiene su token de acceso. La respuesta debería ser similar a la siguiente:

{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

El expires_in representa el número de segundos hasta que caduca el token de acceso. Se recomienda utilizar tiempos de caducidad cortos para limitar la exposición si el token se expone en algún momento.

Actualizar token

Actualizar tokens renovar API una vez caducado el token original. Si se solicita, la respuesta JSON en el flujo de trabajo de contraseñas incluye un token de actualización. Si no recibe un token de actualización, cree uno nuevo mediante el proceso de autenticación de contraseña.

También puede utilizar un token de actualización para generar un nuevo token antes de que caduque el token de acceso existente.

Si el token de acceso ha caducado, recibirá un 401 Status Code y el siguiente encabezado en la respuesta:

WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"

Los siguientes pasos describen el flujo de trabajo para el uso de un token de actualización con el fin de crear un nuevo token de acceso a partir de un JSON cliente en el explorador.

Paso 1: Solicitar el nuevo token

Pase una solicitud de token de actualización con su preferido JSON cliente. Cuando genere la solicitud:

• Utilice un POST método al que llamar https://api.demdex.com/oauth/token.
• Convierta su ID de cliente y secreto en una cadena codificada en base 64. Separe el ID y el secreto con dos puntos durante el proceso de conversión. Por ejemplo, las credenciales de testId : testSecret convertir a dGVzdElkOnRlc3RTZWNyZXQ=.
• Pasar los encabezados HTTP Authorization:Basic <base-64 clientID:clientSecret> y Content-Type: application/x-www-form-urlencoded. Por ejemplo, el encabezado podría tener este aspecto:
  Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
• En el cuerpo de la solicitud, especifique grant_type:refresh_token y pase el token de actualización que recibió en su solicitud de acceso anterior. La solicitud debe tener este aspecto:
  grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e

Paso 2: Recibir el nuevo token

El JSON La respuesta de contiene su nuevo token de acceso. La respuesta debería ser similar a la siguiente:

{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

Código de autorización y autenticación implícita

El Audience Manager REST API admite código de autorización y autenticación implícita. Para utilizar estos métodos de acceso, los usuarios deben iniciar sesión en https://api.demdex.com/oauth/authorize para obtener acceso y actualizar tokens.

Convertir en autenticado API Solicitudes

Requisitos para llamar a API métodos después de recibir un token de autenticación.

Para realizar llamadas contra el disponible API métodos:

• En el HTTP encabezado, establecer Authorization: Bearer <token>.
• Al utilizar Autenticación JWT (cuenta de servicio), debe proporcionar el x-api-key encabezado, que será el mismo que su client_id. Puede obtener su client_id desde el Integración de Adobe Developer página.
• Llame a la función requerida API método.

Opcional API Parámetros de consulta

Establezca los parámetros opcionales disponibles para los métodos que devuelven todas las propiedades de un objeto.

Puede utilizar estos parámetros opcionales con API métodos que devuelven todo propiedades de un objeto. Establezca estas opciones en la cadena de solicitud al pasar esa consulta al API.

Una Nota Sobre Las Opciones De Página

Cuando la información de página no es especificado, la solicitud se devuelve sin formato JSON da como resultado una matriz. Si la información de página es especificado, la lista devuelta se incluirá dentro de un JSON que contiene información sobre el resultado total y la página actual. La solicitud de muestra que utiliza opciones de página puede tener un aspecto similar al siguiente:

GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test

API URLs

URLs para solicitudes, entornos de ensayo y producción y versiones.

Solicitud URLs

La siguiente tabla enumera la solicitud URLs se usa para pasar API solicitudes, por método.

Según el método de autenticación que utilice, debe ajustar la solicitud URLs según las tablas que figuran a continuación.

Solicitud URLs para JWT Autenticación

Solicitud URLs para OAuth Autenticación (obsoleta)

Entornos

El Audience Manager APIproporciona acceso a diferentes entornos de trabajo. Estos entornos le ayudan a probar el código en bases de datos independientes sin afectar a los datos activos y de producción. En la tabla siguiente se enumeran los disponibles API entornos y nombres de host de recursos correspondientes.

Según el método de autenticación que utilice, debe ajustar el entorno URLs de acuerdo con la tabla siguiente.

Versiones

Nuevas versiones de estos APILas se publican de forma regular. Una nueva versión incrementa el API número de versión. Se hace referencia al número de versión en la solicitud URL as v<version number> como se muestra en el siguiente ejemplo:

https://<host>/v1/...

Códigos de respuesta definidos

HTTP códigos de estado y texto de respuesta devueltos por el Audience Manager REST API.

Recursos de Business.Adobe.com

Third Party Integrations Third Party Data Customer Journey Analytics Mobile Analytics Audience Segmentation General Data Protection Regulation