Introducción a REST APIs

Información sobre requisitos generales, autenticación, parámetros de consulta opcionales, solicitud URLs y 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 código API de Audience Manager:

  • 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 I/ Otokens, debe proporcionar el x-api-key encabezado. Puede obtener la clave API siguiendo las instrucciones de la página Service Account Integration.
  • JSONtipo de contenido: especifique content-type: application/json ** accept: application/json y en su código.
  • Solicitudes y respuestas: envíe solicitudes como JSON objeto con el formato correcto. Audience Manager responde con datos JSON formateados. Las respuestas del servidor pueden contener datos solicitados, un código de estado o ambos.
  • Acceso: el Audience Manager consultor le proporcionará un ID de cliente y una clave que le permitirán realizar API solicitudes.
  • Ejemplos de documentación y código: el texto en ** cursiva representa una variable que se proporciona o pasa al crear o recibir API datos. Reemplace el texto cursiva con su propio código, parámetros u otra información requerida.

Autenticación

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

IMPORTANTE

Según el método de autenticación, debe ajustar la solicitud URLs en consecuencia. Consulte la sección Environments para obtener más información sobre los nombres de host que debe utilizar.

JWT (Service Account) Autenticación mediante Adobe I/O

Información general sobre Adobes I/O

Adobe I/O es el ecosistema y la comunidad de desarrolladores de Adobe. Incluye las herramientas para desarrolladores de Adobe I/O y las API y API para todos los productos de Adobe.

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

Requisitos previos

Antes de configurar la autenticación JWT, asegúrese de tener acceso a la Consola del desarrollador de Adobe en Adobe I/O. Póngase en contacto con el administrador de su organización para solicitar acceso.

Autenticación

Siga los pasos a continuación para configurar la autenticación JWT (Service Account) mediante Adobe I/O:

  1. Inicie sesión en Adobe Developer Console.
  2. Siga los pasos de Conexión de cuenta de servicio.
  3. Pruebe la conexión realizando la primera llamada API en función de las instrucciones del Paso 3.
NOTA

Para configurar y trabajar con Audience Manager REST APIs de forma automatizada, puede generar el JWT mediante programación. Consulte Autenticación JWT (cuenta de servicio) para obtener instrucciones detalladas.

Permisos RBAC de cuenta técnica

Si la 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. Realice una llamada GET a https://aam.adobe.io/v1/users/self. La llamada creará una cuenta de usuario técnica que puede ver en Admin Console, en la página Users.

    cuenta técnica

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

OAuth Autenticación (obsoleto)

ADVERTENCIA

Audience Manager REST API la autenticación y la renovación de tokens mediante ahora OAuth 2.0 están en desuso.

En su lugar, utilice Autenticación JWT (cuenta de servicio).

El Audience Manager REST API sigue los 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 usuario API genérico

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

  • Identifique qué servicio llama a API (p. ej., llamadas de sus aplicaciones que usan nuestros APIs o de otras herramientas que realizan API solicitudes).
  • Proporcione acceso ininterrumpido a APIs. Una cuenta vinculada a una persona específica puede ser eliminada cuando abandone la empresa. Esto impedirá que trabaje con el código API disponible. 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 las 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 una cuenta de usuario API no específica que tenga las credenciales, la clave y el secreto adecuados para realizar llamadas API. Esto también resulta útil si desarrolla sus propias aplicaciones que utilizan Audience Manager APIs.

Póngase en contacto con su consultor de Audience Manager para configurar una cuenta de usuario genérica de solo API.

Flujo de trabajo de autenticación de contraseña

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

SUGERENCIA

Codifique el acceso y actualice los tokens si los almacena en una base de datos.

Paso 1: Solicitar acceso API

Póngase en contacto con el administrador de soluciones de socios. Le proporcionarán un API ID de cliente y un secreto. El ID y el secreto le autentican en API.

Nota: Si desea recibir un token de actualización, especifíquelo cuando solicite el acceso API.

Paso 2: Solicitar el token

Pase una solicitud de token con su cliente JSON preferido. Al crear la solicitud:

  • Utilice un método POST para llamar a https://api.demdex.com/oauth/token.
  • Convierta el ID de cliente y el secreto en una cadena codificada base-64. Separe el ID y el secreto con dos puntos durante el proceso de conversión. Por ejemplo, las credenciales testId : testSecret se convierten en dGVzdElkOnRlc3RTZWNyZXQ=.
  • Pasa 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

La respuesta JSON contiene su token de acceso. La respuesta debería tener este aspecto:

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

La clave 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 alguna vez.

Actualizar token

Actualice los tokens para renovar el acceso API después de que caduque el token original. Si se solicita, la respuesta JSON en el flujo de trabajo de la contraseña 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 utilizar un token de actualización para crear un nuevo token de acceso desde un cliente JSON en el explorador.

Paso 1: Solicitar el nuevo token

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

  • Utilice un método POST para llamar a https://api.demdex.com/oauth/token.
  • Convierta el ID de cliente y el secreto en una cadena codificada base-64. Separe el ID y el secreto con dos puntos durante el proceso de conversión. Por ejemplo, las credenciales testId : testSecret se convierten en dGVzdElkOnRlc3RTZWNyZXQ=.
  • Pasa 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

La respuesta JSON contiene el nuevo token de acceso. La respuesta debería tener este aspecto:

