Ad Group Hotel Listing Group Record - Bulk

[アーティクル]
11/13/2024

一括ファイルでアップロードおよびダウンロードできる広告グループホテル登録情報グループを定義します。

次に説明するように検証規則が満たされている限り、同じ一括ファイル内の複数の広告グループの Ad Group Hotel Listing Group レコードをアップロードできます。

少なくとも、ホテルのリストグループツリー構造のルートノードを少なくとも指定する必要があります。ホテル一覧グループのルートノードには、 Hotel Attribute フィールドが "All" に設定され、ホテル属性値が null または空である必要があります。カタログ内のすべてのホテルに均等に入札する場合は、[ サブタイプ] フィールドを [単位] に設定します。より具体的なホテル属性に基づいて入札をパーティション分割する場合は、[ サブタイプ ] フィールドを [サブディビジョン] に、 親基準 ID を null または空に、 ID を 負の値に設定します。負の値は、任意の子ノードの 親基準 ID として使用します。
ルートノードはレベル 0 と見なされ、ツリーの深さは最大 7 レベルまで分岐できます。
アップロード要求ごとに、広告グループごとに最大 20,000 個のホテル登録情報グループツリーノードを含めることができます。広告グループのホテル一覧グループツリーノードの数全体が 20,000 を超えることはできません。
同じツリー (同じ広告グループ) のホテルリストグループツリーノードは、ファイル内でグループ化する必要があります。
ダウンロード中にホテルのリストグループノードの順序は保証されず、親ノードは子ノードの後に提供される場合があります。ただし、同じ広告グループのすべてのノードがファイルにグループ化されます。
ツリー構造を作成または変更する場合は、親ホテルのリストグループツリーノードを、子ホテルリストグループツリーノードの前に並べ替える必要があります。ただし、注文は、入札の更新などの構造以外の変更には関係ありません。たとえば、ツリー構造を追加、削除、更新せずに入札を更新する場合は、 ID、親 ID、入札フィールドのみをアップロードする必要があります。
Hotel Attribute、Hotel Attribute Value、Is Excluded フィールドを更新するには、既存のホテル登録情報グループツリーノードを削除し、新しい識別子を取得する新しいホテル一覧グループツリーノードをアップロードする必要があります。
いずれかのアクションが失敗した場合、それ以外の場合に成功した可能性がある残りのアクションもすべて失敗します。
すべてのホテル一覧グループノードの追加および削除アクションは、完全なツリー構造になる必要があります。
ルートノードからブランチの末尾までのすべてのパスは、リーフノード (Sub Type=Unit) で終了する必要があります。 [ 除外される] フィールドが true でない限り、すべてのユニットに入札が必要です。これは、ノードが負の広告グループ条件であることを意味します。
各サブディビジョンには、サブディビジョンの条件の残りの部分に入札するリーフノードが少なくとも 1 つ必要です。つまり、その兄弟単位と同じオペランドを使用し、ホテル属性値を null または空に設定します。
親と子の両方がまだ存在しない複数のレベルのパーティションを追加する場合は、負の int 値を参照として使用して親を識別します。たとえば、親の ID と子の 親基準 ID フィールドの両方を同じ負の値に設定します。負の ID は、呼び出しの期間中のみ有効です。正常に追加された広告グループの条件ごとに一意のシステム識別子がアップロード結果ファイルに返されます。
[ 入札 ] フィールドは、[ 除外される] フィールドが false の 場合にのみ適用されます。これは、ノードが入札可能な広告グループの条件であることを意味します。ただし、サブディビジョン パーティションノードの場合、Bid は無視されます。これらの要素は、 ユニット (リーフ) パーティションノードにのみ関連します。
ホテル登録情報グループを一時停止するには、広告グループの [状態] フィールドを [一時停止] に更新して、広告グループ全体を一時停止する必要があります。キャンペーン全体を一時停止するには、[キャンペーン] の [状態] フィールドを [一時停止] に更新します。
削除済みアクションの場合は、ID と親 ID のみを指定する必要があります。
親ホテル一覧グループを削除すると、そのすべての子と子孫も削除されます。
ブランチで重複するホテル属性を指定することはできません。

