Autenticación y acceso a las API de Experience Platform
Este documento proporciona un tutorial paso a paso para obtener acceso a una cuenta de desarrollador de Adobe Experience Platform con el fin de realizar llamadas a las API de Experience Platform. Al final de este tutorial, habrá generado o recopilado las siguientes credenciales que se requieren como encabezados en todas las llamadas a la API de Platform:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
{SANDBOX_NAME}
válido como encabezado. Consulte la descripción general de las zonas protegidas para obtener más información sobre las zonas protegidas y la documentación de extremo de administración de la zona protegida para obtener información sobre cómo enumerar las zonas protegidas disponibles para su organización.Para mantener la seguridad de sus aplicaciones y usuarios, todas las solicitudes a las API de Experience Platform deben autenticarse y autorizarse utilizando estándares como OAuth.
Este tutorial explica cómo recopilar las credenciales necesarias para autenticar las llamadas a la API de Platform, tal 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.
Requisitos previos prerequisites
Para realizar llamadas correctamente a las API de Experience Platform, debe tener lo siguiente:
- Una organización con acceso a Adobe Experience Platform.
- Un Admin Console que puede agregarle como desarrollador y como usuario de un perfil de producto.
- Un Experience Platform del sistema que puede otorgarle los controles de acceso basados en atributos necesarios para realizar operaciones de lectura o escritura en diferentes partes de Experience Platform a través de API.
También debe disponer de un Adobe ID para completar este tutorial. Si no tiene una Adobe ID, puede crearla siguiendo estos pasos:
- Ir a Adobe Developer Console.
- Seleccione Crear una nueva cuenta.
- Complete el proceso de registro.
Obtener acceso de desarrollador y usuario para Experience Platform gain-developer-user-access
Antes de crear integraciones en Adobe Developer Console, la cuenta debe tener permisos de desarrollador y usuario para un perfil de producto de Experience Platform en Adobe Admin Console.
Obtener acceso de desarrollador gain-developer-access
Póngase en contacto con un administrador de Admin Console de su organización para agregarlo como desarrollador a un perfil de producto de Experience Platform mediante Admin Console. Consulte la documentación de Admin Console para obtener instrucciones específicas sobre cómo administrar el acceso de desarrollador para perfiles de producto.
Una vez que se le asigne como desarrollador, puede empezar a crear integraciones en Adobe Developer Console. Estas integraciones son una canalización de aplicaciones y servicios externos a las API de Adobe.
Obtener acceso de usuario gain-user-access
El administrador de Admin Console también debe agregarlo a usted como usuario al mismo perfil de producto. Con el acceso de los usuarios, puede ver en la interfaz de usuario el resultado de las operaciones de API que realiza.
Consulte la guía sobre administración de grupos de usuarios en Admin Console para obtener más información.
Generación de una clave de API (ID de cliente) y un ID de organización generate-credentials
Después de que se le haya concedido acceso de desarrollador y usuario a Platform mediante Admin Console, el siguiente paso es generar sus credenciales de {ORG_ID}
y {API_KEY}
en Adobe Developer Console. Estas credenciales solo deben generarse una vez y pueden reutilizarse en futuras llamadas a la API de Platform.
Añadir un Experience Platform a un proyecto add-platform-to-project
Vaya a la consola de desarrollador de Adobe 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 Adobe Developer Console.
Una vez que haya creado un nuevo proyecto, seleccione Agregar API en la pantalla Información general del proyecto.
Aparece la pantalla Añadir una API. Seleccione el icono de producto para Adobe Experience Platform y, a continuación, seleccione API de Experience Platform antes de seleccionar Siguiente.
Seleccione el tipo de autenticación OAuth Server-to-Server select-oauth-server-to-server
A continuación, seleccione el tipo de autenticación OAuth Server-to-Server para generar tokens de acceso y acceder a la API de Experience Platform.
Selección de los perfiles de producto para la integración select-product-profiles
En la pantalla Configurar API, seleccione AEP-Default-All-Users.
Seleccione Guardar la API configurada cuando esté listo.
En el tutorial de vídeo siguiente también se muestra una descripción detallada de los pasos descritos anteriormente para configurar una integración con la API de Experience Platform:
Recopilar credenciales gather-credentials
Una vez agregada la API al proyecto, la página API de Experience Platform del proyecto muestra las siguientes credenciales, que son necesarias en todas las llamadas a las API de Experience Platform:
{API_KEY}
(ID de cliente){ORG_ID}
(ID de organización)
Generación de un token de acceso generate-access-token
El siguiente paso es generar una credencial {ACCESS_TOKEN}
para usarla en llamadas a la API de Platform. A diferencia de los valores de {API_KEY}
y {ORG_ID}
, se debe generar un nuevo token cada 24 horas para seguir usando las API de Platform. Seleccione Generar token de acceso, como se muestra a continuación.
[Obsoleto]{class="badge informative"} Generar un token web JSON (JWT) jwt
El siguiente paso es generar un token web JSON (JWT) basado en las credenciales de la cuenta. Este valor se usa para generar la credencial {ACCESS_TOKEN}
para su uso en llamadas a la API de Platform, que deben regenerarse cada 24 horas.
note important |
---|
IMPORTANT |
Para los fines de este tutorial, los pasos siguientes describen cómo generar un JWT en Developer Console. Sin embargo, este método de generación solo debe utilizarse con fines de prueba y evaluación. |
Para un uso normal, el JWT debe generarse automáticamente. Para obtener más información sobre cómo generar JWT mediante programación, consulte la guía de autenticación de cuenta de servicio en Adobe Developer. |
Seleccione Cuenta de servicio (JWT) en el panel de navegación izquierdo y, a continuación, seleccione Generar JWT.
En el cuadro de texto que aparece en Generar JWT personalizado, pegue el contenido de la clave privada que generó anteriormente al agregar la API de Platform a su cuenta de servicio. A continuación, seleccione Generar token.
La página se actualiza para mostrar el JWT generado, junto con un ejemplo de comando cURL que le permite generar un token de acceso. Para los propósitos de este tutorial, seleccione Copiar junto a JWT generado para copiar el token en su portapapeles.
Generar un token de acceso
Una vez que haya generado un JWT, puede utilizarlo en una llamada de API para generar su {ACCESS_TOKEN}
. A diferencia de los valores de {API_KEY}
y {ORG_ID}
, se debe generar un nuevo token cada 24 horas para seguir usando las API de Platform.
Solicitud
La siguiente solicitud genera un nuevo {ACCESS_TOKEN}
basado en las credenciales proporcionadas en la carga útil. Este extremo solo acepta datos de formulario como carga útil y, por lo tanto, debe recibir un encabezado Content-Type
de multipart/form-data
.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propiedad | Descripción |
{API_KEY} |
El {API_KEY} (ID de cliente) que recuperó en un paso anterior. |
{SECRET} |
Secreto de cliente que recuperó en un paso anterior. |
{JWT} |
El JWT que generó en un paso anterior. |
note note |
---|
NOTE |
Puede utilizar la misma clave de API, secreto de cliente y JWT para generar un nuevo token de acceso para cada sesión. Esto le permite automatizar la generación de tokens de acceso en las aplicaciones. |
Respuesta
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propiedad | Descripción |
token_type |
El tipo of token devuelto. Para tokens de acceso, este valor siempre es bearer . |
access_token |
El {ACCESS_TOKEN} generado. Este valor, con el prefijo Bearer , es necesario como encabezado Authentication para todas las llamadas a la API de Platform. |
expires_in |
Número de milisegundos que restan hasta que caduque el token de acceso. Una vez que este valor alcanza 0, se debe generar un nuevo token de acceso para seguir utilizando las API de Platform. |
Probar credenciales de acceso test-credentials
Una vez que haya recopilado las tres credenciales necesarias (token de acceso, clave de API e ID de organización) , puede intentar realizar la siguiente llamada de API. Esta llamada enumera todas las clases estándar Experience Data Model (XDM) disponibles para su organización. Importe y ejecute la llamada en Postman.
Solicitud
curl -X GET https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
-H 'Accept: application/vnd.adobe.xed-id+json' \
-H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
-H 'x-api-key: {{API_KEY}}' \
-H 'x-gw-ims-org-id: {{ORG_ID}}'
Respuesta
Si su respuesta es similar a la que se muestra a continuación, sus credenciales son válidas y funcionan. (Esta respuesta se ha truncado para el espacio).
{
"results": [
{
"title": "XDM ExperienceEvent",
"$id": "https://ns.adobe.com/xdm/context/experienceevent",
"meta:altId": "_xdm.context.experienceevent",
"version": "1"
},
{
"title": "XDM Individual Profile",
"$id": "https://ns.adobe.com/xdm/context/profile",
"meta:altId": "_xdm.context.profile",
"version": "1"
}
]
}
Obtenga los permisos de control de acceso basados en atributos necesarios get-abac-permissions
Para acceder o modificar varios recursos dentro de Experience Platform, debe tener los permisos de control de acceso adecuados. Los administradores del sistema pueden otorgarle los permisos que necesita. Obtenga más información en la sección acerca de administrar credenciales de API para un rol.
Encontrará información detallada sobre cómo un administrador del sistema puede conceder los permisos necesarios para acceder a los recursos de la plataforma a través de la API en el siguiente tutorial de vídeo:
Usar Postman para autenticar y probar llamadas a la API use-postman
Postman es una herramienta popular que permite a los desarrolladores explorar y probar las API de RESTful. Puede utilizar las colecciones y los entornos de Experience Platform Postman para acelerar el trabajo con las API de Experience Platform. Obtenga más información sobre el uso de Postman en Experience Platform y la introducción a las colecciones y los entornos.
Encontrará información detallada sobre el uso de Postman con colecciones y entornos de Experience Platform en los videotutoriales que se muestran a continuación:
Descargar e importar un entorno de Postman para utilizarlo con las API de Experience Platform
Use una colección de Postman para generar tokens de acceso
Descargue la colección Postman del servicio Identity Management y vea el siguiente vídeo para aprender a generar tokens de acceso.
Descargue colecciones Postman de API de Experience Platform e interactúe con las API
Administradores del sistema: Conceder control de acceso a API y desarrollador con permisos de Experience Platform grant-developer-and-api-access-control
Antes de crear integraciones en Adobe Developer Console, la cuenta debe tener permisos de desarrollador y usuario para un perfil de producto de Experience Platform en Adobe Admin Console.
Añadir desarrolladores al perfil del producto add-developers-to-product-profile
Vaya a Admin Console e inicie sesión con su Adobe ID.
Seleccione Productos y después seleccione Adobe Experience Platform de la lista de productos.
En la ficha Perfiles de producto, seleccione AEP-Default-All-Users. También puede utilizar la barra de búsqueda para buscar el perfil del producto introduciendo el nombre.
Seleccione la ficha Desarrolladores y luego seleccione Agregar desarrollador.
Escriba el correo electrónico o nombre de usuario del desarrollador. Un correo electrónico o nombre de usuario válido mostrará los detalles del desarrollador. Seleccione Guardar.
El desarrollador se ha agregado correctamente y aparece en la ficha Desarrolladores.
Asignar API a un rol
Un administrador del sistema puede asignar API a funciones en la interfaz de usuario del Experience Platform.
Seleccione Permisos y la función a la que desee agregar la API. Seleccione la ficha Credenciales de API y, a continuación, seleccione Agregar credenciales de API.
Seleccione la API que desee agregar al rol y luego seleccione Guardar.
Se le devuelve a la ficha Credenciales de API, donde se enumera la API recién agregada.
Recursos adicionales additional-resources
Consulte los recursos adicionales vinculados a continuación para obtener más ayuda sobre la introducción a las API de Experience Platform
Pasos siguientes next-steps
Al leer este documento, ha recopilado y probado correctamente sus credenciales de acceso para las API de Platform. Ahora puede seguir junto con las llamadas de API de ejemplo proporcionadas a lo largo de documentación.
Además de los valores de autenticación recopilados en este tutorial, muchas API de Platform también requieren que se proporcione un {SANDBOX_NAME}
válido como encabezado. Consulte la información general sobre las zonas protegidas para obtener más detalles.