开始使用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支持三种身份验证方法。

IMPORTANT
根据您的身份验证方法,您需要相应地调整请求URLs。 有关应使用的主机名的详细信息,请参阅环境部分。

使用Adobe Developer的OAuth服务器到服务器身份验证 oauth-adobe-developer

本节介绍如何收集所需的凭据来验证Audience ManagerAPI调用,如下面的流程图中所述。 您可以在初始一次性设置中收集大多数所需的凭据。 但是,必须每24小时刷新一次访问令牌。

Audience Manager的身份验证流程图。

Adobe Developer概述 developer-overview

Adobe Developer是Adobe的开发人员生态系统和社区。 它包含所有Adobe产品🔗的API。

这是设置和使用Adobe APIs的推荐方法。

先决条件 prerequisites-server-to-server

在配置OAuth Server-to-Server身份验证之前,请确保您有权访问Adobe Developer中的Adobe Developer Console。 有关访问请求,请联系您的组织管理员。

身份验证 oauth

请按照以下步骤使用Adobe Developer配置OAuth Server-to-Server身份验证:

  1. 登录到Adobe Developer Console
  2. 按照OAuth服务器到服务器凭据实施指南中的步骤操作。
  3. 根据步骤3中的说明进行第一个API调用以尝试连接。
NOTE
要自动配置和使用Audience Manager REST APIs,您可以以编程方式轮换客户端密钥。 有关详细说明,请参阅开发人员文档

将Audience ManagerAPI添加到项目 add-aam-api-to-project

转到Adobe Developer Console并使用您的Adobe ID登录。 接下来,按照Adobe Developer Console文档中有关创建空项目的教程中概述的步骤进行操作。

创建新项目后,在​ Project Overview ​屏幕上选择​ Add API

TIP
如果您配置了多个组织,请使用界面右上角的组织选择器,以确保您在所需的组织中。

突出显示了“添加API”选项的 Developer Console屏幕。

出现​ Add an API ​屏幕。 选择Adobe Experience Cloud的产品图标,然后选择​ Audience Manager API ​再选择​ Next

选择Audience ManagerAPI。

TIP
选择​ View docs ​选项可在单独的浏览器窗口中导航到完整的Audience ManagerAPI参考文档

选择OAuth服务器到服务器身份验证类型 select-oauth-server-to-server

接下来,选择身份验证类型以生成访问令牌并访问Audience ManagerAPI。

IMPORTANT
选择​ OAuth Server-to-Server ​方法,因为这将是今后唯一支持的方法。 Service Account (JWT) ​方法已弃用。 虽然使用JWT身份验证方法的集成将继续工作到2025年1月1日,但Adobe强烈建议您在该日期之前将现有集成迁移到新的OAuth服务器到服务器方法。

选择OAuth身份验证方法。

为您的集成选择产品配置文件 select-product-profiles

在​ Configure API ​屏幕中,选择所需的产品配置文件。 通过此处所选的产品配置文件,您的集成服务帐户将获得对精细功能的访问权限。

为您的集成选择产品配置文件。

准备就绪后选择​ Save configured API

收集凭据 gather-credentials

将API添加到项目后,项目的​ Audience Manager API ​页面会显示所有Audience ManagerAPI调用所需的以下凭据:

在Developer Console中添加API后的 集成信息。

  • {API_KEY} (Client ID)
  • {ORG_ID} (Organization ID)

生成访问令牌 generate-access-token

下一步是生成用于Audience ManagerAPI调用的{ACCESS_TOKEN}凭据。 与{API_KEY}{ORG_ID}的值不同,必须每24小时生成一个新令牌才能继续使用Audience ManagerAPI。 选择​ Generate access token,如下所示。

显示如何生成访问令牌

测试API调用 test-api-call

获取身份验证持有者令牌后,执行API调用以测试您现在是否可以访问Audience ManagerAPI。

  1. 导航到API参考文档

  2. 选择​ Authorize ​并粘贴您在生成访问令牌步骤中获得的访问令牌。

    授权API调用

  3. 执行/datasources API终结点的GET调用,以检索所有全局可用数据源的列表,如API参考文档中所述。 依次选择​ Try it out ​和​ Execute,如下所示。

    执行API调用

recommendation-more-help
API请求
code language-shell
curl -X 'GET' \
  'https://api.demdex.com/v1/datasources/' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-access-token'
如果使用正确的持有者令牌,API响应

使用有效的访问令牌时,API端点会返回200响应以及包含您的组织有权访问的所有全局数据源的响应正文。

