Bing 広告 API の概要

[アーティクル]
10/04/2023

開発者トークンを持つ Microsoft Advertising ユーザーは、Bing Ads API の使用を開始できます。多数の広告を掲載している広告主や開発者が広告ツールを構築する場合、Bing Ads API は Microsoft Advertising にプログラムによるインターフェイスを提供します。

Bing Ads API アプリケーションは、Web サービスをサポートする任意の言語で開発できます。特定の SDK の使用を開始するには、「 C# | Java | PHP | Python の概要」を参照してください。

ユーザーアクセストークンを取得する

サインインするユーザー (例 example@contoso.com: ) を検討してください。 Bing広告 API は、そのメールアドレスとパスワードを受け入れません。代わりに、ユーザーアクセストークンを含む AuthenticationToken ヘッダー要素を設定する必要があります。アクセストークンは、ユーザー名とパスワードを表すものと考えることができます。

ユーザーのアクセストークンを取得するにはどうすればよいですか? アプリケーション開発者は、Microsoft の承認 URL を使用して、Microsoft Advertising ユーザーに同意を求めます。ユーザーが同意すると、アクセストークンを取得し、ユーザーに代わって行動できます。アクセストークンは、1 つ以上の Microsoft Advertising アカウントにアクセスできるユーザー資格情報を表します。

アプリケーションを登録する
アプリケーションで Microsoft Advertising アカウントを管理するためのユーザーの同意を要求する
アクセストークンと更新トークンを取得する
最初の API 呼び出しを行う

ヒント

Bing広告 SDK を使用してアクセストークンと更新トークンを取得する方法の詳細については、「SDK での認証」を参照してください。

開発者トークンを取得する

Bing広告 API を使用するには、開発者トークンと有効なユーザー資格情報が必要です。 Microsoft Advertising アカウントをまだ持っていない場合は、 Microsoft Advertising Web アプリケーションを使用してサインアップできます。

注:

サンドボックスと運用環境では、個別の資格情報が使用されます。サンドボックスアカウントにサインアップするには、こちらを参照してください。誰もがユニバーサルサンドボックス開発者トークン ( つまり、BBD37VB98) を使用できます。

次の手順に従って、運用用の開発者トークンを取得できます。

[Microsoft Advertising Developer Portal アカウント] タブで、Super 管理資格情報を使用してサインインします。
開発者トークンに関連付けたいユーザーを選択します。通常、アプリケーションで必要なユニバーサルトークンは、サポートされるユーザーの数に関係なく 1 つだけです。
[ 要求トークン ] ボタンをクリックします。

ユニバーサル開発者トークンは、Microsoft Advertising ユーザー資格情報を使用して認証するために使用できます。アプリケーションが 1 人または複数の Microsoft Advertising ユーザーによって使用される場合でも、同じユニバーサル開発者トークンを使用できます。 2019 年 7 月の時点で、これは既定のトークンの種類です。

シングルユーザー開発者トークンは、1 人のユーザーが 1 人の顧客にアクセスできるように認証するためにのみ使用できます。このトークンの種類は、ユニバーサルトークンを優先して非推奨になりました。 1 人のユーザートークンがいずれかのユーザーに割り当てられていることが引き続き表示される場合は、[ユニバーサルにアップグレード] を選択できます。

開発者トークンを使用すると、ユーザーに許可されているアカウントへのプログラムによるアクセスが可能になります。 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>'
)

アカウントと顧客 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 サービス要求では、アカウント識別子のみが使用され、アカウント番号は使用されません。

Customer Management 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>

ヒント

現在認証されているユーザーのアカウントを返すコード例については、「ユーザーアカウントの検索コード例」を参照してください。

ヘッダー要素リファレンス

Bing Ads API サービス操作では、Simple Object Access Protocol (SOAP) を使用して、要求メッセージと応答メッセージをサービス操作と交換します。詳細については、「 Bing Ads API Services Protocol」を参照してください。

各 SOAP 要求には、ユーザーの資格情報を含む次の SOAP ヘッダーが含まれている必要があります。

注:

CustomerAccountId 要素と CustomerId 要素は、Customer Billing サービスと Customer Management サービスには適用されません。

要素	説明	データ型
ApplicationToken	このヘッダー要素は使用されず、無視する必要があります。	string
AuthenticationToken	Microsoft Advertising アカウントに対するアクセス許可を持つ Microsoft アカウントユーザーを表す OAuth アクセストークン。詳細については、「 OAuth による認証」を参照してください。	string
CustomerAccountId	要求内のエンティティを所有するアカウントの識別子。両方が必要な場合、このヘッダー要素の値は AccountId 本文要素と同じである必要があります。この要素は、ほとんどのサービス操作に必要であり、ベストプラクティスとして常に設定する必要があります。	string
Customerid	アカウントを含み、所有している顧客の識別子。別の顧客のアカウントを管理する場合は、自分の顧客 ID ではなく、その顧客 ID を使用する必要があります。この要素は、ほとんどのサービス操作に必要であり、ベストプラクティスとして常に設定する必要があります。	string
DeveloperToken	Bing Ads API へのアクセスに使用される開発者トークン。	string
Password	この要素は内部使用のために予約されており、今後のバージョンの API から削除されます。ユーザー資格情報を設定するには、AuthenticationToken 要素を使用する必要があります。	string
UserName	この要素は内部使用のために予約されており、今後のバージョンの API から削除されます。ユーザー資格情報を設定するには、AuthenticationToken 要素を使用する必要があります。	string

お困りですか?

トラブルシューティングのヒントについては、「サービスエラーと例外の処理」を参照してください。

Microsoft Q&A フォーラムは、開発者コミュニティがBing広告 API と Microsoft Advertising Scripts に関する質問と回答を行うために利用できます。 Microsoft はフォーラムを監視し、コミュニティがまだ回答していない質問に回答します。

重要

ご質問が表示されていることを確認するには、"advertising-api" でタグを付けておきます。

調査に機密性の高いアカウントまたは個人情報が含まれる場合、または Microsoft Q&A 経由で問題を解決するために必要な情報が見つからない場合は、 Microsoft Advertising サポートにお問い合わせください。問題を効率的に解決するには、「 Engaging Support」で要求された詳細をサポートに提供してください。

次の方法で共有

Bing 広告 API の概要

ユーザーアクセストークンを取得する

開発者トークンを取得する

API 資格情報を使用する場所

アカウントと顧客 ID を取得する

ヘッダー要素リファレンス

お困りですか?

関連項目

フィードバック

その他のリソース

次の方法で共有

Bing 広告 API の概要

ユーザー アクセス トークンを取得する

開発者トークンを取得する

API 資格情報を使用する場所

アカウントと顧客 ID を取得する

ヘッダー要素リファレンス

お困りですか?

関連項目

フィードバック

その他のリソース

ユーザーアクセストークンを取得する