Introducción con 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 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: cuando se usa Adobe Developer tokens, debe proporcionar la variable x-api-key encabezado. Puede obtener su API siguiendo las instrucciones de la sección Integración de cuentas de servicio página.
  • JSONtipo de contenido: Especifique content-type: application/json y accept: application/json en su código.
  • Solicitudes y respuestas: Enviar solicitudes 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 le proporcionará un ID de cliente y una clave que le permitirán hacer API solicitudes.
  • Documentación y ejemplos de código: Texto en cursiva representa una variable que se proporciona o pasa al realizar o recibir API datos. Reemplazar cursiva texto con su propio código, parámetros u otra información requerida.

Autenticación

La variable Audience Manager REST APIs admiten dos métodos de autenticación.

IMPORTANTE

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

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 configurar JWT autenticación, asegúrese de tener acceso a la Consola de Adobe Developer en Adobe Developer. Póngase en contacto con el administrador de su organización para solicitar acceso.

Autenticación

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

  1. Inicie sesión en la Consola de Adobe Developer.
  2. Siga los pasos indicados en Conexión de cuenta de servicio.
  3. Pruebe la conexión realizando la primera API realice una llamada según las instrucciones de Paso 3.
NOTA

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

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

    cuenta técnica

  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 (obsoleto)

ADVERTENCIA

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

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

La variable Audience Manager REST API following 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 el APIs.

Crear un genérico API Usuario

Le recomendamos que cree una cuenta de usuario técnica independiente para trabajar con el 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 API la cuenta de usuario de ayuda a realizar dos tareas:

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

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

Flujo de trabajo de autenticación de contraseña

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

SUGERENCIA

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

Paso 1: Solicitud API Acceso

Póngase en contacto con el administrador de soluciones de socios. Le proporcionarán un 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 que cuando lo solicite API acceso.

Paso 2: Solicitar el token

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

  • Utilice un POST método para llamar 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 convertir a dGVzdElkOnRlc3RTZWNyZXQ=.
  • Pasa 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

La variable JSON La respuesta 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 variable 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

Actualizar la renovación de tokens API después de que caduque el token original. Si se solicita, la respuesta JSON en el 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á una 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 JSON en su explorador.

Paso 1: Solicitar el nuevo token

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

  • Utilice un POST método para llamar 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 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 la variable 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 variable JSON contiene su 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

La variable 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.

Autenticar API Solicitudes

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

Para realizar llamadas con los disponibles API métodos:

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 all propiedades de un objeto. Establezca estas opciones en la cadena de solicitud al pasar esa consulta a la variable 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 el valor especificado JSON propiedad.
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 por un "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 : Uso PUT para actualizar un segmento.
  • CREATE : Uso 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 READ y WRITE solo permisos, pasar "permissions":"READ", "permissions":"WRITE" .
includePermissions (Boolean) Establecer en true para devolver los permisos del segmento. El valor predeterminado es false.

Una Nota Sobre Las Opciones De Página

Cuando la información de la página no es especificado, la solicitud devuelve sin formato JSON genera una matriz. Si la información de la página es especificado, la lista devuelta se ajusta en un JSON objeto 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 tabla siguiente muestra la solicitud URLs usado para pasar API por método.

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

Solicitud URLs para JWT Autenticación

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/

Solicitud URLs para OAuth Autenticación (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

La variable 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 tabla siguiente muestra las API entornos y 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 JWT autenticación Nombre de host para OAuth autenticación
Producción https://aam.adobe.io/... https://api.demdex.com/...
Beta https://aam-beta.adobe.io/... https://api-beta.demdex.com/...
NOTA

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

Versiones

Nuevas versiones de estas APILos informes se publican con regularidad. Una nueva versión incrementa la variable API número de versión. 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 devueltos por la variable 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 PUT y POST solicitudes.
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