Introducción a REST APIs getting-started-with-rest-apis
Información sobre requisitos generales, autenticación, parámetros de consulta opcionales, solicitud URLsy otras referencias.
Requisitos de API y Recommendations api-requirements-recommendations
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
yaccept: 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 authentication
El Audience Manager REST APIs admite tres métodos de autenticación.
-
badge positive Recomendado Autenticación de servidor a servidor OAuth usando consola de desarrollador de Adobe. 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. Más información sobre Autenticación de servidor a servidor OAuth en la documentación para desarrolladores de Adobe.
-
badge negative Obsoleto Autenticación JWT (cuenta de servicio) usando consola de desarrollador de Adobe. Adobe Developer es el ecosistema y la comunidad de desarrolladores de Adobe. Incluye API para todos los productos de Adobe.
-
badge negative Obsoleto Autenticación OAuth heredada. Aunque este método esté obsoleto, los clientes con OAuth Las integraciones de pueden seguir utilizando este método.
Autenticación de servidor a servidor OAuth mediante Adobe Developer oauth-adobe-developer
Esta sección cubre cómo recopilar las credenciales necesarias para autenticar las llamadas a la API de Audience Manager, como se describe en el diagrama de flujo siguiente. Puede recopilar la mayoría de las credenciales necesarias en la configuración inicial única. Sin embargo, el token de acceso debe actualizarse cada 24 horas.
Información general de Adobe Developer developer-overview
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 prerequisites-server-to-server
Antes de poder configurar OAuth Server-to-Server 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 oauth
Siga los pasos a continuación para configurar OAuth Server-to-Server autenticación mediante Adobe Developer:
- Inicie sesión en Consola de Adobe Developer.
- Siga los pasos de la Guía de implementación de credenciales de servidor a servidor de OAuth.
- Durante Paso 2: Añadir una API al proyecto mediante la autenticación de cuenta de servicio, elija la Audience Manager API opción.
- Pruebe la conexión estableciendo la primera API llamada de basada en las instrucciones de Paso 3.
Añadir la API de Audience Manager a un proyecto add-aam-api-to-project
Ir a Consola de Adobe Developer e inicie sesión con su Adobe ID. A continuación, siga los pasos descritos en el tutorial sobre creación de un proyecto vacío en la documentación de la consola de Adobe Developer.
Una vez creado un nuevo proyecto, seleccione Add API en el Project Overview pantalla.
El Add an API aparece la pantalla. Seleccione el icono de producto de Adobe Experience Cloud y, a continuación, elija Audience Manager API antes de seleccionar Next.
Seleccione el tipo de autenticación de servidor a servidor OAuth select-oauth-server-to-server
A continuación, seleccione el tipo de autenticación para generar tokens de acceso y acceder a la API de Audience Manager.
Selección de los perfiles de producto para la integración select-product-profiles
En el Configure API , seleccione los perfiles de producto que desee. La cuenta de servicio de su integración obtendrá acceso a las funciones granulares a través de los perfiles de producto seleccionados aquí.
Seleccionar Save configured API cuando esté listo.
Recopilar credenciales gather-credentials
Una vez añadida la API al proyecto, la variable Audience Manager API Esta página del proyecto muestra las siguientes credenciales, necesarias en todas las llamadas a las API de Audience Manager:
{API_KEY}
(Client ID){ORG_ID}
(Organization ID)
Generación de un token de acceso generate-access-token
El siguiente paso es generar una {ACCESS_TOKEN}
credenciales para utilizarlas en llamadas a la API de Audience Manager. A diferencia de los valores para {API_KEY}
y {ORG_ID}
, se debe generar un nuevo token cada 24 horas para seguir utilizando las API de Audience Manager. Seleccionar Generate access token, como se muestra a continuación.
Prueba de una llamada API test-api-call
Después de obtener el token de portador de autenticación, realice una llamada a la API para probar que ahora puede acceder a las API de Audience Manager.
-
Seleccionar Authorize y pegue el token de acceso que obtuvo en la generar token de acceso paso.
-
Realice una llamada de GET a
/datasources
Punto final de API para recuperar una lista de todas las fuentes de datos disponibles globalmente, como se indica en la Documentación de referencia del API. Seleccionar Try it out, seguido de Execute, como se muestra a continuación.
code language-shell |
---|
|
Al utilizar un token de acceso de trabajo, el extremo de la API devuelve una respuesta 200, junto con un cuerpo de respuesta que incluye todas las fuentes de datos globales a las que su organización tiene acceso.
code language-json |
---|
|
ObsoletoJWT (Service Account) Autenticación mediante Adobe Developer jwt
Información general de Adobe Developer adobeio
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 prerequisites
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 auth
Siga los pasos a continuación para configurar JWT (Service Account) autenticación mediante Adobe Developer:
- Inicie sesión en Consola de Adobe Developer.
- 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.
- Pruebe la conexión estableciendo la primera API llamada de basada en las instrucciones de Paso 3.
note note |
---|
NOTE |
Para configurar y trabajar con Audience Manager REST APIs de forma automatizada, puede generar las JWT mediante programación. Consulte Autenticación JWT (cuenta de servicio) para obtener instrucciones detalladas. |
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:
-
Crear un
GET
llamada ahttps://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. -
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.
ObsoletoOAuth Autenticación (obsoleta) oauth-deprecated
note warning |
---|
WARNING |
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. |
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 requirements
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 password-authentication-workflow
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.
note tip |
---|
TIP |
Cifre los tokens de acceso y actualización si los almacena en una base de datos. |
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 llamarhttps://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 adGVzdElkOnRlc3RTZWNyZXQ=
. - Pase el HTTP headers
Authorization:Basic <base-64 clientID:clientSecret>
yContent-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:
code language-json |
---|
|
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 refresh-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 llamarhttps://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 adGVzdElkOnRlc3RTZWNyZXQ=
. - Pasar los encabezados HTTP
Authorization:Basic <base-64 clientID:clientSecret>
yContent-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:
code language-json |
---|
|
Código de autorización y autenticación implícita authentication-code-implicit
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 authenticated-api-requests
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, establecerAuthorization: Bearer <token>
. - Al utilizar Autenticación JWT (cuenta de servicio), debe proporcionar el
x-api-key
encabezado, que será el mismo que suclient_id
. Puede obtener suclient_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 optional-api-query-parameters
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.
page
pageSize
sortBy
descending
ascending
es el valor predeterminado.search
GET https://aam.adobe.io/v1/models/?search=Test
. Puede buscar cualquier valor devuelto por un "get allmétodo ".folderId
permissions
Devuelve una lista de segmentos en función del permiso especificado. READ
es el valor predeterminado. Los permisos incluyen:
READ
: Devuelve y ve información sobre un segmento.WRITE
: usoPUT
para actualizar un segmento.CREATE
: usoPOST
para crear un segmento.DELETE
: elimine un segmento. Requiere acceso a los rasgos subyacentes, si los hay. Por ejemplo, necesitará derechos para eliminar los rasgos que pertenecen a un segmento si desea eliminarlo.
Especifique varios permisos con pares clave-valor independientes. Por ejemplo, para devolver una lista de segmentos con READ
y WRITE
solo permisos, pasar "permissions":"READ"
, "permissions":"WRITE"
.
includePermissions
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 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 api-urls
URLs para solicitudes, entornos de ensayo y producción y versiones.
Solicitud URLs request-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 elRecomendadoObsoletoJWT Autenticación mediante Adobe Developer request-urls-jwt
https://aam.adobe.io/v1/models/
https://aam.adobe.io/v1/datasources/
https://aam.adobe.io/v1/signals/derived/
https://aam.adobe.io/v1/destinations/
https://aam.adobe.io/v1/partner-sites/
https://aam.adobe.io/v1/folders/traits /
Segmentos:
https://aam.adobe.io/v1/folders/segments /
https://aam.adobe.io/v1/schemas/
https://aam.adobe.io/v1/segments/
https://aam.adobe.io/v1/traits/
https://aam.adobe.io/v1/customer-trait-types
https://aam.adobe.io/v1/taxonomies/0/
Solicitud URLs para elObsoletoOAuth Autenticación request-urls-oauth
https://api.demdex.com/v1/models/
https://api.demdex.com/v1/datasources/
https://api.demdex.com/v1/signals/derived/
https://api.demdex.com/v1/destinations/
https://api.demdex.com/v1/partner-sites/
https://api.demdex.com/v1/folders/traits /
Segmentos:
https://api.demdex.com/v1/folders/segments /
https://api.demdex.com/v1/schemas/
https://api.demdex.com/v1/segments/
https://api.demdex.com/v1/traits/
https://api.demdex.com/v1/customer-trait-types
https://api.demdex.com/v1/taxonomies/0/
Entornos environments
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.
https://aam.adobe.io/...
https://api.demdex.com/...
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
Versiones versions
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 response-codes-defined
HTTP
códigos de estado y texto de respuesta devueltos por el Audience Manager REST API.
200
OK
201
Created
PUT
y POST
solicitudes.204
No Content
400
Bad Request
403
Forbidden
404
Not Found
409
Conflict
500
Server Error