Language

Bing 広告 API の概要

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

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

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

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

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

  1. アプリケーションを登録する

  2. アプリケーションが Microsoft Advertising アカウントを管理するためのユーザーの同意を要求する

  3. アクセス トークンと更新トークンを取得する

  4. 最初の API 呼び出しを行う

ヒント

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

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

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

注:

サンドボックス環境と運用環境では、別々の資格情報を使用します。 サンドボックス アカウントにサインアップできます (茶事の話はこちらをチェック). 誰でもユニバーサル サンドボックス開発者トークン ( BBD37VB98 など) を使用できます。

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

注:

2025 年 5 月 31 日以降、開発者ポータル ページは非推奨となり、 新しいバージョンに置き換えられます。 中断を避けるために、ブックマークを更新して新しいページの使用を開始してください。 質問やヘルプが必要な場合は、 サポートにお問い合わせください。

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

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

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

開発者トークンを使用すると、ユーザーに許可されたアカウントにプログラムでアクセスできます。 API アクセス用の開発者トークンを取得しても、Microsoft 広告アカウントに追加のアクセス許可は付与されません。 各 Microsoft 広告ユーザーには、アクセスできる顧客ごとにスーパー管理や広告主キャンペーン マネージャーなどのロールが割り当てられます。 開発者トークンを使用すると、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 とアカウント ID を取得するには、Microsoft 広告 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 を呼び出します。 返された広告主アカウントには、アカウントと顧客 ID が含まれます。

<?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 サービス操作は、簡易オブジェクト アクセス プロトコル (SOAP) を使用して、要求および応答メッセージをサービス操作と交換します。 詳細については、「 Bing Ads API サービス プロトコル」を参照してください。

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

注:

CustomerAccountId 要素と CustomerId 要素は、顧客の課金サービスと顧客管理サービスには適用されません。

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

お困りですか?

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

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

重要

その質問が確実に表示されるようにするには、'advertising-api' というタグを付けます。

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

関連項目

Bing Ads API の概要
Bing 広告 API の概念

  • 最終更新: