一括ダウンロードとアップロード

一括サービスを使用すると、バックグラウンドでキャンペーン設定を非同期的にダウンロードしてアップロードできます。 大規模なデータを管理するには、特にアカウント内の複数の広告グループやキャンペーンに広告やキーワードを追加または更新する必要がある場合は、Bulk サービスを使用することをお勧めします。 一部のエンティティでは、入札候補と品質スコア データをダウンロードすることもできます。 同じファイル内の他のレコードにエラーが含まれているかどうかにかかわらず、各レコードを正常にアップロードできます。 ダウンロードおよびアップロード ファイルに使用されるスキーマ (使用可能なエンティティ、入札候補、品質スコア データの詳細など) については、「 一括ファイル スキーマ」を参照してください。

.NET 言語、Java、または Python を使用している場合は、 Bing Ads API クライアント ライブラリを使用する必要があります。 .NET、Java、Python SDK では、以下で説明する低レベルの詳細が抽象化されています。 たとえば、 DownloadCampaignsByAccountIds と GetBulkDownloadStatus を呼び出してファイルをダウンロードする代わりに、 BulkServiceManager クラスで 1 つのメソッドを使用できます。 SDK で一括ダウンロードとアップロードを使用する方法の詳細については、「一括Service Manager」を参照してください。

一括ダウンロード

アカウントのキャンペーン データをダウンロードするには、 DownloadCampaignsByAccountIds 操作を 呼び出します。 特定のキャンペーンのデータをダウンロードするには、 DownloadCampaignsByCampaignIds 操作を 呼び出します。

一括ファイルのダウンロード

キャンペーンのすべてのデータ、またはキャンペーンのデータを最後にダウンロードした後に変更されたデータのみを要求できます。 どちらのダウンロード操作でも、要求設定とダウンロード ワークフローの概要を次に示します。

1. 要求の DataScope 要素を設定し、エンティティ データに加えて入札候補または品質スコア データを含めるかどうかを指定します。 使用可能な値の一覧については、 DataScope 値セットに関するページを参照してください。

2. 要求の DownloadFileType 要素を設定して、ダウンロード ファイルの形式として Csv または Tsv を選択します。

   注:

   ダウンロードした Csv または Tsv ファイルは、指定した CompressionType に応じて圧縮された ZIP または GZIP になります。 CompressionType を指定しなかった場合、ZIP は既定値です。

3. キャンペーン、広告グループ、広告、キーワードエンティティを含むように、要求の Entities 要素を設定します。 必要に応じて、ダウンロードに除外キーワードやターゲットなどの追加エンティティを含めることができます。 要求できるエンティティの一覧については、 DownloadEntity 値セットに関するページを参照してください。

4. 要求の LastSyncTimeInUTC 要素を前のダウンロードのタイム スタンプに設定して、前回のダウンロード以降に更新または削除されたエンティティのみを要求します。

   注:

   指定したエンティティのダウンロードを初めて要求する場合は、要求の LastSyncTimeInUTC 要素を NULL に設定して、使用可能なすべてのエンティティをダウンロードします。

5. DownloadCampaignsByAccountIds または DownloadCampaignsByCampaignIds 操作でダウンロード要求を送信します。

6. ダウンロード要求は、 GetBulkDownloadStatus 操作に渡す識別子を返します。 ダウンロードが完了するか失敗するまで、 ループで GetBulkDownloadStatus 操作を呼び出します。 ダウンロードが完了するまでにかかる時間は、要求したキャンペーンの数や、キューに既に存在する要求の数など、さまざまな変数によって異なります。 これらの変数により、使用するポーリング間隔が異なる場合があります。 ダウンロード要求を送信した時点からファイルをダウンロードするには、2 日間かかります。 この期間内にファイルが正常にダウンロードされていない場合は、ダウンロード サイトから削除され、ダウンロード操作の 1 つをもう一度呼び出す必要があります。

7. GetBulkDownloadStatus 操作が正常に完了すると、ダウンロード ファイルの URL が返されます。 URL を使用して、ダウンロード ファイルをローカルにコピーします。 URL は、 GetBulkDownloadStatus 操作が 成功 状態コードを返す 5 分以内に使用する必要があります。 この期間内にダウンロードを開始しない場合は、 GetBulkDownloadStatus をもう一度呼び出して新しい URL を取得する必要があります。

8. ダウンロード ファイルは zip 形式で圧縮されているため、データにアクセスするにはファイルを解凍する必要があります。 ダウンロード ファイルに使用されるスキーマの詳細については、「 一括ファイル スキーマ」を参照してください。

ベスト プラクティスのダウンロード

ベスト プラクティスに従って、自分自身とすべての Microsoft Advertising クライアントの公平な使用を確保してください。

• 必要な一括ダウンロード エンティティのみを要求します。 新しいレコードの種類 (行) とフィールド (列) はいつでも追加できます。一括ダウンロードまたは一括アップロードの結果ファイルのレコードまたはフィールドの順序に依存しないでください。

• 完全ダウンロードを 1 回だけ実行します。 その後、差分ダウンロードを実行します。 LastSyncTimeInUTC を最後のダウンロードのタイム スタンプに設定します。 ダウンロード ファイルには、アカウント レコードの SyncTime 列にダウンロードのタイム スタンプが含まれています。 毎回フルダウンロードを実行することに利点はなく、あなたのことを含むすべての人のパフォーマンスが低下します。

• 適切な間隔でダウンロードをポーリングします。 データは誰よりもよく知っている。 キーワードが 100 万未満のアカウントをダウンロードする場合は、15 秒から 20 秒間隔でポーリングすることを検討してください。 アカウントに約 100 万のキーワードが含まれている場合は、5 分待ってから 1 分間隔でポーリングすることを検討してください。 約 400 万個のキーワードを持つアカウントの場合は、10 分待ってから 1 分間隔でポーリングすることを検討してください。

• アカウントに 400 万を超えるキーワードが含まれている場合は、 DownloadCampaignsByCampaignIds 操作を呼び出します。 400 万を超えるキーワードを含むアカウントで DownloadCampaignsByAccountIds 操作を呼び出すと失敗します。

• DownloadCampaignsByCampaignIds 要求に含めるキャンペーンを減らしたい場合があります。 800 万を超えるキーワードを含むアカウントで DownloadCampaignsByCampaignIds 操作を呼び出すと失敗します。 呼び出しごとに少ないキャンペーンを指定する要求は、通常、許可される最大数を指定する呼び出しよりも早く完了します。

一括アップロード

一括アップロード ファイルは、HTTP POST を使用して、一括サービスによって提供される URL に送信できます。

アップロード ファイルに使用するスキーマの詳細については、「 Bulk File Schema」を参照してください。

一括ファイルのアップロード

要求設定とアップロード ワークフローの概要を次に示します。

1. GetBulkUploadUrl 要求の AccountId 要素を、アップロードされるデータに対応するアカウント識別子に設定します。

2. GetBulkUploadUrl 要求の ResponseMode 要素を設定して、サービスがエラーとそれに対応するデータを返すか、結果ファイル内のエラーのみを返すかを指定します。 詳細については、「 ResponseMode」を参照してください。

3. GetBulkUploadUrl 応答で返された UploadUrl を使用して、HTTP POST を使用して一括アップロード ファイルを送信します。 コンテンツ タイプは マルチパート/フォーム データである必要があります。 UTF-8 ファイルには、バイト順マーク (BOM) を含める必要があります。 ZIP 圧縮アップロードには、 CSV または Tsv 形式の 1 つのファイルが含まれている必要があります。 ZIP ファイルは、中央ディレクトリ レコードの末尾を含め、適切に構成されている必要があります。

   注:

   HTTP 標準の Authorization ヘッダーは使用されません。 認証するには、DeveloperToken、CustomerId、CustomerAccountId ヘッダーなど、HTTP クライアントの Microsoft Advertising カスタム ヘッダー要素を追加して設定する必要があります。 AuthenticationToken ヘッダー要素を使用してユーザー資格情報を設定する必要もあります。 詳細については、「 OAuth による認証 」および「 API 資格情報を使用する場所」を参照してください。

   GetBulkUploadUrl、HTTP POST、および GetBulkUploadStatus ワークフロー全体で同じユーザー資格情報を使用する必要があります。

   次に例を示します。

   POST <UploadUrl> HTTP/1.1
   AuthenticationToken: <AuthenticationToken>
   DeveloperToken: <DeveloperToken>
   CustomerId: <CustomerId>
   AccountId: <AccountId>
   Content-Type: multipart/form-data;
   

4. HTTP 応答の状態コードを確認します。 HTTP 応答状態コードが 200 の場合、ファイルは Microsoft Advertising によって正常に受信されました。 HTTP 応答状態コードが 401 の場合、認証に失敗しました ( AuthenticationToken や DeveloperToken が無効でした)。 HTTP 応答ステータス コードが 400 の場合は、応答ストリームで、たとえば 3220 から 3227 の範囲で、 Bing Ads API 操作エラー コード も確認する必要があります。

   URL が一括ファイルのアップロードに既に使用されていたエラー応答メッセージの例を次に示します。

   HTTP/1.1 400 Bad Request
   Cache-Control: private
   Content-Type: application/json; charset=utf-8
   Server: Microsoft-IIS/8.0
   X-AspNetMvc-Version: 3.0
   X-AspNet-Version: 4.0.30319
   X-Powered-By: ASP.NET
   Date: Tue, 12 Jan 2016 17:07:23 GMT
   Content-Length: 224
   
   {"TrackingId":"16bd93cc-22fb-4d3c-94be-25adefd06fae","RequestId":"26c3fbf6-3e24-4569-ada3-d4e8b3d0aecc","Code":3224,"ErrorCode":"BulkServiceUrlAlreadyUsedForUpload","Message":"The URL has already been used for file upload."}
   