AdGroupHotelListingGroups の DownloadEntity 値を DownloadCampaignsByAccountIds または DownloadCampaignsByCampaignIds サービス要求に含めることにより、アカウント内のすべての Ad Group Hotel Listing Group レコードをダウンロードできます。さらに、ダウンロード要求には EntityData スコープを含める必要があります。ベストプラクティスを含む一括サービスの詳細については、「一括ダウンロードとアップロード」を参照してください。

次の一括 CSV の例では、有効な親 ID 値が指定されている場合に、新しい広告グループのホテル登録情報グループを追加します。

Type,Name,Campaign,Time Zone,Campaign Type,Language,Sub Type,Budget Id,Budget,Budget Type,Bid Strategy Type,Bid Strategy PercentMaxCpc,Ad Schedule Use Searcher Time Zone,Client Id,Id,Parent ID,Parent Criterion Id,Ad Group,Ad Group Type,Search Network,Content Network,Percent Cpc Bid,Hotel Ad Group Type,Percent Bid,Hotel Attribute,Hotel Attribute Value,Is Excluded
Format Version,6,,,,,,,,,,,,,,,,,,,,,,,,,
Campaign,,Test Hotel Campaign HLG,PacificTimeUSCanadaTijuana,Hotel,All,,delete_value,25,DailyBudgetStandard,PercentCpc,8.3,false,0,,,,,,,,,,,,,,
AdGroup,,Test Hotel Campaign HLG,,,,,,,,,,,,,,,Test Hotel AdGroup,Hotel,On,Off,3.74,HotelAd,,,,,
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Subdivision,,,,,,,,-1,,,Test Hotel AdGroup,,,,,HotelAd,,All,,false
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Unit,,,,,,,,-2,,-1,Test Hotel AdGroup,,,,,HotelAd,4.1,Brand,Marriott,false
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Unit,,,,,,,,-3,,-1,Test Hotel AdGroup,,,,,HotelAd,4.1,Brand,Hilton,false
Ad Group Hotel Listing Group,,Test Hotel Campaign HLG,,,,Unit,,,,,,,,-4,,-1,Test Hotel AdGroup,,,,,HotelAd,4.1,Brand,,false

.NET、Java、または Python 用の Bing Ads SDK を使用している場合は、 BulkServiceManager を使用して BulkAdGroupProductPartition オブジェクトをアップロードしてダウンロードする時間を節約できます。サービス操作を直接呼び出し、カスタムコードを記述して一括ファイル内の各フィールドを解析する代わりにします。

var uploadEntities = new List<BulkEntity>();

// Map properties in the Bulk file to the BulkAdGroupProductPartition
var bulkAdGroupProductPartition = new BulkAdGroupProductPartition
{
    // Map properties in the Bulk file to the BiddableAdGroupCriterion or
    // NegativeAdGroupCriterion object of the Campaign Management service.
    // Use the BiddableAdGroupCriterion to set the 'Is Excluded' field in the Bulk file to true,
    // and otherwise use the NegativeAdGroupCriterion to set the 'Is Excluded' field to false.
    BiddableAdGroupCriterion = new BiddableAdGroupCriterion
    {
        // 'Parent Id' column header in the Bulk file
        AdGroupId = adGroupIdKey,
        Criterion = new HotelListingGroup { 
            Condition = new HotelListingCondition
            {
                // 'Hotel Attribute Value' column header in the Bulk file
                Attribute = null,
                // 'Hotel Attribute' column header in the Bulk file
                Operand = "All",
            },
            // 'Parent Criterion Id' column header in the Bulk file
            ParentCriterionId = null
        },
        CriterionBid = new FixedBid
        {
            // 'Bid' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
            Amount = 0.50
        },
        // 'Id' column header in the Bulk file
        Id = null,
        // 'Status' column header in the Bulk file
        Status = AdGroupCriterionStatus.Paused,
        // 'Tracking Template' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
        TrackingUrlTemplate = null,
        // 'Custom Parameter' column header in the Bulk file is only applicable for BiddableAdGroupCriterion
        UrlCustomParameters = new CustomParameters
        {
            // Each custom parameter is delimited by a semicolon (;) in the Bulk file
            Parameters = new[] {
                new CustomParameter(){
                    Key = "promoCode",
                    Value = "PROMO1"
                },
                new CustomParameter(){
                    Key = "season",
                    Value = "summer"
                },
            }
        },
    },
    // 'Ad Group' column header in the Bulk file
    AdGroupName = null,
    // 'Campaign' column header in the Bulk file
    CampaignName = null,
    // 'Client Id' column header in the Bulk file
    ClientId = "ClientIdGoesHere",
};

