廣告群組旅館清單群組記錄 - 大量

發行項
11/13/2024

定義可在大量檔案中上傳和下載的廣告群組旅館清單群組。

只要符合驗證規則，您可以在同一個大量檔案中上傳多個廣告群組的廣告 群組旅館清單群組 記錄，如下所述。

您至少必須指定旅館清單群組樹狀結構的根節點。旅館清單群組的根節點必須將其 Hotel Attribute 字段設定為 “All” 和 Hotel Attribute Value null 或空白。如果您同樣地在目錄中的所有旅館上，請將 [子類型 ] 字段設定為 [單位]。如果您要根據更特定的旅館屬性來分割報價，請將 [子類型 ] 字段設定為 [細分]，將 [父準則標識 符] 設定為 null 或空白，並將 [ 標識符] 設定為負值。對於任何子節點，您都會使用負值作為 父準則標識 符。
根節點會被視為層級 0，而樹狀結構最多可以有 7 層深的分支。
根據上傳要求，每個廣告群組最多可以包含 20,000 個旅館清單群組樹狀節點。廣告群組的整個旅館清單群組樹狀節點計數不能超過 20,000。
相同樹狀結構的旅館清單群組樹狀節點 (相同的廣告群組) 必須在檔案中群組在一起。
在下載期間不保證旅館清單群組節點的順序，而且父節點可能會在子節點之後提供;不過，相同廣告群組的所有節點都會群組在檔案中。
如果您要建立或修改樹狀結構，則必須在子旅館清單群組樹狀節點之前排序父旅館清單群組樹狀節點;不過，順序對於非結構化變更並不重要，例如更新報價。例如，如果您想要在不新增、刪除或更新樹狀結構的情況下更新約定，則只需要上傳 [ 標識符]、[ 父標識符] 和 [ 標示] 字段。
若要更新 [ 旅館屬性]、[ 旅館屬性值 ] 或 [ 已排除 ] 字段，您必須刪除現有的旅館清單群組樹狀節點，並上傳新的旅館清單群組樹狀節點，以取得新的標識符。
如果有任何動作失敗，可能已成功的所有剩餘動作也會失敗。
所有旅館清單群組節點新增和刪除動作都必須產生完整的樹狀結構。
從根節點到分支結尾的每個路徑都必須以分葉節點終止， (子類型=單位) 。除非 [已排除 ] 字段為 true ，否則每個單位都必須有一個報價，這表示節點是負面的廣告群組準則。
每個子分割至少必須有一個分葉節點在子分割條件的其餘部分進行比對，也就是使用與其同層級單位相同的操作數 (的) ，並設定其 Hotel Attribute Value null 或空白。
如果您要在父系或子系都不存在的多個層級中加入分割區，請使用負 int 值作為參考來識別父系。例如，將父系的 [標識符] 和子系的 [ 父準則標識 符] 字段設定為相同的負值。負數標識碼只在呼叫期間有效。上傳結果檔案中會傳回每個成功新增廣告群組準則的唯一系統標識碼。
只有當 [已排除] 字段為 false 時，才適用 [Bid] 字段，這表示節點是可比對的廣告群組準則。不過，細分分割節點會忽略 Bid。這些元素只與數據分割節點) 單元 (分葉相關。
若要暫停任何旅館清單群組，您必須將廣告群組的 [ 狀態 ] 字段更新為 [暫停]，以暫停整個廣告群組。您可以將 [營銷活動] 的 [ 狀態] 字 段更新為 [暫停]，以暫停整個營銷活動。
針對 [已刪除] 動作，您只需要指定 [標識符 ] 和 [父標識符]。
如果您刪除父旅館清單群組，也會刪除其所有子系和子系。
您不能在分支中指定重複的旅館屬性。

您可以在 DownloadCampaignsByAccountIds 或 DownloadCampaignsByCampaignIds 服務要求中包含 AdGroupHotelListingGroups 的 DownloadEntity 值，以下載帳戶中的所有 Ad Group Hotel Listing Group 記錄。此外，下載要求必須包含 EntityData 範圍。如需大量服務的詳細資訊，包括最佳做法，請參閱大量下載和上傳。

如果提供有效的父標識碼值，下列大量 CSV 範例會新增廣告群組旅館清單群組。

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 廣告 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();

針對 廣告群組旅館清單群組 記錄，大量檔案架構中提供下列屬性欄位。

廣告群組
出價
百分比標價
行銷活動
用戶端識別碼
自定義參數
最終 URL 後綴
Id
已排除
修改時間
父準則標識碼
父項識別碼
旅館屬性
旅館屬性值
狀態
子類型
追蹤範本

廣告群組

包含旅館清單群組的廣告組名。

添加： 唯讀和必要
更新： 唯讀和必要
刪除： 唯讀和必要

注意事項

若要新增、更新和刪除，您必須指定 [父標識符 ] 或 [ 廣告群組] 字段。

出價

要在銀場中進行成交的金額。當營銷活動布建為ManualCpc時，就會使用此功能。

添加： 如果 [排除] 為 false 且 [子類型] 為 [單位]，則為必要專案，否則不允許進行中標。
更新： 選。如果未設定更新的值，則此設定不會變更。
刪除： 唯讀

百分比標價

要在銀場中進行成交的金額。當營銷活動佈署配置為 PercentCpc 或 Pc 時，就會使用此專案。

行銷活動

包含廣告群組和旅館清單群組的活動名稱。

添加： 唯讀
更新： 唯讀
刪除： 唯讀

用戶端識別碼

用來將大量上傳檔案中的記錄與結果檔中的記錄產生關聯。伺服器不會使用或儲存此欄位的值;它只會從上傳的記錄複製到對應的結果記錄。它可以是長度上限為100的任何有效字串。

添加： 選
更新： 選
刪除： 唯讀

自定義參數

用於 URL 追蹤的自訂索引鍵和值參數集合。

在大量檔案中，自定義參數清單的格式如下。

將每個自定義參數位格式化為 Key=Value，例如 {_promoCode}=PROMO1。
Microsoft Advertising 會接受您包含的前 8 個自定義參數索引鍵和值組，如果您包含超過 8 個自定義參數，則會傳回錯誤。
每個索引鍵和值組都會以分號和空格 ( 分隔」;“) ，例如 {_promoCode}=PROMO1;{_season}=summer。
索引鍵不能包含分號。如果 Value 包含分號，則必須以 '\;' 逸出。此外，如果 Value 包含反斜杠，也必須以『\』逸出。
密鑰不能超過 16 UTF-8 位元組，而且值不能超過 250 UTF-8 位元組。索引鍵是必要的，而 Value 是選擇性的。密鑰的大小上限不包含大括弧和底線，也就是 '{'、'_' 和 '}'。

注意事項

使用大量服務時，密鑰必須以括弧和前置底線格式化，例如，如果 Key 為 promoCode，則必須格式化為 {_promoCode}。使用行銷活動管理服務時，您無法指定括弧和底線。

添加： 選
更新： 選。如果未設定更新的值，則此設定不會變更。若要移除所有自定義參數，請將此字段設定 為 delete_value。 delete_value關鍵詞會移除先前的設定。若要移除自定義參數的子集，請指定您想要保留的自定義參數，並省略任何您不想要保留的參數。新的自定義參數集將取代任何先前的自定義參數集。
刪除： 唯讀

最終 URL 後綴

最終的 URL 後綴可以包含將附加至登陸頁面 URL 結尾的追蹤參數。建議您在最後的 URL 後綴中放置登陸頁面所需的追蹤參數，讓您的客戶一律傳送至您的登陸頁面。如需詳細資訊和驗證規則，請參閱技術指南中的最終 URL 後綴。

添加： 選
更新： 選。如果未設定更新的值，則此設定不會變更。如果您將此欄位設定為 delete_value 字串，則會移除先前的設定。
刪除： 唯讀

Id

系統產生的旅館清單群組標識碼。

添加： 唯讀
更新： 唯讀和必要
刪除： 唯讀和必要

已排除

判斷旅館清單群組是否代表可申請或負面準則。

如果設定為 true ，則為負數準則，否則為 false ，則為可比對的準則。

添加： 必填
更新： 唯讀
刪除： 唯讀

修改時間

上次更新實體的日期和時間。值為國際標準時間 (UTC)。

注意事項

日期和時間值會反映伺服器上的日期和時間，而不是用戶端。如需日期和時間格式的相關信息，請參閱基本 XML 數據類型中的 dateTime 專案。

添加： 唯讀
更新： 唯讀
刪除： 唯讀

父準則標識碼

父旅館清單群組的準則標識碼。

這個大量欄位會對應到 ParentNodeId ，而且必須是 Null，才能指向根節點。

注意事項

此欄位不適用於沒有父代的樹狀結構根旅館清單群組節點。

添加： 唯讀和必要
更新： 唯讀
刪除： 唯讀

父項識別碼

系統產生的廣告群組標識符，其中包含旅館清單群組。

此大量欄位會對應至廣告群組記錄的 [標識符] 欄位。

添加： 唯讀和必要。您必須指定現有的廣告群組標識符，或指定等於父代 Ad Group 記錄之 [標識符] 字段的負標識符。如果您要將新的旅館清單群組新增至相同大量檔案中的新廣告群組，建議您這麼做。如需詳細資訊，請參閱大量檔案架構參考密鑰。
更新： 唯讀和必要
刪除： 唯讀和必要

注意事項

若要新增、更新和刪除，您必須指定 [父標識符 ] 或 [ 廣告群組] 字段。

旅館屬性

條件的操作數。操作數隱含包含等號運算符。例如，您可以將 Brand 讀取為 Brand=。

使用 Hotel 屬性做為 Hotel 屬性值的操作數。

您可以為每個行銷活動和廣告群組指定多個旅館屬性。如果旅館的屬性值等於操作數的屬性值，就會符合每個條件。例如，如果操作數設定為 Brand，且屬性設定為 Contoso，則如果旅館目錄的 Brand 屬性值等於 Contoso，就會符合條件。

在您的行銷活動中，您可以在營銷活動和廣告群組層級設定旅館屬性。下表說明 Hotel Attribute (操作數) 和 Hotel Attribute Value (屬性) Ad Group Hotel 清單群組記錄的商務規則。

注意事項

當根節點的 Hotel 值設定為 Null 或空白時，Hotel 屬性必須是 “All”。

Hotel 屬性 (操作數)	Hotel 屬性值 (屬性) 描述	廣告群組旅館清單群組規則
全部	不適用。	針對廣告群組的旅館清單群組，根節點必須將操作數設定為「All」，並將屬性設定為 Null 或空白。
品牌	旅館的製造商、品牌或發行者。最多 200 個字元。	Brand 操作數可用於多個分支，但每個分支只能指定一次。
類別	旅館類別，例如「Inn」、“Motel”、“Resort” 等。最多 200 個字元。	不適用。
城市	旅館所在的城市。	不適用。
國家/地區	旅館所在的國家或地區。	不適用。
CustomLabel0-4 有五個自定義標籤操作數值可供使用，例如 CustomLabel0、CustomLabel1、CustomLabel2、CustomLabel3 和 CustomLabel4。	每個 CustomLabel 操作數都可以在多個分支中使用，但每個分支只能指定一次。例如，一個分支可能包含 CustomLabel0 和 CustomLabel1，但不能包含另一個具有 CustomLabel1 操作數的節點。最多 200 個字元。	不適用。
HotelId	旅館標識碼。最多 1,024 個字元。	Id 操作數可用於多個分支，但每個分支只能指定一次。
StarRating	1 到 5 顆星的旅館評等。	不適用。
狀態	旅館所在的狀態。	不適用。

添加： 必填
更新： 唯讀。您無法更新條件或值欄位。若要更新條件，您必須刪除旅館清單群組，並新增一個新的清單群組。
刪除： 唯讀

旅館屬性值

條件的屬性值。

添加： 必填
更新： 唯讀。您無法更新條件或值欄位。若要更新條件，您必須刪除旅館清單群組，並新增一個新的清單群組。
刪除： 唯讀

狀態

旅館清單群組的狀態。

可能的值為 [作用中 ] 或 [已刪除]。

添加： 選。唯一可能的狀態是 [作用中]。如果您將狀態設定為 [已刪除] ，則會忽略該狀態，且傳回的記錄的狀態會設定為 [作用中]。
更新： 選
刪除： 必填。 [狀態] 必須設定為 [ 已刪除]。

子類型

旅館清單群組的類型。

可能的值為 [細分 ] 和 [ 單位]。

添加： 必填
更新： 唯讀
刪除： 唯讀

追蹤範本

追蹤範本可以與您透過內容 API 提交的旅館供應專案 [連結] 字段中指定的 URL 搭配使用。藉由結合摘要 URL 與追蹤範本，登陸頁面 URL 會組合在按兩下廣告之後引導使用者的位置。當您使用 [追蹤範本] 字 段來更新 URL 參數，而不是在摘要 URL 中更新它們時，摘要 URL 不需要經過編輯檢閱，而且您的廣告會繼續不間斷地提供。例如，如果目錄摘要中的旅館供應專案 URL 是 https://contoso.com/，您可以指定下列追蹤範本： {lpurl}？matchtype={matchtype}&device={device}。

下列驗證規則適用於追蹤範本。如需支援的範本和參數的詳細資訊，請參閱 Microsoft Advertising 說明文章我可以使用哪些追蹤或 URL 參數？

針對較低層級實體定義的追蹤範本，例如廣告會覆寫針對較高層級實體所設定的範本，例如營銷活動。如需詳細資訊，請參閱實體限制。
追蹤範本的長度限製為 2,048 個字元。 HTTP 或 HTTPS 通訊協定字串確實會計入 2,048 個字元的限制。
追蹤範本必須是格式正確的 URL，開頭為下列其中一項： http://、 https://、 {lpurl} 或 {unescapedlpurl}。
Microsoft Advertising 不會驗證自定義參數是否存在。如果您在追蹤範本中使用自定義參數，但它們不存在，則登陸頁面 URL 會包含自定義參數的索引鍵和值佔位元，而不需替代。例如，如果您的追蹤範本是 https://tracker.example.com/?season={_season}&promocode={_promocode}&u={lpurl}，且 { _season} 或 {_promocode} 都未定義於行銷活動、廣告群組、準則、關鍵詞或廣告層級，則登陸頁面 URL 會相同。

共用方式為

廣告群組旅館清單群組記錄 - 大量

廣告群組

出價

百分比標價

行銷活動

用戶端識別碼

自定義參數

最終 URL 後綴

Id

已排除

修改時間

父準則標識碼

父項識別碼

旅館屬性

旅館屬性值

狀態

子類型

追蹤範本

意見反應

其他資源