一括ファイル スキーマ
一括スキーマは、Bulk API を使用してダウンロードまたはアップロードするファイルの内容を定義します。 一括サービスは、ダウンロードとアップロードの両方で、 DownloadEntity 値セット内のファイルの種類と対応するスキーマをサポートします。
一括サービスを使用してキャンペーンを管理する方法の詳細については、「 一括ダウンロードとアップロード」を参照してください。 データ ファイルの内容の詳細については、以下のセクションを参照してください。
ファイル スキーマ
タブまたはコンマで区切られたレコード (行) とフィールド (列) のセットをダウンロードできます。 最初の列ヘッダーの名前は Type です。 列名の残りの部分は、対応するレコードの種類内または関連するプロパティにマップされます。
重要
新しいレコードの種類 (行) とフィールド (列) はいつでも追加できます。一括ダウンロードまたは一括アップロードの結果ファイルのレコードまたはフィールドの順序に依存しないでください。 同様に、参照ドキュメントに特に記載がない限り、各フィールドで返される固定の値セットに依存しないでください。
同様に、アップロード中に任意の順序でフィールドを送信できます。 次の 「タイプ階層」で説明されているように、新しいエンティティを作成する場合は、アップロード レコードの順序が重要です。
バージョンの書式設定
一括形式のバージョンは、Bing Ads API バージョンとは別です。 フォーマット バージョンを使用すると、柔軟なアップグレード パスで、アプリケーションを中断することなく、サポートされている最新の機能を採用できます。 ベスト プラクティスとして、常に最新の形式バージョンにアップグレードする必要があります。 現在、サポートされている唯一のフォーマット バージョンは 6.0 です。
一括ダウンロードを使用してファイル形式のバージョンを指定するには、DownloadCampaignsByAccountIds または DownloadCampaignsByCampaignIds 要求で FormatVersion を 6.0 に設定します。
一括アップロードを使用してバージョンを指定するには、[バージョンの書式設定] レコードの [名前] フィールドを 6.0 に設定します。
レコードの種類
Format Version 6.0 を使用してアップロードおよびダウンロードできるレコードの詳細を次の表に示します。
重要
新しいレコードの種類 (行) とフィールド (列) はいつでも追加できます。一括ダウンロードまたは一括アップロードの結果ファイルのレコードまたはフィールドの順序に依存しないでください。
型階層
ダウンロード ファイルには、常に [バージョンの書式設定 ] と [ アカウント レコードの種類] のレコードが含まれます。 アップロードするには、 フォーマット バージョン が必要であり、一括ファイル内の他のすべてのレコードの種類の前に置く必要があります。
親エンティティが同じファイルに作成された場合は、一括ファイル内の依存する子レコードの前に配置する必要があります。 たとえば、次の図に示すように、サイト リンク広告拡張機能をキャンペーンに関連付ける場合、 キャンペーン サイトリンク広告拡張機能 レコードは、 キャンペーン と サイトリンク広告拡張機能 の両方のレコードの後にファイルに含める必要があります。 [キャンペーン サイトリンク広告拡張機能] レコードの [ID] フィールドと [親 ID] フィールドは、それぞれ Sitelink Ad Extension レコードと Campaign レコードの識別子に設定する必要があります。 Sitelink Ad Extension レコードと Campaign レコードも新規で、まだ Microsoft Advertising 識別子が割り当てられていない場合は、参照キーを使用する必要があります。
有効な Microsoft Advertising 識別子が既に割り当てられている親エンティティのレコードを含める必要はありません。
一括ファイル レコードの追加、更新、削除では、部分的な成功がサポートされます。 たとえば、3 つのキャンペーンを追加しようとして、2 つだけがファイルに正しく指定されている場合、2 つが追加されます。 結果ファイルには、成功したキャンペーン レコード、1 つのキャンペーン レコード、および 1 つのキャンペーン エラー レコードの詳細が含まれます。
同じファイルにキャンペーン、広告グループ、テキスト広告、キーワードを追加する場合など、新しいキャンペーン識別子がまだ不明な場合は、子レコードの論理参照キーとしてキャンペーン名を指定します。 アップロードで既存の親を指定する必要はありません。
部分的な更新は、除外キーワード、除外サイト、ターゲット条件などの一括レコードでサポートされます。 たとえば、1 つの場所の条件の入札を更新することができ、キャンペーンまたは広告グループのターゲット条件のセット全体をダウンロードしてアップロードする必要はありません。
レコードを更新する場合は、更新されたレコードの [Id ] フィールドが必要です。 親レコードの 親 ID または 参照キー も必要です。
キャンペーンまたは広告グループ名を更新する場合、正しい 親 ID が指定されている場合は、子レコードの新しい名前を指定することは省略可能です。
あるレコードセットを別のセットに置き換える場合は、新しいセットの前に削除されたレコードを指定する必要があります。 たとえば、特定のキャンペーンの既存の キャンペーン除外キーワード をすべて置き換えるには、まずキャンペーン の除外キーワード を [ステータス] を [削除済み] に、 親 ID をキャンペーン ID に設定します。 ID を指定しない場合、つまり、特定の camapaign 否定キーワードの削除を試みない場合、そのキャンペーンのすべてのキャンペーンの除外キーワードが実質的に削除されます。 [すべて削除] レコードの下に、アップロード追加操作に必要なすべてのプロパティを含む 1 つ以上の新しい キャンペーン除外キーワード レコードを含めることができます。
既存のレコードを、同じ一意のプロパティを持つ新しいレコードに置き換える場合は、新しいレコードの前に削除されたレコードを指定する必要があります。 たとえば、特定の広告グループの既存の広告グループ動的検索広告ターゲットを置き換えるには、最初に[ステータス]が [削除済み]、[Id]\(既存の動的広告ターゲット(Web ページ基準)ID に設定された ID)、[親 ID]が広告グループ ID に設定されている広告グループ動的検索広告ターゲットを含めます。 削除されたレコードの下に、新しい Ad Group Dynamic Search Ad Target レコード (おそらく新しい Web ページ条件) を含めることができます。
注:
ほとんどの場合、レコードを個別に削除して追加するのではなく、既存のレコードを更新できます。たとえば、既存のキャンペーン性別基準の [入札調整] フィールドを更新できます。
レコードを削除する場合は、 Id フィールドが必要です。 値が Microsoft Advertising 割り当てシステム識別子であるか、親レコードの 参照キー であるかに関係なく、親エンティティへの参照も必要です。 たとえば、広告グループを削除する場合、広告グループ レコードの [親 ID] フィールドが [キャンペーン] レコードの [Id] フィールドと一致するか、広告グループ レコードの [キャンペーン] フィールドが [キャンペーン] レコードの [キャンペーン] フィールドと一致する必要があります。 両方が指定されている場合、広告グループ レコードの [親 ID] フィールド (参照キー) は無視されます。
いくつかの例外を除き、結果ファイルにはアップロードした列のみが含まれます。 たとえば、Id 列ヘッダーなしで新しい Ad Group Negative Keyword をアップロードした場合、結果ファイルには新しい負のキーワードに割り当てられた識別子は含まれません。 一括ファイルには Id 列が含まれている必要があります。ただし、新しい広告グループの除外キーワードごとに ID は空のままにする必要があります。 このルールの例外は、キャンペーン、広告グループ、広告、キーワードです。その場合、アップロードされた列に関係なく、結果ファイルにすべての列が含まれます。
delete_valueで更新する
既存の設定を削除するには、Bulk サービスによってそのような文字列が無視されるため、Bulk ファイルに空の文字列 ("") を書き込む必要はありません。 予約された "delete_value" 文字列を使用して、省略可能なフィールドの値を削除またはリセットします。
- 省略可能なフィールドで予約済みの "delete_value" 文字列を使用すると、前の設定が削除されます。 たとえば、広告グループ レコードの [カスタム パラメーター] フィールドを "delete_value" に設定した場合、以前のカスタム パラメーターはすべて広告グループから削除されます。 同様に、広告グループ レコードの [追跡テンプレート] フィールドを "delete_value" に設定すると、前の追跡テンプレートが広告グループから削除されます。
- .NET、Java、Python 用の Bing Ads SDK では、該当する場合は自動的に "delete_value" が書き込まれます。 詳細については、「 Bulk Service Manager - update with delete_value」を参照してください。
必須フィールドに"delete_value"を使用する場合は、次の点にご注意ください。
- 必要なプリミティブ値の代わりに予約された "delete_value" 文字列を使用する場合、無視されます。 フィールドは更新されませんでしたが、"delete_value" 文字列はアップロード結果ファイルを介して渡されます。 たとえば、広告グループ レコードの [広告グループ ] フィールド ( 広告グループ 名) を "delete_value" に設定した場合、広告グループの名前は更新されません。
- 必要な値セットの代わりに予約された "delete_value" 文字列を使用すると、フィールドが既定値に更新され、結果ファイルにその変更が反映されます。 たとえば、広告グループ レコードの [ネットワーク配布] フィールドを "delete_value" に設定した場合、広告グループのネットワーク配布は OwnedAndOperatedAndSyndicatedSearch に設定され、アップロード結果ファイルにも同じ内容が反映されます。
参照キー
Microsoft Advertising 識別子がまだ割り当てられていない一括ファイル内の先行するレコードを参照する場合は、レコードの種類に応じて論理参照キーまたは負の参照キーを使用できます。
注:
親エンティティが同じファイルに作成される場合は、一括ファイル内の依存する子レコードの前に配置する必要があります。
負の参照キー
Microsoft Advertising 識別子がまだ割り当てられていない一括ファイル内の先行するレコードを参照する場合は、拡張機能の Id フィールドを任意の負の数に設定できます。 このカスタム ID は、負の参照キーと呼ばれます。 その後、依存レコードの Id フィールド内で負の参照キーを使用できます。
最初の例は、新しいキャンペーンの 広告グループ を作成する方法を示 しています。 [広告グループ] レコードの [親 ID] フィールドを、キャンペーンの負の参照キー (-111) に設定します。 同じファイルに、広告グループを親とするレコードを追加する場合 (キーワードや広告グループ吹き出し広告拡張機能など)、広告グループの [Id] フィールドを負の値 (子レコードから参照できる -1111 など) に設定する必要もあります。
| 型 | Id | Parent Id |
|---|---|---|
| キャンペーン | -111 | |
| 広告グループ | -1111 | -111 |
2 番目の例は、新しいキャンペーンと新しい吹き出し広告拡張機能のキャンペーン吹き出し広告拡張機能を作成する方法を示しています。 この例では、新しい広告グループと別の新しい吹き出し広告拡張機能の広告グループ吹き出し広告拡張機能を作成する方法も示しています。
- [キャンペーン吹き出し広告拡張機能] レコードの [親 ID] フィールドをキャンペーンの負の参照キー (-111) に設定し、[キャンペーン吹き出し広告拡張機能] レコードの [Id] フィールドを吹き出し広告拡張機能 (-11) の負の参照キーに設定します。
- [広告グループ吹き出し広告拡張機能] レコードの [親 ID] フィールドを広告グループの負の参照キー (-1111) に設定し、[広告グループ吹き出し広告拡張機能] レコードの [Id] フィールドを吹き出し広告拡張機能 (-12) の負の参照キーに設定します。
| 型 | Id | Parent Id |
|---|---|---|
| 吹き出し広告拡張機能 | -11 | |
| 吹き出し広告拡張機能 | -12 | |
| キャンペーン | -111 | |
| 広告グループ | -1111 | -111 |
| キャンペーンの吹き出し広告拡張機能 | -11 | -111 |
| 広告グループの吹き出し広告拡張機能 | -12 | -1111 |
論理参照キー
新しい [キャンペーン] レコードまたは [広告グループ] レコードを参照する場合は、[ 親 ID ] フィールドを子レコード内の 負の参照キー に設定する代わりに、キャンペーンと広告グループ名を使用できます。 たとえば、新しい広告グループを新しいキャンペーンに追加し、新しい広告グループに新しいキーワードを追加するには、次の例に示すように、子レコードの [キャンペーン] フィールドと [広告グループ] フィールドを設定します。
| 型 | キャンペーン | 広告グループ |
|---|---|---|
| キャンペーン | レディースシューズ | |
| 広告グループ | レディースシューズ | 女性の赤い靴の販売 |
クライアント識別子
クライアント識別子を使用して、一括アップロード ファイル内の入力レコードを結果ファイルの出力レコードに関連付けることができます。 たとえば、新しいレコードを追加するときに、[ クライアント ID ] フィールドを選択した文字列値に設定できます。 Microsoft Advertising システムは、クライアント識別子に変更を加えず、対応するレコードの結果ファイルに渡します。
エラー
一括ダウンロード ファイルまたは一括アップロード結果ファイルには、対応する [種類] フィールドに Error サフィックスが含まれるレコードが含まれている場合があります。 たとえば、 製品広告エラー レコードの種類は、製品広告エラーを表します。 [エラー] 列と [エラー番号] 列には、エラーに関する詳細が含まれます。
注:
アップロード結果ファイルには、アップロードされた 1 つのレコードに対応する複数のエラー レコードが含まれる場合があります。
[最終 URL] などの新機能に関連するエラーには、[ フィールド パス ] 列でエラーが発生した場所に関する追加の詳細が含まれます。 各フィールド パス名は、 キャンペーン管理サービス のデータ オブジェクトの 1 つの要素に対応します。 たとえば、キャンペーン レコードの [追跡テンプレート] フィールドが、http:// または https:// {lpurl}、{unescapedlpurl} で始まらない場合、このフィールド パス値の値は TrackingTemplate です。 TrackingUrlTemplate は、キャンペーン管理サービスで使用できるキャンペーン データ オブジェクトの要素です。
| 型 | 追跡テンプレート | Error | エラー番号 | フィールド パス |
|---|---|---|---|---|
| キャンペーン エラー | tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} | InvalidUrlScheme | 4600 | TrackingTemplate |
| キャンペーン エラー | tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl} | CampaignServiceInvalidUrl | 2611 | TrackingTemplate |
重要
[フィールド パス] の値は変更される可能性があるため、現在の文字列形式に依存しないようにしてください。 フィールド パスは、すべてのエラーでサポートされているわけではありません。 これは、各キャンペーン、広告グループ、拡張テキスト広告、製品広告、広告グループ製品パーティション、キーワード、およびサイトリンク広告拡張機能レコードのモバイル最終 URL、最終 URL、追跡テンプレート、およびカスタム パラメーター フィールドでサポートされています。 また、吹き出し広告拡張機能レコードおよびレビュー広告拡張機能レコードのすべてのフィールドに関連するエラーにも対応しています。
問題が編集エラーに関連している場合は、[ 編集場所]、[ 編集用語]、[ 編集理由コード]、[ パブリッシャーの国] 列にも、エラーに関する詳細情報が含まれている可能性があります。