快速入门 REST APIs getting-started-with-rest-apis
有关一般要求、身份验证、可选查询参数、请求的信息 URLs和其他引用。
API要求和Recommendations api-requirements-recommendations
使用时,请注意以下事项 AUDIENCE MANAGERAPI 代码:
- 请求参数: 除非另有指定,否则所有请求参数都是必需的。
- 请求标头:使用时 Adobe Developer 令牌,您必须提供
x-api-key
标题。 您可以获取 API 按照 服务帐户集成 页面。 - JSON内容类型: 指定
content-type: application/json
和accept: application/json
在您的代码中。 - 请求和响应: 以正确格式发送请求 JSON 对象。 Audience Manager 响应方式 JSON 带格式的数据。 服务器响应可以包含请求的数据、状态代码或同时包含这两者。
- 访问: 您的 Audience Manager 顾问将为您提供客户端ID和密钥,供您制作 API 请求。
- 文档和代码示例: 文本输入 斜体 表示在制作或接收时提供或传入的变量 API 数据。 替换 斜体 带有您自己的代码、参数或其他必需信息的文本。
身份验证 authentication
此 Audience Manager REST APIs 支持三种身份验证方法。
-
badge positive 推荐 OAuth服务器到服务器身份验证 使用 Adobe开发人员控制台. Adobe Developer 是Adobe的开发者生态系统和社区。 它包括 适用于所有Adobe产品的API. 这是设置和使用的推荐方式 Adobe APIs. 详细了解 OAuth服务器到服务器身份验证 在Adobe开发人员文档中。
-
badge negative 已弃用 JWT(服务帐户)身份验证 使用 Adobe开发人员控制台. Adobe Developer 是Adobe的开发者生态系统和社区。 它包括 适用于所有Adobe产品的API.
-
badge negative 已弃用 旧版OAuth身份验证. 虽然此方法已弃用,但具有现有 OAuth 集成可以继续使用此方法。
使用Adobe Developer的OAuth服务器到服务器身份验证 oauth-adobe-developer
本节介绍如何收集所需的凭据来验证Audience ManagerAPI调用,如下面的流程图中所述。 您可以在初始一次性设置中收集大多数所需的凭据。 但是,必须每24小时刷新一次访问令牌。
Adobe Developer概述 developer-overview
Adobe Developer 是Adobe的开发者生态系统和社区。 它包括 适用于所有Adobe产品的API.
这是设置和使用的推荐方式 Adobe APIs.
先决条件 prerequisites-server-to-server
在配置之前 OAuth Server-to-Server 身份验证,确保您有权访问 Adobe Developer控制台 在 Adobe Developer. 有关访问请求,请联系您的组织管理员。
身份验证 oauth
按照以下步骤配置 OAuth Server-to-Server 身份验证使用 Adobe Developer:
- 登录到 Adobe Developer控制台.
- 请按照 OAuth服务器到服务器凭据实施指南.
- 时段 步骤2:使用服务帐户身份验证将API添加到您的项目中,选择 Audience Manager API 选项。
- 尝试建立您的第一个连接 API 根据来自的指令调用 步骤3.
将Audience ManagerAPI添加到项目 add-aam-api-to-project
转到 Adobe Developer控制台 然后使用您的Adobe ID登录。 接下来,按照教程中概述的以下步骤进行操作: 创建空项目 在Adobe Developer Console文档中。
创建新项目后,选择 Add API 在 Project Overview 屏幕。
此 Add an API 屏幕。 选择Adobe Experience Cloud的产品图标,然后选择 Audience Manager API 选择之前 Next.
选择OAuth服务器到服务器身份验证类型 select-oauth-server-to-server
接下来,选择身份验证类型以生成访问令牌并访问Audience ManagerAPI。
为您的集成选择产品配置文件 select-product-profiles
在 Configure API 屏幕中,选择所需的产品配置文件。 通过此处所选的产品配置文件,您的集成服务帐户将获得对精细功能的访问权限。
选择 Save configured API 准备就绪后。
收集凭据 gather-credentials
将API添加到项目后, Audience Manager API 项目页面显示所有Audience ManagerAPI调用所需的以下凭据:
{API_KEY}
(Client ID){ORG_ID}
(Organization ID)
生成访问令牌 generate-access-token
下一步是生成 {ACCESS_TOKEN}
用于Audience ManagerAPI调用的凭据。 与的值不同 {API_KEY}
和 {ORG_ID}
,必须每24小时生成一个新令牌才能继续使用Audience ManagerAPI。 选择 Generate access token,如下所示。
测试API调用 test-api-call
获取身份验证持有者令牌后,执行API调用以测试您现在是否可以访问Audience ManagerAPI。
code language-shell |
---|
|
使用有效的访问令牌时,API端点会返回200响应以及包含您的组织有权访问的所有全局数据源的响应正文。
code language-json |
---|
|
已弃用JWT (Service Account)使用Adobe Developer进行身份验证 jwt
Adobe Developer概述 adobeio
Adobe Developer 是Adobe的开发者生态系统和社区。 它包括 适用于所有Adobe产品的API.
这是设置和使用的推荐方式 Adobe APIs.
先决条件 prerequisites
在配置之前 JWT 身份验证,确保您有权访问 Adobe Developer控制台 在 Adobe Developer. 有关访问请求,请联系您的组织管理员。
身份验证 auth
按照以下步骤配置 JWT (Service Account) 身份验证使用 Adobe Developer:
- 登录到 Adobe Developer控制台.
- 请按照中的步骤操作 服务帐户连接.
- 时段 步骤2:使用服务帐户身份验证将API添加到您的项目中,选择 Audience Manager API 选项。
- 尝试建立您的第一个连接 API 根据来自的指令调用 步骤3.
note note |
---|
NOTE |
配置和使用 Audience Manager REST APIs 通过自动化方式,您可以 JWT 以编程方式。 请参阅 JWT(服务帐户)身份验证 以获取详细说明。 |
技术帐户RBAC权限
如果您的Audience Manager帐户使用 基于角色的访问控制,您必须创建一个Audience Manager技术用户帐户,并将其添加到将进行API调用的Audience ManagerRBAC组。
按照以下步骤创建技术用户帐户并将其添加到RBAC组中:
-
创建
GET
调用https://aam.adobe.io/v1/users/self
. 呼叫将创建一个技术用户帐户,您可在中看到该帐户 Admin Console,在 Users 页面。 -
登录到您的Audience Manager帐户并 添加技术用户帐户 添加到将进行API调用的用户组。
已弃用OAuth 身份验证(已弃用) oauth-deprecated
note warning |
---|
WARNING |
Audience Manager REST API 令牌身份验证和续订方式 OAuth 2.0 现已弃用。 |
请使用 JWT(服务帐户)身份验证 而是。 |
此 Audience Manager REST API 关注 OAuth 2.0 令牌身份验证和续订标准。 以下各节介绍如何验证并开始使用 APIs.
创建通用 API 用户 requirements
我们建议您创建一个单独的技术用户帐户来使用 Audience Manager APIs.这是一个通用帐户,与您组织中的特定用户无关,也与特定用户相关联。 此类型 API 用户帐户可帮助您完成2件事:
- 识别哪种服务呼叫 API (例如,来自使用我们的应用程序的 API或从其他制作工具 API 请求)。
- 提供对的不间断访问 APIs.与特定人员关联的帐户可能会在他们离开您的公司时删除。 这会阻止您使用 API 代码。 不绑定到特定员工的通用帐户有助于避免此问题。
作为此类帐户的示例或用例,假设您想使用 批量管理工具. 要实现此目的,您的用户帐户需要 API 访问权限。 不要向特定用户添加权限,请创建非特定、 API 具有要生成的相应凭据、密钥和机密的用户帐户 API 呼叫。 如果您开发自己的应用程序,而这些应用程序又使用 Audience Manager APIs.
使用您的 Audience Manager 咨询师来设置通用, API-only用户帐户。
密码身份验证工作流 password-authentication-workflow
密码验证安全访问我们的 REST API. 以下步骤概述了密码身份验证的工作流 JSON 浏览器中的客户端。
note tip |
---|
TIP |
如果您将令牌存储在数据库中,则加密访问和刷新令牌。 |
步骤1:请求 API 访问
请联系您的合作伙伴解决方案经理。 他们将为您提供 API 客户端ID和密码。 此ID和密码用于验证您的 API.
注意:如果要接收刷新令牌,请在请求时指定 API 访问权限。
步骤2:请求令牌
使用您的首选传递令牌请求 JSON 客户。 构建请求时:
- 使用
POST
调用方法https://api.demdex.com/oauth/token
. - 将您的客户端ID和密码转换为base-64编码字符串。 在转换过程中使用冒号分隔ID和密码。 例如,凭据
testId : testSecret
转换为dGVzdElkOnRlc3RTZWNyZXQ=
. - 传入 HTTP headers
Authorization:Basic <base-64 clientID:clientSecret>
和Content-Type: application/x-www-form-urlencoded
. 例如,标题可能如下所示:Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
- 按如下方式设置请求正文:
grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>
步骤3:接收令牌
此 JSON 响应包含您的访问令牌。 响应应如下所示:
code language-json |
---|
|
此 expires_in
key表示访问令牌过期前的秒数。 作为最佳实践,如果令牌被公开,请使用较短的过期时间以限制泄露。
刷新令牌 refresh-token
刷新令牌续订 API 在原始令牌过期后访问。 如果要求,响应 JSON 在密码工作流中包含刷新令牌。 如果您没有收到刷新令牌,请通过密码身份验证过程创建一个新令牌。
您还可以使用刷新令牌在现有访问令牌过期之前生成新的令牌。
如果您的访问令牌已过期,您将收到 401 Status Code
和响应中的以下标头:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
以下步骤概述了使用刷新令牌从创建新访问令牌的工作流 JSON 浏览器中的客户端。
步骤1:请求新令牌
使用您的首选传递刷新令牌请求 JSON 客户。 构建请求时:
- 使用
POST
调用方法https://api.demdex.com/oauth/token
. - 将您的客户端ID和密码转换为base-64编码字符串。 在转换过程中使用冒号分隔ID和密码。 例如,凭据
testId : testSecret
转换为dGVzdElkOnRlc3RTZWNyZXQ=
. - 在HTTP标头中传递
Authorization:Basic <base-64 clientID:clientSecret>
和Content-Type: application/x-www-form-urlencoded
. 例如,标题可能如下所示:Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
- 在请求正文中,指定
grant_type:refresh_token
并传入您在上一个访问请求中收到的刷新令牌。 请求应当如下所示:grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
步骤2:接收新令牌
此 JSON 响应包含您的新访问令牌。 响应应如下所示:
code language-json |
---|
|
授权代码和隐式身份验证 authentication-code-implicit
此 Audience Manager REST API 支持授权代码和隐式身份验证。 要使用这些访问方法,您的用户需要登录到 https://api.demdex.com/oauth/authorize
以获取访问权限和刷新令牌。
进行身份验证 API 请求 authenticated-api-requests
呼叫要求 API 方法收到身份验证令牌后。
对可用发出调用 API 方法:
- 在
HTTP
标题,设置Authorization: Bearer <token>
. - 使用时 JWT(服务帐户)身份验证,您需要提供
x-api-key
标头,它将与您的client_id
. 您可以获取client_id
从 Adobe Developer集成 页面。 - 调用所需的 API 方法。
可选 API 查询参数 optional-api-query-parameters
设置可用于返回对象所有属性的方法的可选参数。
您可以将这些可选参数与 API 返回的方法 所有 对象的属性。 将查询传入到时,在请求字符串中设置这些选项 API.
page
pageSize
sortBy
descending
ascending
为默认值。search
GET https://aam.adobe.io/v1/models/?search=Test
. 您可以搜索“”返回的任何值get all”方法。folderId
permissions
根据指定的权限返回区段列表。 READ
为默认值。 权限包括:
READ
:返回并查看有关区段的信息。WRITE
:使用PUT
以更新区段。CREATE
:使用POST
以创建区段。DELETE
:删除区段。 需要访问基础特征(如果有)。 例如,如果要删除属于某个区段的特征,您需要拥有删除该区段的权限。
使用单独的键值对指定多个权限。 例如,要返回包含的区段列表, READ
和 WRITE
仅限权限,传入 "permissions":"READ"
, "permissions":"WRITE"
.
includePermissions
true
以返回您对该区段的权限。 默认为 false
.有关页面选项的注释
页面信息时间 不是 指定后,请求将返回 JSON 数组中的结果。 如果页面信息 是 指定,则返回的列表将封装在 JSON 包含有关总结果和当前页信息的对象。 使用页面选项的示例请求可能如下所示:
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test
API URLs api-urls
URLs 用于请求、暂存和生产环境以及版本。
请求 URLs request-urls
下表列出了请求 URLs 用于传入 API 请求,按方法。
根据您使用的身份验证方法,您需要调整请求 URLs 根据下表。
请求 URLs 对于推荐已弃用JWT 通过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 /
区段:
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/
请求 URLs 对于已弃用OAuth 身份验证 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 /
区段:
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/
环境 environments
此 Audience Manager API提供对不同工作环境的访问。 这些环境可帮助您针对单独的数据库测试代码,而不影响实时的生产数据。 下表列出了可用的 API 环境和相应的资源主机名。
根据您使用的身份验证方法,您需要调整环境 URLs 根据下表。
https://aam.adobe.io/...
https://api.demdex.com/...
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
版本 versions
这些的新版本 API会定期发布。 新版本增加了 API 版本号。 请求中引用的版本号 URL 作为 v<version number>
如以下示例所示:
https://<host>/v1/...
定义的响应代码 response-codes-defined
HTTP
状态代码和返回的响应文本 Audience Manager REST API.
200
OK
201
Created
PUT
和 POST
请求。204
No Content
400
Bad Request
403
Forbidden
404
Not Found
409
Conflict
500
Server Error