{
    "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 los tokens.

Realizar solicitudes autenticadas API

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

Para realizar llamadas con los métodos API disponibles:

Parámetros de consulta API opcionales

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 métodos API que devuelven todas propiedades para un objeto. Establezca estas opciones en la cadena de solicitud al pasar esa consulta a API.

Parámetro Descripción
page Devuelve los resultados por número de página. La numeración comienza en 0.
pageSize Define el número de resultados de respuesta que devuelve la solicitud (10 es el valor predeterminado).
sortBy Ordena y devuelve los resultados según la propiedad JSON especificada.
descending Ordena y devuelve los resultados en orden descendente. ascending es el valor predeterminado.
search Devuelve los resultados en función de la cadena especificada que desee utilizar como parámetro de búsqueda. Por ejemplo, supongamos que desea encontrar resultados para todos los modelos que tienen la palabra "Prueba" en cualquiera de los campos de valor para ese elemento. Su solicitud de ejemplo podría tener este aspecto: GET https://aam.adobe.io/v1/models/?search=Test. Puede buscar cualquier valor devuelto mediante el método "get all".
folderId Devuelve todos los ID de traits dentro de la carpeta especificada. No está disponible para todos los métodos.
permissions Devuelve una lista de segmentos en función del permiso especificado. READ es el valor predeterminado. Los permisos incluyen:
  • READ : Devolver y ver información sobre un segmento.
  • WRITE : Utilice PUT para actualizar un segmento.
  • CREATE : Utilice POST para crear un segmento.
  • DELETE : Eliminar un segmento. Requiere acceso a los rasgos subyacentes, si los hay. Por ejemplo, necesitará derechos para eliminar las características que pertenecen a un segmento si desea eliminarlas.

Especifique varios permisos con pares de clave-valor independientes. Por ejemplo, para devolver una lista de segmentos con permisos de READ y WRITE , pase "permissions":"READ", "permissions":"WRITE" .
includePermissions (Boolean) Configúrelo en true para devolver sus permisos para el segmento. El valor predeterminado es false.

Una Nota Sobre Las Opciones De Página

Cuando la información de la página no se especifica, la solicitud devuelve JSON sin formato y resulta en una matriz. Si se especifica la información de la página es, la lista devuelta se ajusta en un objeto JSON que contiene información sobre el resultado total y la página actual. Su solicitud de ejemplo con opciones de página podría 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 utilizada para pasar las solicitudes API, por método.

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

Solicitar URLs autenticación JWT

API Métodos Solicitud URL
Algorithmic Modeling https://aam.adobe.io/v1/models/
Data Source https://aam.adobe.io/v1/datasources/
Derived Signals https://aam.adobe.io/v1/signals/derived/
Destinations https://aam.adobe.io/v1/destinations/
Domains https://aam.adobe.io/v1/partner-sites/
Folders Características: https://aam.adobe.io/v1/folders/traits /
Segmentos: https://aam.adobe.io/v1/folders/segments /
Schema https://aam.adobe.io/v1/schemas/
Segments https://aam.adobe.io/v1/segments/
Traits https://aam.adobe.io/v1/traits/
Trait Types https://aam.adobe.io/v1/customer-trait-types
Taxonomy https://aam.adobe.io/v1/taxonomies/0/

Solicitar URLs autenticación OAuth (obsoleto)

API Métodos Solicitud URL
Algorithmic Modeling https://api.demdex.com/v1/models/
Data Source https://api.demdex.com/v1/datasources/
Derived Signals https://api.demdex.com/v1/signals/derived/
Destinations https://api.demdex.com/v1/destinations/
Domains https://api.demdex.com/v1/partner-sites/
Folders Características: https://api.demdex.com/v1/folders/traits /
Segmentos: https://api.demdex.com/v1/folders/segments /
Schema https://api.demdex.com/v1/schemas/
Segments https://api.demdex.com/v1/segments/
Traits https://api.demdex.com/v1/traits/
Trait Types https://api.demdex.com/v1/customer-trait-types
Taxonomy https://api.demdex.com/v1/taxonomies/0/

Entornos

Los Audience Manager APIproporcionan acceso a diferentes entornos de trabajo. Estos entornos ayudan a probar el código con bases de datos independientes sin afectar a los datos de producción activos. La siguiente tabla enumera los entornos API disponibles y los nombres de host de recursos correspondientes.

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

Entorno Nombre de host para la autenticación JWT Nombre de host para la autenticación OAuth
Producción https://aam.adobe.io/... https://api.demdex.com/...
Beta https://aam-beta.adobe.io/... https://api-beta.demdex.com/...
NOTA

El entorno beta Audience Manager es una versión independiente de menor escala del entorno de producción. Todos los datos que desee probar deben introducirse y recopilarse en este entorno.

Versiones

Las nuevas versiones de estos APIs se publican con regularidad. Una nueva versión incrementa el número de versión API. Se hace referencia al número de versión en la solicitud URL como 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 que devuelve Audience Manager REST API.

ID del código de respuesta Texto de respuesta Definición
200 OK La solicitud se procesó correctamente. Devuelve el contenido o los datos esperados si es necesario.
201 Created Se creó el recurso. Devuelve para solicitudes PUT y POST.
204 No Content El recurso se ha eliminado. El cuerpo de la respuesta estará en blanco.
400 Bad Request El servidor no entendió la solicitud. Normalmente se debe a una sintaxis mal formada. Compruebe la solicitud e inténtelo de nuevo.
403 Forbidden No tiene acceso al recurso.
404 Not Found No se encontró el recurso para la ruta especificada.
409 Conflict No se pudo completar la solicitud debido a un conflicto con el estado del recurso.
500 Server Error El servidor encontró un error inesperado que impedía que cumpliera la solicitud.

En esta página