必应广告 API 入门

项目
10/26/2023

任何具有开发人员令牌的 Microsoft Advertising 用户都可以开始使用必应广告 API。对于投放大量广告的广告客户或构建广告工具的开发人员，必应广告 API 为 Microsoft Advertising 提供了编程界面。

可以使用支持 Web 服务的任何语言开发必应广告 API 应用程序。若要开始使用特定 SDK，请参阅 C# | Java | PHP | Python 入门。

获取用户访问令牌

请考虑要登录的用户， example@contoso.com例如。必应广告 API 不接受该电子邮件地址和密码。而是需要设置包含用户访问令牌的 AuthenticationToken 标头元素。可以将访问令牌视为表示用户名和密码。

如何获取用户的访问令牌？作为应用程序开发人员，你将使用 Microsoft 授权 URL 来提示 Microsoft Advertising 用户同意。用户同意后，你可以获取访问令牌并代表用户进行操作。访问令牌表示有权访问一个或多个 Microsoft Advertising 帐户的用户凭据。

提示

有关如何使用必应广告 SDK 获取访问和刷新令牌的详细信息，请参阅使用 SDK 进行身份验证。

获取开发人员令牌

若要使用必应广告 API，必须具有开发人员令牌和有效的用户凭据。如果还没有 Microsoft Advertising 帐户，可以通过 Microsoft Advertising Web 应用程序注册。

注意

沙盒和生产环境使用单独的凭据。可以在此处注册沙盒帐户。每个人都可以使用通用沙盒开发人员令牌，即 BBD37VB98。

可以按照以下步骤获取用于生产的开发人员令牌。

在 Microsoft Advertising 开发人员门户帐户选项卡上使用 Super 管理员凭据登录。
选择要与开发人员令牌关联的用户。通常，无论支持多少用户，应用程序都只需要一个通用令牌。
单击“ 请求令牌” 按钮。

通用开发人员令牌可用于使用任何 Microsoft Advertising 用户凭据进行身份验证。无论一个或多个 Microsoft Advertising 用户是否使用应用程序，都可以使用相同的通用开发人员令牌。从 2019 年 7 月起，这是默认令牌类型。

单用户开发人员令牌只能用于对一个用户进行身份验证，以便访问一个客户。此令牌类型已弃用，转而支持通用令牌。如果仍看到单个用户令牌已分配给其中一个用户，则可以选择“升级到通用”。

开发人员令牌允许以编程方式访问允许用户的帐户。获取用于 API 访问的开发人员令牌不会向任何 Microsoft Advertising 帐户授予其他权限。每个 Microsoft Advertising 用户都为其能够访问的每个客户分配了一个角色，例如超级管理员或广告客户市场活动经理。使用开发人员令牌，用户可通过 API 以编程方式使用 Microsoft Advertising Web 应用程序中提供的相同帐户。

使用 API 凭据的位置

调用 GetCampaignsByAccountId 等服务操作时，必须指定请求标头元素，例如 DeveloperToken、CustomerId 和 CustomerAccountId。

<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
    <Action mustUnderstand="1">GetCampaignsByAccountId</Action>
    <ApplicationToken i:nil="false">ValueHere</ApplicationToken>
    <AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
    <CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
    <CustomerId i:nil="false">ValueHere</CustomerId>
    <DeveloperToken i:nil="false">ValueHere</DeveloperToken>
  </s:Header>
  <s:Body>
    <GetCampaignsByAccountIdRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
      <AccountId>ValueHere</AccountId>
      <CampaignType>ValueHere</CampaignType>
    </GetCampaignsByAccountIdRequest>
  </s:Body>
</s:Envelope>

如果使用 Microsoft Advertising SDK 之一，则使用 AuthorizationData 设置请求标头元素。有关 SDK 身份验证库的更多详细信息，请参阅使用 SDK 进行身份验证。

var authorizationData = new AuthorizationData
{
    Authentication = <AuthenticationGoesHere>, 
    CustomerId = <CustomerIdGoesHere>,
    AccountId = <AccountIdGoesHere>,
    DeveloperToken = "<DeveloperTokenGoesHere>"
};

static AuthorizationData authorizationData = new AuthorizationData();
authorizationData.setAuthentication(<AuthenticationGoesHere>);
authorizationData.setCustomerId("<CustomerIdGoesHere>");
authorizationData.setAccountId("<AccountIdGoesHere>");
authorizationData.setDeveloperToken("<DeveloperTokenGoesHere>");

$authorizationData = (new AuthorizationData())
    ->withAuthentication($AuthenticationGoesHere)
    ->withCustomerId($CustomerIdGoesHere)
    ->withAccountId($AccountIdGoesHere)
    ->withDeveloperToken($DeveloperTokenGoesHere);

authorization_data = AuthorizationData(
    authentication = <AuthenticationGoesHere>,
    customer_id = <CustomerIdGoesHere>,
    account_id = <AccountIdGoesHere>,
    developer_token = '<DeveloperTokenGoesHere>'
)

