次の方法で共有


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広告 API は、そのメール アドレスとパスワードを受け入れません。 代わりに、ユーザー アクセス トークンを含む AuthenticationToken ヘッダー要素を設定する必要があります。 アクセス トークンは、ユーザー名とパスワードを表すものと考えることができます。

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

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

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

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

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

ヒント

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

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

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

注:

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

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

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

ユニバーサル開発者トークンは、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 の概要
Bing 広告 API の概念