验证和访问 Experience Platform API
此文档分步说明了如何获取Adobe Experience Platform开发人员帐户访问权限以调用Experience PlatformAPI。 在本教程结束时,您将生成或收集了所有平台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 Console。
- 选择 创建新帐户。
- 完成注册过程。
获得Experience Platform的开发人员和用户访问权限 gain-developer-user-access
在Adobe Developer Console上创建集成之前,您的帐户必须具有Adobe Admin Console中Experience Platform产品配置文件的开发人员和用户权限。
获取开发人员访问权限 gain-developer-access
请联系贵组织的Admin Console管理员,以使用Admin Console将您作为开发人员添加到Experience Platform产品配置文件中。 有关如何管理产品配置文件的开发人员访问权限的特定说明,请参阅Admin Console文档。
一旦您被指定为开发人员,就可以开始在Adobe Developer Console中创建集成。 这些集成是从外部应用程序和服务到AdobeAPI的管道。
获得用户访问权限 gain-user-access
您的Admin Console管理员还必须将您作为用户添加到同一产品配置文件。 凭借用户访问权限,您可以在UI中查看您执行的API操作的结果。
有关详细信息,请参阅在 Admin Console中管理用户组的指南。
生成API密钥(客户端ID)和组织ID generate-credentials
在通过Admin Console授予您开发人员和用户访问Platform的权限后,下一步是在Adobe Developer Console中生成您的{ORG_ID}
和{API_KEY}
凭据。 这些凭据只需生成一次,可在以后的Platform API调用中重复使用。
将Experience Platform添加到项目 add-platform-to-project
转到Adobe Developer Console并使用您的Adobe ID登录。 接下来,按照Adobe Developer Console文档中有关创建空项目的教程中概述的步骤进行操作。
创建新项目后,请在 项目概述 屏幕上选择 添加API。
突出显示了“添加API”选项的
出现 添加API 屏幕。 选择Adobe Experience Platform的产品图标,然后选择 Experience PlatformAPI,然后再选择 下一步。
选择OAuth服务器到服务器身份验证类型 select-oauth-server-to-server
接下来,选择OAuth服务器到服务器身份验证类型以生成访问令牌并访问Experience PlatformAPI。
为您的集成选择产品配置文件 select-product-profiles
在 配置API 屏幕中,选择 AEP-Default-All-Users。
准备就绪后,选择 保存配置的API。
以下视频教程中也提供了上述步骤的演练,以设置与Experience PlatformAPI的集成:
收集凭据 gather-credentials
将API添加到项目后,项目的 Experience PlatformAPI 页面将显示所有调用Experience PlatformAPI时所需的以下凭据:
在Developer Consle中添加API后
{API_KEY}
(客户端ID){ORG_ID}
(组织ID)
生成访问令牌 generate-access-token
下一步是生成用于Platform API调用的{ACCESS_TOKEN}
凭据。 与{API_KEY}
和{ORG_ID}
的值不同,必须每24小时生成一个新令牌才能继续使用平台API。 选择 生成访问令牌,如下所示。
[已弃用]{class="badge negative"}生成JSON Web令牌(JWT) jwt
下一步是根据您的帐户凭据生成JSON Web令牌(JWT)。 此值用于生成您的{ACCESS_TOKEN}
凭据以用于Platform API调用,必须每24小时重新生成一次。
note important |
---|
IMPORTANT |
在本教程中,以下步骤概述了如何在Developer Console中生成JWT。 但是,这种生成方法只应用于测试和评估目的。 |
对于常规使用,必须自动生成JWT。 有关如何以编程方式生成JWT的更多信息,请参阅Adobe Developer上的服务帐户身份验证指南。 |
在左侧导航中选择 服务帐户(JWT),然后选择 生成JWT。
在 生成自定义JWT 下提供的文本框中,粘贴您之前在将平台API添加到服务帐户时生成的私钥的内容。 然后选择 生成令牌。
页面将更新以显示生成的JWT,以及一个允许您生成访问令牌的示例cURL命令。 在本教程中,请选择 生成的JWT 旁边的 复制 以将令牌复制到剪贴板。
生成访问令牌
生成JWT后,您可以在API调用中使用它来生成{ACCESS_TOKEN}
。 与{API_KEY}
和{ORG_ID}
的值不同,必须每24小时生成一个新令牌才能继续使用平台API。
请求
以下请求基于有效负载中提供的凭据生成新的{ACCESS_TOKEN}
。 此终结点仅接受表单数据作为其有效负载,因此必须为其指定multipart/form-data
的Content-Type
标头。
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} 。 此值作为所有Platform API调用的Authentication 标头是必需的,其前缀为Bearer 。 |
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 Console上创建集成之前,您的帐户必须具有Adobe Admin Console中Experience Platform产品配置文件的开发人员和用户权限。
将开发人员添加到产品配置文件 add-developers-to-product-profile
转到Admin Console并使用您的Adobe ID登录。
选择 产品,然后从产品列表中选择 Adobe Experience Platform。
Admin Console 上的产品列表
从 产品配置文件 选项卡中,选择 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}
作为标头。 有关更多信息,请参阅沙盒概述。