uploadEntities.Add(bulkAdGroupProductPartition);

var entityUploadParameters = new EntityUploadParameters
{
    Entities = uploadEntities,
    ResponseMode = ResponseMode.ErrorsAndResults,
    ResultFileDirectory = FileDirectory,
    ResultFileName = DownloadFileName,
    OverwriteResultFile = true,
};

var uploadResultEntities = (await BulkServiceManager.UploadEntitiesAsync(entityUploadParameters)).ToList();

Ad Group Hotel Listing Group レコードの場合は、一括ファイルスキーマで次の属性フィールドを使用できます。

広告グループ
Bid
入札率
Campaign
クライアント ID
カスタムパラメーター
最終 URL サフィックス
Id
除外されます
変更時刻
親基準 ID
Parent Id
ホテル属性
ホテル属性値
状態
Sub Type
追跡テンプレート

広告グループ

ホテル登録情報グループを含む広告グループの名前。

追加： 読み取り専用と必須
更新： 読み取り専用と必須
削除： 読み取り専用と必須

注:

追加、更新、削除を行うには、[ 親 ID ] フィールドまたは [ 広告グループ ] フィールドを指定する必要があります。

Bid

オークションで入札する金額。これは、キャンペーン入札スキームが ManualCpc の場合に使用されます。

追加：Is Excluded が false で、サブタイプが Unit の場合は必須で、それ以外の場合は入札は許可されません。
更新： オプション。更新プログラムに値が設定されていない場合、この設定は変更されません。
削除： 読み取り専用

入札率

オークションで入札する金額。これは、キャンペーン入札スキームが PercentCpc または Commission の場合に使用されます。

キャンペーン

広告グループとホテル登録情報グループを含むキャンペーンの名前。

追加： 読み取り専用
更新： 読み取り専用
削除： 読み取り専用

クライアント ID

一括アップロードファイル内のレコードを結果ファイル内のレコードに関連付けるために使用されます。このフィールドの値は、サーバーによって使用または格納されません。アップロードされたレコードから対応する結果レコードにコピーされます。最大 100 の長さの任意の有効な文字列を指定できます。

追加： オプション
更新： オプション
削除： 読み取り専用

カスタムパラメーター

URL 追跡用のキーパラメーターと値パラメーターのカスタムコレクション。

一括ファイルでは、カスタムパラメーターの一覧は次のように書式設定されます。

