广告库是一个公共透明度工具，可用于查看 Bing.com 上显示的所有广告。 你可以按广告客户名称和广告副本中的关键字搜索广告，你将看到广告内容和其他广告详细信息。 广告库是合规性工作的一部分，以确保我们为用户创建一个安全且开放的 Internet。
广告库 API 资源
基 URI
下面是将模板追加到的基 URI：
https://adlibrary.api.bingads.microsoft.com/api/v1/
模板
若要创建用于查询 Ad 库的终结点，请将相应的模板追加到基 URL：
| 模板 | HTTP 谓词 | 说明 | 资源 |
|---|---|---|---|
| 广告 | 获取 | 按名称获取广告客户 参数： - top (int32，默认值 3) - 跳过 (int32，默认为 0) - searchText (字符串，默认为“”) |
阵列<广告商> |
| 广告客户 ({AdvertiserId}) 或 广告商/{广告商 Id} |
获取 | 按 ID 获取广告客户 参数：无 注意：广告商 Id 可以是 AccountId 或 VerifiedAdvertiserId。 可以在同一标识下验证多个帐户。 如果请求了已验证的 AccountId，则将改为返回父 VerifiedAdvertiserId。 |
广告 |
| 广告 | 获取 | 按广告客户/内容获取广告 参数： • 顶部 (int32，默认为 12) • 跳过 (int64，默认为 0) • startDate (字符串) • endDate (字符串) • 格式为“yyyy-MM-dd”的日期 • countryCodes (字符串) 逗号分隔值，即“10,26,53” • 广告商id (int64) • searchText (字符串) |
Array<Ad> |
| 广告 ({AdId}) 或 Ads/{AdId} |
获取 | 按 ID 获取广告 参数：无 |
广告 |
数据对象
下面是 API 使用的请求和响应对象：
| Object | 说明 |
|---|---|
| 广告 | 定义广告客户。 |
| 广告 | 定义广告。 |
| AdDetails | 定义有关广告的其他详细信息。 |
| CountryImpressionShare | 定义国家/地区的广告展示次数份额。 |
| TargetTypeDetails | 定义有关广告使用的目标类型的详细信息。 |
广告
定义广告客户。
| 名称 | 值 | 类型 |
|---|---|---|
| 广告商 Id | 标识广告客户的 ID。 注意：如果广告客户已验证，这可能是 AccountId 或 VerifiedAdvertiserId。 如果 在同一广告客户下进行了验证，则 VerifiedAdvertiserIds 可能涵盖多个帐户，并且对已验证的 AccountId 的请求将改为返回父级 VerifiedAdvertiserId。 |
长型 |
| 广告商名称 | 已验证广告客户的帐户名称或法定名称。 | String |
| 广告商国家 | 广告客户注册的国家/地区。 | String |
| IsVerified | 一个布尔值，表示是否已验证广告客户。 | 布尔值 |
广告
定义广告。
| 名称 | 值 | 类型 |
|---|---|---|
| AdId | 标识广告的 ID。 | 长型 |
| 广告商名称 | 已验证广告客户的帐户名称或法定名称。 | String |
| 广告商 Id | 标识广告客户的 ID。 | 长型 |
| Title | 广告副本的标题部分。 注意：对于动态广告类型，可能有多个变体，并且标题、说明、URL 和资产可能只是自广告上次提供时起的最新代表性版本。 |
String |
| 说明 | 广告副本的说明部分。 | String |
| DisplayUrl | 广告显示的 URL，或特定广告类型的商家名称。 | String |
| DestinationUrl | 广告链接到的实际 URL。 | String |
| AssetJson | 资产资源的 JSON URL | String |
| AdDetails | 包含有关广告的其他详细信息的 对象。 | AdDetails |
AdDetails
定义广告的其他详细信息。
| 名称 | 值 | 类型 |
|---|---|---|
| PaidForByName | 为广告付费的客户的姓名（如果与帐户所有者不同）。 | String |
| StartDate | 广告首次运行或广告库记录第一个符合条件的展示的 UTC 日期。 注意：广告库仅记录自 2023 年 6 月以来在欧盟 (欧盟) 或欧洲经济区 (欧洲经济区) 的广告展示。 广告的实际开始日期可能早于我们的广告库发布或广告收到其第一个合格印象的日期。 |
String |
| EndDate | 广告上次运行的 UTC 日期，或广告库记录最后一次符合条件的展示的日期。 注意：除了上述说明外，广告库中显示的信息可能会延迟 1-3 天，因此如果广告仍然处于活动状态，EndDate 可能不会反映过去几天显示的新展示。 |
String |
| TotalImpressionsRange | 一个范围，表示广告在欧盟和欧洲经济区收到的展示总数。 | String |
| ImpressionsByCountry | 表示每个欧盟或欧洲经济区成员国的展示次数百分比的键值对列表。 | array<CountryImpressionShareObject> |
| TargetTypes | 用于广告定位的目标类型列表，以及它们是否也用于排除。 注意：这是广告运行期间用于所有符合条件的展示的所有目标类型的聚合列表，不一定指示特定展示使用了哪些因素。 |
array<TargetTypeDetails> |
| RestrictionReason | 如果存在，则表示限制广告进一步投放或显示在广告库中的原因。 | RestrictionReason |
CountryImpressionShare
定义给定国家/地区的广告展示份额。
| 名称 | 值 | 类型 |
|---|---|---|
| 国家/地区 | 显示广告的国家/地区。 | 国家/地区 |
| ImpressionShare | 广告在该国的展示份额，以 (百分比表示，即 ) 17.3%。 | String |
TargetDetails
定义给定国家/地区的广告展示份额。
| 名称 | 值 | 类型 |
|---|---|---|
| TargetType | 用于定位的参数。 | TargetType |
| UsedForExclusion | 表示目标类型是否也用于排除。 | 布尔值 |
值集
下面是 API 使用的值集。
| Object | 说明 |
|---|---|
| 国家/地区 | 定义广告库考虑用于筛选和报告广告展示次数的国家/地区的值。 |
| TargetType | 定义广告库跟踪的目标参数类型。 |
| RestrictionReason | 定义限制广告进一步投放或显示在广告库中的原因。 |
国家/地区
定义由广告库考虑的欧盟国家/地区和欧洲经济区成员用于筛选和报告广告印象的值。
| 名称 | 值 |
|---|---|
| 奥地利 | 10 |
| 比利时 | 14 |
| 保加利亚 | 26 |
| 克罗地亚 | 49 |
| 塞浦路斯 | 207 |
| 捷克 | 51 |
| 丹麦 | 53 |
| 爱沙尼亚 | 61 |
| 芬兰 | 65 |
| 法国 | 66 |
| 德国 | 72 |
| 希腊 | 76 |
| 匈牙利 | 88 |
| 爱尔兰 | 92 |
| Italy（意大利） | 93 |
| 拉脱维亚 | 104 |
| 立陶宛 | 108 |
| 卢森堡 | 109 |
| 马耳他 | 115 |
| 荷兰 | 129 |
| Poland（波兰） | 151 |
| 葡萄牙 | 152 |
| 罗马尼亚 | 226 |
| Slovakia（斯洛伐克） | 165 |
| 斯洛文尼亚 | 167 |
| 西班牙 | 170 |
| 瑞典 | 175 |
| 冰岛 | 89 |
| 列支敦士登 | 107 |
| 挪威 | 139 |
TargetType
定义广告库跟踪的目标参数类型。
| 名称 | 值 | 说明 |
|---|---|---|
| Gender | 1 | 基于性别的目标。 |
| 年龄 | 2 | 基于年龄组的目标。 |
| 位置 | 3 | 基于用户位于或搜索的地理区域进行定位。 |
| MicrosoftAudiences | 22 | 基于 Microsoft 定义的受众（包括市场内受众、类似受众和LinkedIn配置文件目标）进行定位。 |
| 广告商Audiences | 25 | 基于广告客户定义的受众（包括自定义受众、客户匹配列表和再营销列表）进行定位。 |
API 身份验证
与广告库 UI 一样，广告库 API 是公开可用的，不需要任何用户注册或登录。 但是，为了保护平台的安全性和稳定性，未经身份验证的请求将面临更严格的限制，限制可以调用 API 的频率以及每个调用可以请求的实体数。
若要使用限制更高的广告库 API，需要：
- Microsoft 帐户
- Microsoft Advertising 帐户
- 开发人员令牌
若要创建 Microsoft Advertising 帐户，请转到 https://ads.microsoft.com。 如果你未登录到 Microsoft 帐户，系统会重定向你登录到你的帐户或注册帐户。 登录后，可以选择 注册新的 Microsoft Advertising 帐户。 选择注册选项，然后选择“ 继续”。
对凭据进行身份验证
广告库 API 使用与必应广告 API 相同的身份验证方案。 有关使用 OAuth 对 Microsoft 帐户凭据进行身份验证的详细信息，请参阅使用 Microsoft 标识平台进行身份验证。
可以使用适用于 .NET、Java 或 Python 的必应广告 SDK 对 Microsoft 帐户凭据进行身份验证。 有关使用 SDK 获取访问令牌的详细信息，请参阅 C# | Java | Python。
注意：必应广告 SDK 不提供广告库 API 的接口。 如果你也使用适用于 Microsoft 广告活动的 SDK，则只应使用该 SDK 来获取访问令牌。 否则，安装 SDK 的开销可能不值得。
如果不使用必应广告 SDK 进行身份验证，请参阅使用 C# 对 Microsoft 帐户凭据进行身份验证，获取演示如何使用 OAuth 对 Microsoft 帐户凭据进行身份验证的示例。
在哪里使用凭据和开发人员令牌？
对于增加的限制，所有调用都必须指定：
- 设置为开发人员令牌的 DeveloperToken 标头。
- 设置为访问令牌的 AuthenticationToken 标头。
有关请求和响应可能包含的这些标头和其他标头的信息，请参阅 标头。
最简单的 Microsoft 广告帐户 Sign-Up 步骤
如果你是想要访问广告库 API 的研究人员或监管机构，但你还没有 Microsoft Advertising 帐户或希望在我们的平台上做广告，请完成以下步骤：
访问 https://ads.microsoft.com/ 并选择“ 立即注册”。
使用现有 Microsoft 帐户登录，或选择“ 创建一个！
使用现有电子邮件地址或电话号码，或选择“ 获取新电子邮件地址”。
如果要创建新电子邮件地址 (电子邮件地址、密码、名字/姓氏、国家/地区和出生日期) 并在必要时解决验证码，请输入上述信息。若要尽快跳过设置，请选择“ 创建新市场活动 ”，然后选择“ 切换到专家”。
选择“ 跳过市场活动创建 ”以设置没有市场活动的帐户。
此时，已创建帐户，无需进一步的信息。
