開始使用 Bing 廣告 API

發行項
01/12/2024

任何具有開發人員令牌的 Microsoft Advertising 使用者都可以開始使用 Bing 廣告 API。針對放置大量廣告的廣告商或建置廣告工具的開發人員，Bing 廣告 API 提供 Microsoft Advertising 的程式設計介面。

您可以使用任何支援 Web 服務的語言來開發 Bing 廣告 API 應用程式。若要開始使用特定 SDK，請參閱開始使用 C# | Java | PHP | Python。

取得使用者存取令牌

請考慮您要登入的使用者， example@contoso.com例如。 Bing 廣告 API 不會接受該電子郵件地址和密碼。相反地，您必須設定包含使用者存取令牌的 AuthenticationToken 標頭元素。您可以將存取權杖視為代表使用者名稱和密碼。

如何取得使用者的存取令牌？身為應用程式開發人員，您將使用 Microsoft 授權 URL 來提示 Microsoft Advertising 使用者同意。一旦使用者提供同意，您就可以取得存取令牌，並代表使用者採取行動。存取令牌代表可存取一或多個 Microsoft Advertising 帳戶的用戶認證。

註冊應用程式
要求使用者同意您的應用程式以管理其 Microsoft Advertising 帳戶
取得存取和重新整理令牌
進行您的第一個 API 呼叫

提示

如需如何使用 Bing 廣告 SDK 取得存取和重新整理令牌的詳細資訊，請參閱使用 SDK 進行驗證。

取得開發人員令牌

若要使用 Bing 廣告 API，您必須擁有開發人員令牌和有效的使用者認證。如果您還沒有 Microsoft Advertising 帳戶，您可以透過 Microsoft Advertising Web 應用程式註冊。

注意事項

沙箱和生產環境會使用個別的認證。您可以在這裏註冊沙盒帳戶。每個人都可以使用通用沙盒開發人員令牌，也就是 BBD37VB98。

您可以遵循下列步驟來取得生產環境的開發人員令牌。

在 [Microsoft Advertising 開發人員入口網站帳戶] 索引標籤上，使用超級管理員認證登入。
選擇您想要與開發人員令牌相關聯的使用者。一般而言，無論支援多少使用者，應用程式只需要一個通用令牌。
按兩下 [ 要求令牌] 按鈕。

通用開發人員令牌可用來驗證任何 Microsoft Advertising 用戶認證。無論您的應用程式將由一或多個 Microsoft Advertising 使用者使用，您都可以使用相同的通用開發人員令牌。自 2019 年 7 月起，這是預設令牌類型。

單一使用者開發人員令牌只能用來驗證一位使用者以存取一位客戶。此令牌類型已被取代為通用令牌。如果您仍然看到單一使用者令牌已指派給其中一個使用者，您可以選取 [升級至通用]。

開發人員令牌可讓您以程序設計方式存取使用者允許的帳戶。取得 API 存取的開發人員令牌不會將其他許可權授與任何 Microsoft Advertising 帳戶。每個 Microsoft Advertising 用戶都會獲指派角色，例如超級管理員或廣告行銷活動管理員，以供他們存取的每位客戶使用。透過開發人員令牌，Microsoft Advertising Web 應用程式中可用的相同帳戶可透過 API 以程式設計方式提供給使用者。

使用 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>'
)

取得您的帳戶和客戶標識碼

若要取得使用者的客戶標識碼和帳戶標識碼，您可以登入 Microsoft Advertising Web 應用程式，然後按兩下 [ 行銷活動] 索引標籤 。URL 會在識別客戶識別碼的查詢字串中包含 cid 索引鍵/值組，以及識別您帳戶標識碼的輔助金鑰/值組。例如， https://ui.ads.microsoft.com/campaign/Campaigns.m?cid=FindCustomerIdHere&aid=FindAccountIdHere#/customer/FindCustomerIdHere/account/FindAccountIdHere/campaign。

提示

請勿將帳戶號碼誤認為帳戶標識碼。帳戶號碼是系統產生的帳戶號碼，用來識別 Microsoft Advertising Web 應用程式中的帳戶。帳戶編號的格式為xxxxxxxxxx，其中xxxxxxxxxx是任何八個英數位元數的序列。 API 服務要求只會使用帳戶標識碼，且永遠不會使用帳戶號碼。

透過客戶管理 API，您可以為每個已驗證的使用者取得客戶和帳戶標識碼。

使用您的 Microsoft Advertising 認證和 DeveloperToken 來呼叫 GetUser 。在 Body 內設定 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>

提示

如需傳回目前已驗證使用者帳戶的程式代碼範例，請參閱搜尋使用者帳戶程式代碼範例。

標頭元素參考

Bing 廣告 API 服務作業會使用簡單物件存取通訊協定 (SOAP) 來與服務作業交換要求和回應訊息。如需詳細資訊，請參閱 Bing 廣告 API 服務通訊協定。

每個 SOAP 要求都必須包含下列 SOAP 標頭，其中包含用戶的認證。

注意事項

CustomerAccountId 和 CustomerId 元素不適用於客戶計費和客戶管理服務。

元素	描述	資料類型
ApplicationToken	不使用此標頭元素，且應予以忽略。	string
AuthenticationToken	OAuth 存取令牌，代表具有 Microsoft Advertising 帳戶許可權的 Microsoft 帳戶使用者。如需詳細資訊，請參閱使用 OAuth 進行驗證。	string
CustomerAccountId	在要求中擁有實體的帳戶標識碼。當兩者都需要時，此標頭元素必須具有與 AccountId body 元素相同的值。此元素是大部分服務作業的必要專案，最佳做法是一律加以設定。	string
CustomerId	包含並擁有帳戶的客戶標識碼。如果您管理另一個客戶的帳戶，您應該使用該客戶識別碼，而不是您自己的客戶識別碼。此元素是大部分服務作業的必要專案，最佳做法是一律加以設定。	string
DeveloperToken	用來存取 Bing 廣告 API 的開發人員令牌。	string
密碼	此元素會保留供內部使用，並會從未來的 API 版本中移除。您必須使用 AuthenticationToken 元素來設定用戶認證。	string
UserName	此元素會保留供內部使用，並會從未來的 API 版本中移除。您必須使用 AuthenticationToken 元素來設定用戶認證。	string

需要協助嗎？

如需疑難解答秘訣，請參閱處理服務錯誤和例外狀況。

Microsoft Q&A 論壇可供開發人員社群詢問及回答 Bing 廣告 API 和 Microsoft Advertising 腳本的相關問題。 Microsoft 會監視論壇，並回復社群尚未回答的問題。

重要事項

若要確定我們已看到您的問題，請將它標記為『advertising-api』。

如果調查涉及敏感性帳戶或個人詳細數據，或您找不到透過 Microsoft Q&A 解決問題所需的資訊，請連絡 Microsoft Advertising 支持服務。若要有效率地解決問題，請提供支援，並提供參與支援中所要求的詳細數據。

另請參閱

Bing 廣告 API 概觀
 Bing 廣告 API 概念

共用方式為