验证和访问 Experience Platform API
此文档分步说明了如何获取 Adobe Experience Platform 开发人员帐户访问权限以调用 Experience Platform API。在本教程结束时,您将生成或收集了所有平台API调用中作为标头所需的以下凭据:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
为了维护应用程序和用户的安全,所有对Experience PlatformAPI的请求都必须使用OAuth等标准进行身份验证和授权。
本教程介绍如何收集验证Platform API调用所需的凭据,如下面的流程图中所述。 您可以在初始一次性设置中收集大多数所需的凭据。 但是,必须每24小时刷新一次访问令牌。
先决条件 prerequisites
要成功调用Experience PlatformAPI,您必须具备以下条件:
- 有权访问Adobe Experience Platform的组织。
- 能够将您添加为产品配置文件的开发人员和用户的Admin Console管理员。
- Experience Platform系统管理员,可为您授予必要的基于属性的访问控制,以通过API对Experience Platform的各个部分执行读取或写入操作。
您还必须拥有Adobe ID才能完成本教程。 如果您没有Adobe ID,则可以使用以下步骤创建一个:
- 转到 Adobe Developer控制台.
- 选择 创建新帐户.
- 完成注册过程。
获得Experience Platform的开发人员和用户访问权限 gain-developer-user-access
在Adobe Developer控制台上创建集成之前,您的帐户必须具有Adobe Admin Console中Experience Platform产品配置文件的开发人员和用户权限。
获取开发人员访问权限 gain-developer-access
联系 Admin Console 管理员将您作为开发人员添加到Experience Platform产品配置文件中 Admin Console. 请参阅 Admin Console 文档,以了解关于如何 管理产品配置文件的开发人员访问权限.
一旦您被分配为开发人员,您就可以开始在中创建集成 Adobe Developer控制台. 这些集成是从外部应用程序和服务到AdobeAPI的管道。
获得用户访问权限 gain-user-access
您的 Admin Console 管理员还必须将您作为用户添加到同一产品配置文件。 凭借用户访问权限,您可以在UI中查看您执行的API操作的结果。
请参阅指南,网址为 在中管理用户组 Admin Console 以了解更多信息。
生成API密钥(客户端ID)和组织ID generate-credentials
在您通过获得对Platform的开发人员和用户访问权限后 Admin Console,下一步是生成 {ORG_ID}
和 {API_KEY}
Adobe Developer控制台中的凭据。 这些凭据只需生成一次,可在以后的Platform API调用中重复使用。
将Experience Platform添加到项目 add-platform-to-project
转到 Adobe Developer控制台 然后使用您的Adobe ID登录。 接下来,按照教程中概述的以下步骤进行操作: 创建空项目 在Adobe Developer Console文档中。
创建新项目后,选择 添加API 在 项目概述 屏幕。
此 添加API 屏幕。 选择Adobe Experience Platform的产品图标,然后选择 EXPERIENCE PLATFORMAPI 选择之前 下一个.
选择OAuth服务器到服务器身份验证类型 select-oauth-server-to-server
接下来,选择身份验证类型以生成访问令牌并访问Experience PlatformAPI。
为您的集成选择产品配置文件 select-product-profiles
在 配置API 屏幕,选择 AEP-Default-All-Users.
选择 保存配置的API 准备就绪后。
以下视频教程中也提供了上述步骤的演练,以设置与Experience PlatformAPI的集成:
收集凭据 gather-credentials
将API添加到项目后, EXPERIENCE PLATFORMAPI 项目页面显示所有Experience PlatformAPI调用所需的以下凭据:
{API_KEY}
(客户端ID){ORG_ID}
(组织 ID)
生成访问令牌 generate-access-token
下一步是生成 {ACCESS_TOKEN}
用于平台API调用的凭据。 与的值不同 {API_KEY}
和 {ORG_ID}
,必须每24小时生成一个新令牌才能继续使用平台API。 选择 生成访问令牌,如下所示。
已弃用生成JSON Web令牌(JWT) jwt
下一步是根据您的帐户凭据生成JSON Web令牌(JWT)。 此值用于生成 {ACCESS_TOKEN}
用于平台API调用的凭据,必须每24小时重新生成一次。
note important |
---|
IMPORTANT |
在本教程中,以下步骤概述了如何在开发人员控制台中生成JWT。 但是,这种生成方法只应用于测试和评估目的。 |
对于常规使用,必须自动生成JWT。 有关如何以编程方式生成JWT的更多信息,请参阅 服务帐户身份验证指南 在Adobe Developer上。 |
选择 服务帐户(JWT) 在左侧导航中,然后选择 生成JWT.
在以下位置提供的文本框中: 生成自定义JWT,粘贴您之前在将平台API添加到服务帐户时生成的私钥的内容。 然后,选择 生成令牌.
页面将更新以显示生成的JWT,以及一个允许您生成访问令牌的示例cURL命令。 在本教程中,选择 复制 旁边 生成的JWT 以将令牌复制到剪贴板。
生成访问令牌
生成JWT后,您可以在API调用中使用它来生成 {ACCESS_TOKEN}
. 与的值不同 {API_KEY}
和 {ORG_ID}
,必须每24小时生成一个新令牌才能继续使用平台API。
请求
以下请求生成一个新的 {ACCESS_TOKEN}
基于有效负载中提供的凭据。 此端点仅接受表单数据作为其有效负载,因此必须为 Content-Type
页眉 multipart/form-data
.
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
属性 | 描述 |
{API_KEY} |
此 {API_KEY} (客户端ID)中检索到的值 上一步. |
{SECRET} |
您在中检索到的客户端密码 上一步. |
{JWT} |
您在中生成的JWT 上一步. |
note note |
---|
NOTE |
您可以使用相同的API密钥、客户端密钥和JWT为每个会话生成新的访问令牌。 这允许您在应用程序中自动生成访问令牌。 |
响应
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
属性 | 描述 |
token_type |
类型 of 正在返回令牌。 对于访问令牌,此值始终为 bearer . |
access_token |
生成的 {ACCESS_TOKEN} . 此值,以单词为前缀 Bearer ,必须作为 Authentication 所有平台API调用的标头。 |
expires_in |
访问令牌过期前剩余的毫秒数。 一旦此值达到0,必须生成新的访问令牌才能继续使用平台API。 |
测试访问凭据 test-credentials
收集完所有三个所需的凭据(访问令牌、API密钥和组织ID)后,您可以尝试进行以下API调用。 此调用列出了所有标准 Experience Data Model (XDM)类可供您的组织使用。 在中导入并执行调用 Postman.
请求
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}}'
响应
如果您的响应与下面显示的响应类似,则您的凭据有效且有效。 (此响应已因空间而被截断。)
{
"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"
}
]
}
获取必要的基于属性的访问控制权限 get-abac-permissions
要访问或修改Experience Platform中的多个资源,您必须具有相应的访问控制权限。 系统管理员可以向您授予 所需的权限. 在部分中获取有关 管理角色的API凭据.
以下视频教程中也提供了有关系统管理员如何授予通过API访问Platform资源所需的权限的详细信息:
使用Postman验证和测试API调用 use-postman
Postman 是一个常用的工具,它允许开发人员探索和测试RESTful API。 您可以使用Experience PlatformPostman收藏集和环境来加速使用Experience PlatformAPI。 详细了解 在Experience Platform中使用Postman 以及收藏集和环境的快速入门。
以下视频教程中也提供了有关将Postman与Experience Platform集合和环境结合使用的详细信息:
下载并导入要与Experience PlatformAPI一起使用的Postman环境
使用Postman收藏集生成访问令牌
下载 Identity Management服务Postman收藏集 并观看以下视频,了解如何生成访问令牌。
下载Experience PlatformAPI Postman收藏集并与API交互
系统管理员:通过Experience Platform权限授予开发人员和API访问控制 grant-developer-and-api-access-control
在Adobe Developer控制台上创建集成之前,您的帐户必须具有Adobe Admin Console中Experience Platform产品配置文件的开发人员和用户权限。
将开发人员添加到产品配置文件 add-developers-to-product-profile
转至Admin Console并使用您的 Adobe ID 登录。
选择 产品,然后选择 Adobe Experience Platform 从产品列表中。
从 产品配置文件 选项卡,选择 AEP-Default-All-Users. 或者,使用搜索栏通过输入名称来搜索产品配置文件。
选择 开发人员 选项卡,然后选择 添加开发人员.
输入开发人员的 电子邮件或用户名. 有效的 电子邮件或用户名 将显示开发人员详细信息。 选择 保存。
开发人员已成功添加,并显示在 开发人员 选项卡。
将API分配给角色
系统管理员可以在Experience PlatformUI中将API分配给角色。
选择 权限 以及要将API添加到的角色。 选择 API凭据 选项卡,然后选择 添加API凭据.
选择要添加到角色的API,然后选择 保存.
您将返回 API凭据 选项卡,其中列出了新添加的API。
其他资源 additional-resources
请参阅下面链接的其他资源,以获取开始使用Experience PlatformAPI的更多帮助
后续步骤 next-steps
通过阅读本文档,您已收集并成功测试您的Platform API访问凭据。 现在,您可以遵循在整个过程中提供的示例API调用 文档.
除了您在本教程中收集的身份验证值之外,许多Platform API还需要有效的 {SANDBOX_NAME}
将作为标头提供。 有关更多信息,请参阅沙盒概述。