Show Menu
TEMAS×

Getting Started with REST APIs

Information about general requirements, authentication, optional query parameters, request URLs, and other references.

Requisitos y recomendaciones de API

Cosas que debes y debes hacer cuando trabajas con Audience Manager los APIs.
Tenga en cuenta lo siguiente al trabajar con código de 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 tokens de E/S de Adobe, debe proporcionar el x-api-key encabezado. Puede obtener la API clave siguiendo las instrucciones de la página Integración de cuentas de servicio.
  • JSONtipo de contenido: Especifique content-type: application/json y ** accept: application/json en el código.
  • Solicitudes y respuestas: Enviar solicitudes como un JSON objeto con el formato correcto. Audience Manager responde con datos con JSON formato. 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á 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 con su propio código, parámetros u otra información requerida.

Autenticación

Los Audience Manager​REST APIs dos métodos de autenticación son compatibles.
Según el método de autenticación, debe ajustar la solicitud URLs en consecuencia. Consulte la sección Entornos para obtener más información sobre los nombres de host que debe utilizar.

JWT (Service Account) Autenticación mediante E/S de Adobe

Información general de E/S de Adobe

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 JWT la autenticación, asegúrese de tener acceso a la consola de desarrollador de Adobe en E/S de Adobe. 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 JWT (Service Account) autenticación mediante Adobe I/O:
  1. Inicie sesión en Adobe Developer Console .
  2. Siga los pasos de la Conexión de cuenta de servicio .
  3. Pruebe la conexión realizando la primera API llamada según las instrucciones del paso 3 .
Para configurar y trabajar con el Audience Manager de forma automatizada, puede generar el REST APIs JWT programa de forma automática. Consulte Autenticación JWT (cuenta de servicio) para obtener instrucciones detalladas.

OAuth Autenticación (obsoleto)

Audience Manager REST API la autenticación y renovación de token mediante OAuth 2.0 ahora está en desuso.
Utilice la autenticación #jwt-service-account-authentication-jwt JWT (cuenta de servicio) en su lugar.
El Audience Manager sistema REST API cumple OAuth 2.0 los estándares de autenticación y renovación de testigos. Las secciones siguientes describen cómo autenticar y inicio el trabajo con APIs.

Crear un usuario API genérico

Le recomendamos que cree una cuenta de usuario técnica independiente para trabajar con Audience Manager los APIinformes. 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 API usuario le ayuda a realizar dos tareas:
  • Identifique qué servicio llama a la API (p. ej., llamadas desde sus aplicaciones que usan nuestros APIo desde otras herramientas que realizan API solicitudes).
  • Proporcionar acceso ininterrumpido a los APIinformes. Una cuenta vinculada a una persona específica puede ser eliminada cuando abandone su compañía. Esto impedirá que trabaje con el API código 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 no específica que tenga las credenciales, la clave y el secreto adecuados para realizar API 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 APIde solo usuario.

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 JSON cliente en su explorador.
Cifre los tokens de acceso y actualícelos si los almacena en una base de datos.

Paso 1: Solicitar API acceso

Póngase en contacto con el administrador de soluciones de socio. Le proporcionarán un ID de API cliente y un secreto. El ID y el secreto le autentican en el API.
Nota: Si desea recibir un autentificador de actualización, especifíquelo cuando solicite API acceso.

Paso 2: Solicitar el token

Pasa una solicitud de token con tu JSON cliente preferido. Al generar 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 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 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 JSON 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 expires_in clave 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 API el acceso 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á un encabezado 401 Status Code y el siguiente en la respuesta:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
Los pasos siguientes describen el flujo de trabajo para utilizar un token de actualización para crear un nuevo token de acceso desde un JSON cliente en el explorador.

Paso 1: Solicitar el nuevo token

Pasa una solicitud de token de actualización con el JSON cliente preferido. Al generar 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 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 JSON respuesta 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 para https://api.demdex.com/oauth/authorize obtener acceso y actualizar los tokens.

Realizar solicitudes autenticadas API

Requisitos para llamar a API métodos después de recibir un autentificador.
Para realizar llamadas con los API métodos disponibles:
  • En el HTTP encabezado, establezca Authorization: Bearer <token> .
  • Al utilizar la autenticación JWT (Service Account) Autenticación mediante E/S de Adobe JWT (Service Account), debe proporcionar el x-api-key encabezado, que será el mismo que el client_id . Puede obtener información client_id desde la página de integración de E/S de Adobe.
  • Llame al API método requerido.

Parámetros API de Consulta 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 API métodos que devuelven todas las propiedades de un objeto. Configure estas opciones en la cadena de solicitud al pasar esa consulta al 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 JSON propiedad 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 solo con READ y WRITE permisos, pase "permissions":"READ" , "permissions":"WRITE" .
includePermissions
(Boolean) Establezca en para true devolver los permisos para el segmento. El valor predeterminado es false .

Una nota sobre las opciones de página

Cuando no se especifica la información de la página , la solicitud devuelve JSON resultados sencillos en una matriz. Si se especifica la información de la página, la lista devuelta se envuelve en un JSON objeto 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.

Solicitud URLs de 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 de 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

Los Audience Manager dos APIofrecen 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 API entornos 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 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/...
El entorno Audience Manager beta 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 APIinformes se publican con regularidad. Una nueva versión incrementa el número de la API versión. Se hace referencia al número de versión en la solicitud URL como v<version number> 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.
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 PUT y POST solicitudes.
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.