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 el 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 Integración de cuentas de servicio.
  • JSONtipo de contenido: especifique content-type: application/json ** accept: application/json y el código.
  • Solicitudes y respuestas: Enviar 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: Su Audience Manager asesor le proporcionará un ID de cliente y una clave que le permitirá realizar API solicitudes.
  • Muestras 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 en cursiva por 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 Entornos para obtener detalles sobre los nombres de host que debe utilizar.

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

Información general de Adobe I/O

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

Ésta es la manera recomendada de configurar y utilizar Adobe APIs.

Requisitos previos

Antes de configurar la autenticación JWT, asegúrese de tener acceso a la Consola de 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 la Consola de programadores de Adobe.
  2. Siga los pasos en Conexión de cuenta de servicio.
  3. Pruebe la conexión haciendo su primera API llamada en función de las instrucciones del Paso 3.
NOTA

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

OAuth Autenticación (obsoleto)

ADVERTENCIA

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

Utilice Autenticación de JWT (cuenta de servicio) en su lugar.

El Audience Manager REST API sigue los estándares OAuth 2.0 para la autenticación y renovación de testigos. Las secciones a continuación describen cómo autenticar y inicio el trabajo con APIs.

Crear un API usuariogenérico

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 cuenta de usuario API le ayuda a realizar dos tareas:

  • Identifique qué servicio llama a API (por ejemplo: llamadas desde las aplicaciones que utilizan nuestro APIs o desde otras herramientas que realizan API solicitudes).
  • Proporcione acceso ininterrumpido a APIs. Una cuenta vinculada a una persona específica puede ser eliminada cuando abandone su compañía. 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 hacerlo, 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 API llamadas. Esto también es útil si desarrolla sus propias aplicaciones que utilizan Audience Manager APIs.

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

Flujo de trabajo de autenticación de contraseña

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

CONSEJO

Cifre los tokens de acceso y actualícelos si los almacena en una base de datos.

Paso 1: Solicitar acceso API

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

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

Paso 2: Solicitar el token

Pase una solicitud de token con su cliente JSON preferido. Al generar 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 con codificación 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 del flujo de trabajo de 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 a partir de un cliente JSON en el explorador.

Paso 1: Solicitar el nuevo token

Pasa una solicitud de token de actualización con tu cliente JSON preferido. Al generar 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 con codificación 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 la solicitud de acceso anterior. La solicitud debería 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 API autenticadas

Requisitos para llamar a los métodos API después de recibir un autentificador.

Para realizar llamadas con los métodos API disponibles:

  • En el encabezado HTTP, establezca Authorization: Bearer <token>.
  • Al utilizar la autenticación JWT (Service Account), debe proporcionar el encabezado x-api-key, que será el mismo que el client_id. Puede obtener su client_id desde la página Integración con Adobe I/O.
  • Llame al método API requerido.

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. Configure 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. Inicios de numeración en 0.
pageSize Define el número de resultados de respuesta que devuelve la solicitud (10 es el valor predeterminado).
sortBy Ordena y devuelve 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 buscar resultados para todos los modelos que tienen la palabra "Prueba" en cualquiera de los campos de valor para ese elemento. Su solicitud de muestra podría tener este aspecto: GET https://aam.adobe.io/v1/models/?search=Test. Puede buscar cualquier valor devuelto por un 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 basada en el permiso especificado. READ es el valor predeterminado. Los permisos incluyen:
  • READ :: Información de retorno y vista sobre un segmento.
  • WRITE :: Se utiliza PUT para actualizar un segmento.
  • CREATE :: Se utiliza POST para crear un segmento.
  • DELETE : Eliminar un segmento. Requiere acceso a las características subyacentes, si las hay. Por ejemplo, necesitará derechos para eliminar las características que pertenecen a un segmento si desea eliminarlo.

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

Una nota sobre las opciones de página

Cuando la información de página no se especifica, la solicitud devuelve JSON sin formato da como resultado una matriz. Si la información de página está especificada, la lista devuelta se envuelve en un objeto JSON que contiene información sobre el resultado total y la página actual. La solicitud de muestra con opciones de página podría tener un aspecto similar a este:

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 lista la solicitud URLs utilizada 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 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 APIs proporcionan acceso a diferentes entornos de trabajo. Estos entornos le ayudan a probar el código con bases de datos independientes sin afectar a los datos de producción activos. La siguiente tabla lista 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 autenticación JWT Nombre de host para 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 de forma regular. Una nueva versión incrementa el número de versión API. En la solicitud URL se hace referencia al número de versión 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 el Audience Manager REST API.

ID del código de respuesta Texto de respuesta Definición
200 OK La solicitud se procesó correctamente. Devolverá el contenido o los datos esperados si es necesario.
201 Created Se creó el recurso. Devuelve para solicitudes PUT y POST.
204 No Content Se eliminó el recurso. El cuerpo de la respuesta estará en blanco.
400 Bad Request El servidor no entendía la solicitud. Generalmente debido a una sintaxis mal formada. Compruebe su 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 le impedía cumplir la solicitud.

En esta página