5. GetBulkUploadUrl 応答には、GetBulkUploadStatus 操作に渡す RequestId も含まれています。 アップロードが保留中の間、アップロードが完了するか失敗するまで、ループ内で GetBulkUploadStatus 操作を呼び出すことができます。 アップロード要求を送信した時点からアップロード結果ファイルをダウンロードするには、15 分かかります。 この期間内にファイルが正常にダウンロードされていない場合は、ダウンロード サイトから削除され、取得されない可能性があります。 この機会の期間を逃した場合は、いずれかのダウンロード操作を呼び出して、最新のエンティティ データを取得できます。

6. GetBulkUploadStatus 操作が正常に完了すると、アップロード結果ファイルの URL が返されます。 URL を使用して、結果ファイルをローカルにコピーします。 この URL は、 GetBulkUploadStatus 操作が Completed 状態応答文字列を返す 15 分以内に使用する必要があります。 この期間内にダウンロードを開始しない場合は、 GetBulkUploadStatus をもう一度呼び出して新しい URL を取得する必要があります。

   注:

   アップロード結果ファイルの形式は Csv または Tsv で、アップロード用に送信したファイルの形式と一致します。

アップロードのベスト プラクティス

ベスト プラクティスに従って、自分自身とすべての Microsoft Advertising クライアントの公平な使用を確保してください。

• ファイルが大きいと、アップロードのパフォーマンスが低下する可能性があります。 オプションであり、アップロードのためにファイルを圧縮することをお勧めします。 圧縮する場合は、対応する拡張子を持つ ZIP 形式にする必要があります。 運用環境でのアップロードのファイル サイズ制限は 100 MB で、最大 400 万行です。 サンドボックスの場合、制限は 20,000 行です。 顧客ごとに同時アップロードを 5 または 6 未満に制限できる場合は、ファイル サイズの制限に近づくのではなく、ファイルを分割することを検討してください。

• ファイルを並行してアップロードするには、同時アップロードを顧客ごとに 5 または 6 に制限します。 前のファイルが処理されるまで各スレッドで待機し、スレッドを再利用して別のファイルをアップロードできます。 たとえば、1 つのスレッドがファイルをアップロードでき、アップロードの状態が Completed、 CompletedWithErrors、または Failed の場合、そのスレッドは別のファイルをアップロードできます。

• 追加または更新するエンティティとフィールドのみをアップロードします。 指定した場合、入札候補や品質スコア データなどの読み取り専用フィールドは無視されます。

• パフォーマンスを最大化するために、ファイルごとに 1 つのエンティティの種類をアップロードします。 新しいキャンペーン、広告、キーワードを作成する場合、 参照キーと一緒にアップロードする方が効率的な場合など、いくつかの例外があります。 別の例として、10 個のキャンペーン、500 個の広告、800 個のキーワードのみを更新している場合は、種類ごとにアップロードを分割するのではなく、1 つのアップロードに含めることができます。

• アップロード結果ファイルでエラーと結果 (ResponseMode = ErrorsAndResults) を要求する必要があるかどうか、またはエラーのみ (ResponseMode = ErrorsOnly) で十分かどうかを検討します。 結果をローカル データと同期する必要があるかどうかを検討します。 たとえば、エンティティを更新する場合は、エラーが発生したかどうかを把握するだけで済み、その場合は GetBulkUploadUrl 要求で ResponseMode = ErrorsOnly を指定できます。 新しいエンティティを追加する場合は、GetBulkUploadUrl 要求で ResponseMode = ErrorsAndResults を指定して、結果のエンティティ識別子を受け取ることができます。

• 部分的な再試行の場合は、レコードのサブセットのみがエラーになった場合は、ファイル全体をアップロードしないでください。 再試行するレコードのみをアップロードします。

• アップロードの状態が Completed、 CompletedWithErrors、または Failed になるまで再試行しないでください。 偶然のパフォーマンスが期待を満たしていない場合は、とにかく結果を待ってください。

• 適切な間隔でアップロード結果をポーリングします。 最初は、アップロードされた 10,000 行ごとに 1 分待つ必要があります。 最初の待機時間が経過したら、1 分間隔でポーリングすることを検討してください。

関連項目

一括サービス リファレンス
Bing Ads API Web サービス アドレス