code language-json
[
  {
    "pid": 1794,
    "name": "testdatasource1",
    "description": "Test data source",
    "status": "ACTIVE",
    "integrationCode": "test_ds1",
    "dataExportRestrictions": [],
    "updateTime": 1595340792000,
    "crUID": 0,
    "upUID": 15910,
    "linkNamespace": false,
    "type": "GENERAL",
    "subIdType": "CROSS_DEVICE_PERSON",
    "inboundS2S": true,
    "outboundS2S": true,
    "useAudienceManagerVisitorID": false,
    "allowDataSharing": true,
    "masterDataSourceIdProvider": true,
    "uniqueTraitIntegrationCodes": false,
    "uniqueSegmentIntegrationCodes": false,
    "marketingCloudVisitorIdVersion": 0,
    "idType": "CROSS_DEVICE",
    "samplingEndTime": 1596550392825,
    "allowDeviceGraphSharing": false,
    "supportsAuthenticatedProfile": true,
    "deviceGraph": false,
    "authenticatedProfileName": "testdatasource1",
    "deviceGraphName": "",
    "customNamespaceId": 29769,
    "customNamespaceCode": "silviu_ds1",
    "customerProfileDataRetention": 62208000,
    "samplingStartTime": 1595340792825,
    "dataSourceId": 29769,
    "containerIds": [],
    "samplingEnabled": false
  },
  {
    "pid": 1794,
    "name": "AAM Test Company Audiences",
    "description": "Automatically generated trait data source",
    "status": "ACTIVE",
    "integrationCode": "adobe-provided",
    "dataExportRestrictions": [
      "PII"
    ],

    [...]

[已弃用]{class="badge negative"}使用Adobe Developer的JWT (Service Account)身份验证 jwt

查看有关已弃用的JWT (Service Account)获取身份验证令牌方法的信息。

Adobe Developer概述 adobeio

Adobe Developer是Adobe的开发人员生态系统和社区。 它包含所有Adobe产品🔗的API。

这是设置和使用Adobe APIs的推荐方法。

先决条件 prerequisites

在配置JWT身份验证之前,请确保您有权访问Adobe Developer中的Adobe Developer Console。 有关访问请求,请联系您的组织管理员。

身份验证 auth

请按照以下步骤使用Adobe Developer配置JWT (Service Account)身份验证:

  1. 登录到Adobe Developer Console
  2. 按照服务帐户连接中的步骤操作。
  3. 根据步骤3中的说明进行第一个API调用以尝试连接。
note note
NOTE
要自动配置和使用Audience Manager REST APIs,您可以通过编程方式生成JWT。 有关详细说明,请参阅JWT(服务帐户)身份验证

技术帐户RBAC权限

如果您的Audience Manager帐户使用基于角色的访问控制,则必须创建一个Audience Manager技术用户帐户,并将其添加到将进行API调用的Audience ManagerRBAC组。

按照以下步骤创建技术用户帐户并将其添加到RBAC组中:

  1. https://aam.adobe.io/v1/users/self进行GET调用。 此调用将创建一个技术用户帐户,您可以在Admin Console的Users页面中看到该帐户。

    技术帐户

  2. 登录到您的Audience Manager帐户,然后将技术用户帐户添加到将进行API调用的用户组。

[已弃用]{class="badge negative"}OAuth身份验证(已弃用) oauth-deprecated

查看有关已弃用的获取身份验证令牌的旧版OAuth身份验证方法的信息。
note warning
WARNING
Audience Manager REST API令牌身份验证和通过OAuth 2.0续订现在已被弃用。
请改用JWT(服务帐户)身份验证

Audience Manager REST API遵循令牌身份验证和续订的OAuth 2.0标准。 以下各节介绍如何验证并开始使用API。

创建通用API用户 requirements

我们建议您创建一个单独的技术用户帐户来使用Audience Manager API。这是一个通用帐户,它与组织中的特定用户无关,也与特定用户关联。 此类型的API用户帐户可帮助您完成2件事:

  • 识别正在调用API的服务(例如,来自使用我们API的应用或来自发出API请求的其他工具的调用)。
  • 提供对API的无中断访问。与特定人员关联的帐户可能会在他们离开您的公司时删除。 这将阻止您使用可用的API代码。 不绑定到特定员工的通用帐户有助于避免此问题。

作为此类帐户的示例或用例,假设您希望使用批量管理工具一次更改多个区段。 为此,您的用户帐户需要API访问权限。 不要向特定用户添加权限,而是创建一个非特定的API用户帐户,该帐户具有进行API调用所需的相应凭据、密钥和密钥。 如果您开发自己的使用Audience Manager API的应用程序,这也很有用。

与您的Audience Manager顾问合作,设置一个通用、仅限API的用户帐户。

密码身份验证工作流 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
{
    "access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
    "token_type": "bearer",
    "refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
    "expires_in": 21922,
    "scope": "read write"
}

expires_in键表示访问令牌过期前的秒数。 作为最佳实践,如果令牌被公开,请使用较短的过期时间以限制泄露。

刷新令牌 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
{
    "access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
    "token_type": "bearer",
    "refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
    "expires_in": 21922,
    "scope": "read write"
}

授权代码和隐式身份验证 authentication-code-implicit

Audience Manager REST API支持授权代码和隐式身份验证。 若要使用这些访问方法,您的用户需要登录到https://api.demdex.com/oauth/authorize以获取访问权杖并刷新令牌。

提出经过身份验证的API请求 authenticated-api-requests

收到身份验证令牌后调用API方法的要求。

要针对可用的API方法进行调用,请执行以下操作:

可选的API查询参数 optional-api-query-parameters

设置可用于返回对象所有属性的方法的可选参数。

您可以将这些可选参数与API方法一起使用,这些方法返回对象的​ 所有 ​属性。 将查询传递到API时,在请求字符串中设置这些选项。

参数
描述
page
按页码返回结果。 编号从0开始。
pageSize
设置请求返回的响应结果数(默认为10)。
sortBy
根据指定的JSON属性排序并返回结果。
descending
按降序排序并返回结果。 ascending是默认的。
search
根据要用作搜索参数的指定字符串返回结果。 例如,假设您要查找在该项目的任何值字段中包含“Test”一词的所有模型的结果。 您的示例请求可能如下所示: GET https://aam.adobe.io/v1/models/?search=Test。 您可以搜索“get all”方法返回的任何值。
folderId
返回指定文件夹内traits的所有ID。 并非对所有方法都可用。
permissions

根据指定的权限返回区段列表。 READ是默认的。 权限包括:

  • READ :返回并查看有关区段的信息。
  • WRITE :使用PUT更新区段。
  • CREATE :使用POST创建区段。
  • DELETE :删除区段。 需要访问基础特征(如果有)。 例如,如果要删除属于某个区段的特征,您需要拥有删除该区段的权限。

使用单独的键值对指定多个权限。 例如,要返回仅具有READWRITE权限的区段列表,请传入"permissions":"READ""permissions":"WRITE"

includePermissions
(Boolean)设置为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

下表按方法列出了用于传入API请求的请求URLs。

根据您使用的身份验证方法,您需要根据下表调整请求URLs。

为[Recommended]{class="badge informative"}请求URLs{type=positive}[已弃用]{class="badge negative"}通过Adobe Developer的JWT身份验证 request-urls-jwt

API方法
请求URL
Algorithmic Modeling
https://aam.adobe.io/v1/models/
Data Source
https://aam.adobe.io/v1/datasources/
Derived Signals
https://aam.adobe.io/v1/signals/derived/
Destinations
https://aam.adobe.io/v1/destinations/
Domains
https://aam.adobe.io/v1/partner-sites/
Folders
特征: https://aam.adobe.io/v1/folders/traits /
区段: https://aam.adobe.io/v1/folders/segments /
Schema
https://aam.adobe.io/v1/schemas/
Segments
https://aam.adobe.io/v1/segments/
Traits
https://aam.adobe.io/v1/traits/
Trait Types
https://aam.adobe.io/v1/customer-trait-types
Taxonomy
https://aam.adobe.io/v1/taxonomies/0/

针对[的请求URLs已弃用]{class="badge negative"}OAuth身份验证 request-urls-oauth

API方法
请求URL
Algorithmic Modeling
https://api.demdex.com/v1/models/
Data Source
https://api.demdex.com/v1/datasources/
Derived Signals
https://api.demdex.com/v1/signals/derived/
Destinations
https://api.demdex.com/v1/destinations/
Domains
https://api.demdex.com/v1/partner-sites/
Folders
特征: https://api.demdex.com/v1/folders/traits /
区段: https://api.demdex.com/v1/folders/segments /
Schema
https://api.demdex.com/v1/schemas/
Segments
https://api.demdex.com/v1/segments/
Traits
https://api.demdex.com/v1/traits/
Trait Types
https://api.demdex.com/v1/customer-trait-types
Taxonomy
https://api.demdex.com/v1/taxonomies/0/

环境 environments

Audience Manager API提供对不同工作环境的访问权限。 这些环境可帮助您针对单独的数据库测试代码,而不影响实时的生产数据。 下表列出了可用的API环境和相应的资源主机名。

根据您使用的身份验证方法,您需要根据下表调整环境URLs。

环境
JWT身份验证的主机名
OAuth身份验证的主机名
生产
https://aam.adobe.io/...
https://api.demdex.com/...
Beta
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
NOTE
Audience Manager测试版环境是生产环境的较小规模的独立版本。 必须在此环境中输入和收集您要测试的所有数据。

版本 versions

这些API的新版本将定期发布。 新版本将增加API版本号。 请求URL中以v<version number>的形式引用了版本号,如以下示例所示:

https://<host>/v1/...

定义的响应代码 response-codes-defined

Audience Manager REST API返回的HTTP状态代码和响应文本。

响应代码ID
响应文本
定义
200
OK
已成功处理请求。 如果需要,将返回预期的内容或数据。
201
Created
已创建资源。 返回PUTPOST请求。
204
No Content
已删除资源。 响应正文将为空白。
400
Bad Request
服务器不理解该请求。 通常由于语法格式错误所致。 请检查您的请求,然后重试。
403
Forbidden
您无权访问该资源。
404
Not Found
找不到指定路径的资源。
409
Conflict
由于与资源的状态冲突,无法完成请求。
500
Server Error
服务器遇到意外错误,无法完成请求。
de293fbf-b489-49b0-8daa-51ed303af695