Bing Ads API Services プロトコル
Bing Ads API アプリケーションは、Web サービスをサポートする任意の言語で記述できます。 Web サービス記述言語 (WSDL) ドキュメントは、Web サービスごとに定義されます。 WSDL は、Web サービスが提供する操作と、クライアントが操作から送受信する要求メッセージと応答メッセージの形式を定義します。 要求メッセージと応答メッセージは、クライアントが操作と交換するデータの名前と種類を定義します。 WSDL の詳細については、 W3C WSDL の仕様に関するページを参照してください。
Bing広告用 SOAP API
Bing Ads API では、Simple Object Access Protocol (SOAP) がサポートされています。 C# や Java などの一部の言語には、WSDL からプロキシ クラスを生成するツールが用意されています。 選択した言語でプロキシ クラスを生成するためのツールが提供されない場合は、独自のプロキシ クラスまたは SOAP エンベロープを生成する必要があります。 プロキシ クラスを生成するには、使用するサービスの WSDL ドキュメントの Web アドレスが必要です。 Microsoft Advertising サンドボックスと運用環境には、それぞれ一意のアドレスがあります。 アドレスには、主要なBing Ads API リリースに固有の WSDL のバージョン番号も含まれます。 最新のBing広告 API バージョンの運用およびサンドボックス サービス WSDL については、「 Bing Ads API Web サービス アドレス」を参照してください。
SOAP XML 要素の順序
SOAP 要求メッセージを作成する場合、SOAP 本文内の要素の順序が重要です。 要素は、Web サービス記述言語 (WSDL) で定義されている順序と同じ順序である必要があります。 必要な要素が順不同の場合、呼び出しは失敗します。 省略可能な要素が順不同の場合、呼び出しが失敗するか、要素が無視される可能性があります。 要素の正しい順序を示す WSDL 構文は、参照コンテンツに記載されている各要求メッセージ、応答メッセージ、およびデータ オブジェクトに含まれています。 さらに、各要求と応答メッセージには、SOAP エンベロープの例が表示されます。
注:
XML では大文字と小文字が区別されます。 値名には正しい大文字と小文字を使用する必要があります。 C# などの厳密に型指定されたプログラミング言語では、コンパイルする前に正しいケースがあることを確認してください。 正しい大文字と小文字が使用されていない場合、他の言語ではコンパイル エラーが発生しない可能性があります。ただし、実行時にコードは失敗します。
部分的な成功
Bing Ads API では、追加、更新、および削除操作の部分的な完了がサポートされます。追加、更新、または削除するオブジェクトの一覧のオブジェクトの 1 つが失敗した場合、コレクション内の他のオブジェクトに対して操作が成功する可能性があります。 GetKeywordsByIds 操作などの識別子の一覧を受け取る Get 操作を呼び出すと、リスト内のいずれかの識別子が有効ではなく、操作が成功し、無効な要求識別子に対応する応答要素が nil になります。
部分更新
キャンペーン管理の部分更新
部分更新は、ほとんどのキャンペーン管理データ オブジェクトでサポートされていますが、一部のキャンペーン管理データ オブジェクトではサポートされていません。 たとえば、ExpandedTextAd の Text プロパティを更新する場合は、Id 要素と Text 要素のみを指定する必要があります。 広告の編集状態などの読み取り専用要素は、nil または空のままにする必要があります。 特に明記されていない限り、省略可能な要素は空のままであり、既存の設定は変更されません。
部分的な更新は、広告表示オプションではサポートされていません。 更新要求と共に送信されない省略可能な要素は、有効にそれぞれの広告拡張機能から削除されます。
顧客管理の部分的な更新
顧客管理サービスはエンティティの完全な更新を実行するため、文書化された必須プロパティに加えて、nil または空にしたくないすべての省略可能なプロパティの値を指定する必要があります。
注:
この規則の例外の 1 つは、任意のオブジェクトの ForwardCompatibilityMap 要素です。 たとえば、AdvertiserAccount の ForwardCompatibilityMap 要素を指定しない場合、キーと値のペアで表されるプロパティは更新または無効になりません。
エンティティ識別子をローカルに格納する
アカウントとキャンペーン エンティティのローカル ストアを管理する必要があります。 具体的には、アカウント、顧客、キャンペーン、広告グループ、キーワードの識別子をローカルに格納する必要があります。 ほとんどの呼び出しでは、エンティティの識別子が必要です。 識別子を格納する場合は、識別子を取得するために必要な呼び出しを排除します。
たとえば、キャンペーン管理の呼び出しの多くはアカウント識別子を必要とします。 アカウント識別子を取得するには、顧客管理サービスを使用できます。 ただし、サービスを繰り返し呼び出す代わりに、アカウント識別子をローカルに格納して、後続の呼び出しで使用できるようにします。
Web サービス呼び出しの作成に関連するオーバーヘッドを管理する
各 Web サービス呼び出しに関連付けられているオーバーヘッド コスト (処理時間) を次に示します。
- Web サービスへの HTTPS 接続の確立。
- ユーザー名とパスワードの認証。
- 開発者トークンの検証。
これらのコストは、1 つの項目を処理するか、一連の項目を処理するかに関係なく発生します。 オーバーヘッドを最小限に抑えるには、一般に、できるだけ多くの項目を 1 回の呼び出しで処理する必要があります。 たとえば、更新するキャンペーンごとに UpdateCampaigns を呼び出す代わりに、更新する複数のキャンペーンに対して 1 回だけ呼び出します。 大規模なデータを管理するには、特にアカウント内の複数の広告グループまたはキャンペーンに広告やキーワードを追加または更新する必要がある場合は、 Bulk サービスを使用する必要があります。 Bulk サービスを使用すると、データを TSV または CSV ファイルとしてダウンロードし、必要に応じて変更し、変更をアップロードできます。 一括サービスの使用の詳細については、「 一括ダウンロードとアップロード」を参照してください。
Web サービスへの接続の確立に関連するコストのため、必要な限り接続を維持する必要があります。 たとえば、複数のレポートを要求する必要がある場合は、すべてのレポート サービス操作呼び出しに同じレポート サービス クライアント オブジェクトを使用します。 サービスが不要になったら、接続を明示的に閉じます。
調整の処理
非常に大量の使用量を調整すると、すべての Microsoft Advertising クライアントの公平な使用が維持されます。
Ad Insight API
Ad Insight サービスの場合、調整により、1 人のユーザーが 1 分で実行できる API への呼び出しの数が制限されます。
顧客レベルでは、顧客が顧客データに対して行うことができる通話の数は、60 秒のウィンドウを持つスライディング プロトコルを使用して制限されます。
サービス呼び出しの制限を超えると、次のエラーが表示されます。
- 数値エラー コード: 117
- シンボリック エラー コード: CallRateExceeded
- メッセージ: 1 分で実行できる呼び出しの数を超えました。 1 分あたりの通話数を減らしてください。
このエラーが発生した場合は、60 秒待ってから制限の下で要求を再送信できます。
Bulk API
Bulk サービスでは、 DownloadCampaignsByAccountIds、 DownloadCampaignsByCampaignIds、 GetBulkUploadUrl に対して行うことができる要求の数が制限されます。 サービス制限の詳細は内部であり、変更される可能性があります。
サービス呼び出しの制限に達すると、次のエラーが表示されます。
- 数値エラー コード: 4204
- シンボリック エラー コード: BulkServiceNoMoreCallsPermittedForTheTimePeriod
- メッセージ: 現在の期間、このアカウントに対する一括アップロードまたはダウンロードの呼び出しは許可されません。一括アップロードの制限に達した場合、一括ダウンロード操作は引き続き使用できます。またはその逆の場合もあります。
このエラーが発生した場合は、最大 15 分待ってから要求を再送信できます。 詳細については、「 一括ダウンロードのベスト プラクティス 」と「 一括アップロードのベスト プラクティス」を参照してください。
また、運用環境での一括アップロードのファイルあたりのサイズ制限は 100 MB で、最大 400 万行であることに注意してください。 サンドボックスの場合、制限は 20,000 行です。
キャンペーン管理 API
キャンペーン管理サービスの場合、調整により、1 人のユーザーが 1 分で実行できる API への呼び出しの数が制限されます。
顧客レベルでは、顧客が顧客データに対して行うことができる通話の数は、60 秒のウィンドウを持つスライディング プロトコルを使用して制限されます。
サービス呼び出しの制限に達すると、次のエラーが表示されます。
- 数値エラー コード: 117
- シンボリック エラー コード: CallRateExceeded
- メッセージ: 1 分で実行できる呼び出しの数を超えました。 1 分あたりの通話数を減らしてください。
このエラーが発生した場合は、60 秒待ってから制限の下で要求を再送信できます。
Reporting API
Reporting サービスは、 SubmitGenerateReportRequest に対して行うことができる要求の数を制限します。 サービス制限の詳細は内部であり、変更される可能性があります。
サービス呼び出しの制限に達すると、次のエラーが表示されます。
- 数値エラー コード: 207
- シンボリック エラー コード: ConcurrentRequestOverLimit
- メッセージ: 既に同時レポート要求の最大数に達しています。 前のレポートが完了するまで待ってから、新しい要求を送信してください。
このエラーが発生した場合は、前のレポートが完了するまで待ってから、新しい要求を送信してみてください。