各カスタムパラメーターペアを Key=Value (例: {_promoCode}=PROMO1) として書式設定します。
Microsoft Advertising は、含める最初の 8 つのカスタムパラメーターキーと値のペアを受け入れ、8 つ以上のカスタムパラメーターを含める場合はエラーが返されます。
各キーと値のペアは、セミコロンとスペース ("; ") で区切られます (例: {_promoCode}=PROMO1;{_season}=summer.
Key にはセミコロンを含めることはできません。 Value にセミコロンが含まれている場合は、'\;' としてエスケープする必要があります。さらに、Value に円記号が含まれている場合は、'\' としてもエスケープする必要があります。
キーは 16 UTF-8 バイトを超えることはできません。値は 250 UTF-8 バイトを超えることはできません。キーは必須であり、値は省略可能です。 Key の最大サイズには、中かっことアンダースコア ('{'、'_'、'}' は含まれません。

注:

Bulk サービスでは、Key は周囲の中かっこと先頭のアンダースコアで書式設定する必要があります。たとえば、Key が promoCode の場合は、{_promoCode} として書式設定する必要があります。キャンペーン管理サービスでは、周囲の中かっことアンダースコアを指定できません。

追加： オプション
更新： オプション。更新プログラムに値が設定されていない場合、この設定は変更されません。すべてのカスタムパラメーターを削除するには、このフィールドを delete_value に設定します。 delete_value キーワード (keyword)では、前の設定が削除されます。カスタムパラメーターのサブセットを削除するには、保持するカスタムパラメーターを指定し、保持しないパラメーターを省略します。カスタムパラメーターの新しいセットは、以前のカスタムパラメーターセットに置き換えられます。
削除： 読み取り専用

最終 URL サフィックス

最後の URL サフィックスには、ランディングページ URL の末尾に追加される追跡パラメーターを含めることができます。顧客が常にランディングページに送信されるように、ランディングページで必要な追跡パラメーターを最終的な URL サフィックスに配置することをお勧めします。詳細と検証規則については、テクニカルガイドの「最終 URL サフィックス」を参照してください。

追加： オプション
更新： オプション。更新プログラムに値が設定されていない場合、この設定は変更されません。このフィールドを delete_value 文字列に設定すると、前の設定は削除されます。
削除： 読み取り専用

Id

ホテル登録情報グループのシステム生成識別子。

追加： 読み取り専用
更新： 読み取り専用と必須
削除： 読み取り専用と必須

除外されます

ホテル登録情報グループが入札可能な条件と負の条件のどちらを表すかを決定します。

true に設定すると負の条件になり、false の場合は入札可能な条件になります。

追加： 必須
更新： 読み取り専用
削除： 読み取り専用

変更時刻

エンティティが最後に更新された日付と時刻。値は、世界協定時刻 (UTC) です。

注:

日付と時刻の値は、クライアントではなく、サーバーでの日付と時刻を反映します。日付と時刻の形式については、「プリミティブ XML データ型」の dateTime エントリを参照してください。

追加： 読み取り専用
更新： 読み取り専用
削除： 読み取り専用

親基準 ID

親ホテル一覧グループの基準識別子。

この一括フィールドは ParentNodeId にマップされ、ルートノードを指すには null にする必要があります。

注:

このフィールドは、親を持たないツリールートホテルリストグループノードには適用されません。

追加： 読み取り専用と必須
更新： 読み取り専用
削除： 読み取り専用

Parent Id

ホテル登録情報グループを含む広告グループのシステム生成識別子。

この一括フィールドは、広告グループレコードの Id フィールドにマップされます。

追加： 読み取り専用と必須。既存の広告グループ識別子を指定するか、親広告グループレコードの Id フィールドと等しい負の識別子を指定する必要があります。これは、同じ Bulk ファイル内の新しい広告グループに新しいホテル登録情報グループを追加する場合に推奨されます。詳細については、「一括ファイルスキーマ参照キー」を参照してください。
更新： 読み取り専用と必須
削除： 読み取り専用と必須

注:

追加、更新、削除を行うには、[ 親 ID ] フィールドまたは [ 広告グループ ] フィールドを指定する必要があります。

ホテル属性

条件のオペランド。オペランドには、equal 演算子が暗黙的に含まれます。たとえば、「 Brand as Brand=」と読むことができます。

Hotel 属性値のオペランドとして Hotel 属性を使用します。

キャンペーンと広告グループごとに複数のホテル属性を指定できます。ホテルの属性値がオペランドの属性値と等しい場合、各条件が満たされます。たとえば、オペランドが Brand に設定され、属性が Contoso に設定されている場合、ホテルカタログの Brand 属性の値が Contoso と等しい場合、条件が満たされます。

キャンペーンでは、ホテルの属性はキャンペーンレベルと広告グループレベルで設定できます。次の表では、 Ad Group Hotel Listing Group レコードの Hotel Attribute (オペランド) と Hotel Attribute Value (attribute) ビジネスルールについて説明します。

注:

ルートノードに対して Hotel Value が null または空に設定されている場合は、Hotel 属性を "すべて" にする必要があります。

ホテル属性 (オペランド)	ホテル属性値 (属性) 説明	Ad Group Hotel Listing Group Rules
すべて	該当なし。	広告グループのホテル登録情報グループの場合、ルートノードにはオペランドを "すべて" に設定し、属性を null または空に設定する必要があります。
ブランド	ホテルの製造元、ブランド、または発行元。最大 200 文字。	Brand オペランドは複数のブランチで使用できますが、ブランチごとに 1 回だけ指定できます。
カテゴリ	"Inn"、"Motel"、"Resort"などのホテルカテゴリ。最大 200 文字。	該当なし。
都市	ホテルが位置する都市。	該当なし。
国	ホテルがある国または地域。	該当なし。
CustomLabel0-4 CustomLabel0、CustomLabel1、CustomLabel2、CustomLabel3、CustomLabel4 など、5 つのカスタムラベルオペランド値を使用できます。	各 CustomLabel オペランドは複数のブランチで使用できますが、ブランチごとに 1 回だけ指定できます。たとえば、あるブランチには CustomLabel0 と CustomLabel1 が含まれている場合がありますが、 CustomLabel1 オペランドを持つ別のノードは含まれていない場合があります。最大 200 文字。	該当なし。
HotelId	ホテル識別子。最大 1,024 文字。	Id オペランドは複数のブランチで使用できますが、ブランチごとに 1 回だけ指定できます。
StarRating	1-5つ星のホテル評価。	該当なし。
状態	ホテルがある状態。	該当なし。

追加： 必須
更新： 読み取り専用。条件フィールドまたは値フィールドを更新することはできません。条件を更新するには、ホテル登録情報グループを削除し、新しいグループを追加する必要があります。
削除： 読み取り専用

ホテル属性値

条件の属性値。

状態

ホテル登録情報グループの状態。

使用可能な値は [アクティブ] または [削除済み] です。

追加： オプション。使用可能な状態は [アクティブ] のみです。状態を [削除済み] に設定すると無視され、返されたレコードの状態が [アクティブ] に設定されます。
更新： オプション
削除： 必須。 [状態] を [削除済み] に設定する必要があります。

Sub Type

ホテル登録情報グループの種類。

可能な値は 、サブディビジョン と ユニットです。

追加： 必須
更新： 読み取り専用
削除： 読み取り専用

追跡テンプレート

追跡テンプレートは、 Content API を使用して送信したホテルオファーの [リンク] フィールドに指定された URL と組み合わせて使用できます。フィード URL と追跡テンプレートを組み合わせることで、ランディングページ URL が組み立てられます。この URL は、広告をクリックした後にユーザーが誘導されます。 [追跡テンプレート] フィールドを使用して、フィード URL で URL パラメーターを更新するのではなく、URL パラメーターを更新する場合、フィード URL は編集レビューを通過する必要がないため、広告は中断なく配信されます。たとえば、カタログフィードのホテルオファー URL がである場合は https://contoso.com/、次の追跡テンプレート {lpurl}?matchtype={matchtype}&device={device}を指定できます。

追跡テンプレートには、次の検証規則が適用されます。サポートされているテンプレートとパラメーターの詳細については、Microsoft Advertising のヘルプ記事「どのような追跡または URL パラメーターを使用できますか?」を参照してください。

広告など、下位レベルのエンティティに対して定義された追跡テンプレートは、キャンペーンなどの上位レベルのエンティティに対する設定をオーバーライドします。詳細については、「エンティティの制限」を参照してください。
追跡テンプレートの長さは 2,048 文字に制限されています。 HTTP または HTTPS プロトコル文字列は、2,048 文字の制限にカウントされます。
追跡テンプレートは、 http://、 https://、 {lpurl}、または {unescapedlpurl} のいずれかで始まる適切な形式の URL である必要があります。
Microsoft Advertising では、カスタムパラメーターが存在するかどうかを検証しません。追跡テンプレートでカスタムパラメーターを使用し、それらが存在しない場合、ランディングページ URL には、代替なしでカスタムパラメーターのキーと値のプレースホルダーが含まれます。たとえば、トラッキングテンプレートがでhttps://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}、キャンペーン、広告グループ、条件、キーワード (keyword)、または広告レベルで {_season} または {_promocode} が定義されていない場合、ランディングページの URL は同じになります。

次の方法で共有

Ad Group Hotel Listing Group Record - Bulk

広告グループ

Bid

入札率

キャンペーン

クライアント ID

カスタムパラメーター

最終 URL サフィックス

Id

除外されます

変更時刻

親基準 ID

Parent Id

ホテル属性

ホテル属性値

状態

Sub Type

追跡テンプレート

フィードバック

その他のリソース

次の方法で共有

Ad Group Hotel Listing Group Record - Bulk

広告グループ

Bid

入札率

キャンペーン

クライアント ID

カスタム パラメーター

最終 URL サフィックス

Id

除外されます

変更時刻

親基準 ID

Parent Id

ホテル属性

ホテル属性値

状態

Sub Type

追跡テンプレート

フィードバック

その他のリソース

カスタムパラメーター