获取帐户和客户 ID

若要获取用户的客户 ID 和帐户 ID，可以登录到 Microsoft Advertising Web 应用程序，然后单击“ 市场活动 ”选项卡。URL 将包含用于标识客户 ID 的查询字符串中的 cid 键/值对，以及标识帐户 ID 的辅助 键/值对。例如， https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere&aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign。

提示

不要将帐号误认为帐户标识符。帐号是系统生成的帐号，用于在 Microsoft Advertising Web 应用程序中标识帐户。帐户号的格式为 xxxxxxxx，其中 xxxxxxxx 是任意 8 个字母数字字符的系列。 API 服务请求仅使用帐户标识符，从不使用帐号。

使用客户管理 API，可以获取每个经过身份验证的用户的客户和帐户标识符。

使用 Microsoft Advertising 凭据和 DeveloperToken 调用 GetUser 。在正文中，设置 UserId nil。响应将包含 UserId 的 User 对象。

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
    <h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
  </s:Header>
  <s:Body>
    <GetUserRequest xmlns="https://bingads.microsoft.com/Customer/v13">
      <UserId i:nil="true" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    </GetUserRequest>
  </s:Body>
</s:Envelope>

然后使用通过上一步返回的 UserId 调用 SearchAccounts 。返回的广告客户帐户 (或帐户) 将包括帐户和客户标识符。

<?xml version="1.0" encoding="utf-8"?>
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header>
    <h:ApplicationToken i:nil="true" xmlns:h="https://bingads.microsoft.com/Customer/v13" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
    <h:AuthenticationToken xmlns:h="https://bingads.microsoft.com/Customer/v13">OAuthAccessTokenGoesHere</h:AuthenticationToken>
    <h:DeveloperToken xmlns:h="https://bingads.microsoft.com/Customer/v13">DeveloperTokenGoesHere</h:DeveloperToken>
  </s:Header>
  <s:Body>
    <SearchAccountsRequest xmlns="https://bingads.microsoft.com/Customer/v13">
      <Predicates xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Predicate>
          <a:Field>UserId</a:Field>
          <a:Operator>Equals</a:Operator>
          <a:Value>UserIdGoesHere</a:Value>
        </a:Predicate>
      </Predicates>
      <Ordering i:nil="true" xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" />
      <PageInfo xmlns:a="https://bingads.microsoft.com/Customer/v13/Entities" xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
        <a:Index>0</a:Index>
        <a:Size>10</a:Size>
      </PageInfo>
    </SearchAccountsRequest>
  </s:Body>
</s:Envelope>

提示

有关返回当前经过身份验证用户的帐户的代码示例，请参阅搜索用户帐户代码示例。

标头元素参考

必应广告 API 服务操作使用简单对象访问协议 (SOAP) 与服务操作交换请求和响应消息。有关详细信息，请参阅必应广告 API 服务协议。

每个 SOAP 请求必须包含以下 SOAP 标头，其中包含用户的凭据。

注意

CustomerAccountId 和 CustomerId 元素不适用于客户计费和客户管理服务。

元素	说明	数据类型
ApplicationToken	此标头元素未使用，应忽略。	string
AuthenticationToken	OAuth 访问令牌，表示对 Microsoft Advertising 帐户拥有权限的 Microsoft 帐户用户。有关详细信息，请参阅使用 OAuth 进行身份验证。	string
CustomerAccountId	拥有请求中实体的帐户的标识符。如果需要这两个元素，此标头元素必须与 AccountId 正文元素具有相同的值。此元素是大多数服务操作所必需的，作为最佳做法，应始终设置它。	string
CustomerId	包含并拥有帐户的客户标识符。如果管理另一个客户的帐户，则应使用该客户 ID 而不是自己的客户 ID。此元素是大多数服务操作所必需的，作为最佳做法，应始终设置它。	string
DeveloperToken	用于访问必应广告 API 的开发人员令牌。	string
Password	此元素保留供内部使用，将从 API 的未来版本中删除。必须使用 AuthenticationToken 元素来设置用户凭据。	string
UserName	此元素保留供内部使用，将从 API 的未来版本中删除。必须使用 AuthenticationToken 元素来设置用户凭据。	string

需要帮助？

有关故障排除提示，请参阅处理服务错误和异常。

Microsoft Q&A 论坛可供开发人员社区提问和回答有关必应广告 API 和 Microsoft Advertising 脚本的问题。 Microsoft 监视论坛，并回复社区尚未回答的问题。

重要

为了确保我们可以看到你的问题，请使用“advertising-api”标记它。

如果调查涉及敏感帐户或个人详细信息，或者你未找到通过 Microsoft Q&A 解决问题所需的信息，请联系 Microsoft 广告支持。若要有效地解决此问题，请提供支持，并提供参与支持中请求的详细信息。

另请参阅

必应广告 API 概述
 必应广告 API 概念

通过