分享方式：

旅館 API 參考

  • 文章

注意事項

此 Beta 版的旅館價格廣告僅供選取參與者使用。 如需參與 Beta 發行計劃的相關信息，請連絡您的帳戶管理員或 在這裡註冊。

API 和檔可能會變更。

旅館 API 可讓您管理旅館廣告營銷活動和營銷活動。

端點

以下是您用來建構端點的基底 URI。

  • 生產—https://partner.api.bingads.microsoft.com/Travel/v1/

端點必須包含客戶和帳戶資源。

https://partner.api.sandbox.bingads.microsoft.com/Travel/V1/Customers({customerId})/Accounts({accountId})/

將 {customerId} 設定為客戶的 CustomerId，並將 {accountId} 設定為客戶的 CustomerAccountId。

接下來，從下表附加範本，以新增、取得及更新旅館資源。 例如，若要取得或新增旅館群組，請使用下列端點：

https://partner.api.sandbox.bingads.microsoft.com/Travel/V1/Customers({customerId})/Accounts({accountId})/SubAccounts('{subAccountId}')/HotelGroups

注意事項

SubAccounts、HotelGroups、Hotels 和 ReportJobs 的標識符是字串，且必須以單引號括住。 例如，SubAccounts (『12345』) /HotelGroups。 這僅適用於 SubAccounts、HotelGroups、Hotels 和 ReportJobs;請勿針對客戶和帳戶使用單引號。

SubAccounts 範本

動詞 說明
獲取 取得 (先前為指定帳戶定義的旅館活動) 記錄活動清單。

注意：根據預設，清單最多包含1,000個營銷活動。 若要判斷子帳戶中的營銷活動總數，請使用 $count 查詢參數。 若要指定要傳回的活動數目，請使用 $top 查詢參數。 若要逐頁查看子帳戶中的所有活動，請使用$top和 $skip 查詢參數。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 SubAccount 物件的清單。
發佈 將子帳戶新增至指定的帳戶。 您可以將子帳戶視為記錄活動。 使用子帳戶以邏輯方式組織您的旅館廣告活動。 每個帳戶最多可以有50個作用中的記錄活動。

要求本文：包含要新增的 SubAccount 。

回應本文：如果成功，則包含 AddResponse 物件。 欄 value 位包含新增的記錄活動標識碼。

SubAccounts ('{subAccountId}') 範本

動詞 說明
獲取 取得指定的子帳戶。

回應本文：包含 SubAccount 物件。

樣本參數：
  • {subAccountId}—設定為要取得之子帳戶的標識符。
補丁 匯報 子帳戶。

要求本文：包含 SubAccount 物件，只指定要更新的欄位。

回應本文：無。 如果成功，則傳回 HTTP 狀態代碼 204。

樣本參數：
  • {subAccountId}—設定為要更新之子帳戶的標識符。

SubAccounts ('{subAccountId}') /HotelGroups 範本

動詞 說明
獲取 取得指定子帳戶中的旅館群組清單。

注意：根據預設，清單最多包含 1,000 個旅館群組。 若要判斷子帳戶中的群組總數，請使用 $count 查詢參數。 若要指定要傳回的群組數目，請使用 $top 查詢參數。 若要逐頁查看子帳戶中的所有群組，請使用$top和 $skip 查詢參數。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 HotelGroup 物件的清單。

樣本參數：
  • {subAccountId}—設定為包含要取得之旅館群組的子帳戶標識碼。
發佈 將旅館群組新增至指定的子帳戶。 使用旅館群組建立旅館價格廣告的邏輯群組。 每個子帳戶最多可以建立 1,000 個使用中的旅館群組。

要求本文：包含要新增至子帳戶的 HotelGroup 。

回應本文：如果成功，則包含 AddResponse 物件。 欄 value 位包含新增旅館群組的標識碼。

樣本參數：
  • {subAccountId}—設定為子帳戶的標識碼，以將旅館群組新增至其中。

SubAccounts ('{subAccountId}') /HotelGroups ('{hotelGroupId}') 範本

動詞 說明
獲取 取得指定的旅館群組。

回應本文：包含 HotelGroup 物件。

樣本參數：
  • {subAccountId}—設定為包含旅館群組之子帳戶的標識碼。
  • {hotelGroupId}—設定為要取得的旅館群組標識符。
補丁 匯報 旅館群組。

要求本文：包含 HotelGroup 物件，只指定要更新的欄位。

回應本文：無。 如果成功，則傳回 HTTP 狀態代碼 204。

樣本參數：
  • {subAccountId}—設定為包含旅館群組之子帳戶的標識碼。
  • {hotelGroupId}—設定為要更新的旅館群組標識符。
刪除 刪除旅館群組。

要求本文：無。

回應本文：無。 如果成功，則傳回 HTTP 狀態代碼 204。

樣本參數：
  • {subAccountId}—設定為包含旅館群組之子帳戶的標識碼。
  • {hotelGroupId}—設定為要刪除的旅館群組標識符。

SubAccounts ('{subAccountId}') /Hotels 範本

動詞 說明
獲取 取得指定子帳戶中的旅館價格廣告清單。 此清單包含子帳戶中所有旅館群組的所有旅館。

注意：根據預設，清單最多包含 1,000 家旅館。 若要判斷子帳戶中的旅館總數，請使用 $count 查詢參數。 若要指定要傳回的旅館數目，請使用 $top 查詢參數。 若要逐頁查看子帳戶中的所有旅館，請使用$top和 $skip 查詢參數。

注意：使用此呼叫只會在UI體驗中逐頁瀏覽旅館。 請勿使用此呼叫來下載所有旅館。 若要下載所有旅館，請改用 報表 功能。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 Hotel 物件的清單。

樣本參數：
  • {subAccountId}—設定為包含要取得之旅館的子帳戶標識碼。
.

SubAccounts ('{subAccountId}') /HotelGroups ('{hotelGroupId}') /Hotels 模板

動詞 說明
獲取 取得指定旅館群組中的旅館價格廣告清單。

注意：根據預設，清單最多包含 1,000 家旅館。 若要判斷旅館群組中的旅館總數，請使用 $count 查詢參數。 若要指定要傳回的旅館數目，請使用 $top 查詢參數。 若要逐頁查看群組中的所有旅館，請使用$top和 $skip 查詢參數。

注意：使用此呼叫只會在UI體驗中逐頁瀏覽旅館。 請勿使用此呼叫來下載所有旅館。 若要下載所有旅館，請改用 報表 功能。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 Hotel 物件的清單。

樣本參數：
  • {subAccountId}—設定為包含旅館群組之子帳戶的標識碼。
  • {hotelGroupId}—設定為包含要取得之旅館的旅館群組標識符。
.

SubAccounts ('{subAccountId}') /HotelGroups ('{hotelGroupId}') /Hotels ('{hotelId}') 範本

動詞 說明
獲取 取得指定的旅館廣告。

回應本文：包含 Hotel 物件。

樣本參數：
  • {subAccountId}—設定為包含旅館群組之子帳戶的標識碼。
  • {hotelGroupId}—設定為包含要取得之旅館的旅館群組標識符。
  • {hotelId}—設定為要取得的旅館廣告。
補丁 匯報 旅館廣告。

要求本文：包含只指定要更新之字段的 Hotel 物件。

回應本文：無。 如果成功，則傳回 HTTP 狀態代碼 204。

樣本參數：
  • {subAccountId}—設定為包含旅館群組之子帳戶的標識碼。
  • {hotelGroupId}—設定為包含要更新之旅館的旅館群組標識符。
  • {hotelId}—設定為要更新的旅館標識碼。 您可以將此參數設定為 Microsoft 指派給旅館的標識碼，或是廣告商指派給旅館的標識碼。 如果您將它設定為廣告商的標識碼，您必須將查詢參數設定 PartnerHotelId 為 true。
查詢參數：
  • PartnerHotelId—如果{hotelId}資源參數包含廣告商指派給旅館的標識符，請設定為 true。 如果此參數設定為 false 或遺失，則標識碼是 Microsoft 所指派的標識碼。 預設值為 false 。

SubAccounts ('{subAccountId}') /Ungrouped 範本

動詞 說明
獲取 取得未分組旅館群組中的旅館清單。 當您建立子帳戶時，服務會建立未分組的旅館群組。 您旅館摘要中未與其他群組相關聯的所有旅館都會放在此群組中。 若要將此群組中的旅館與不同的旅館群組產生關聯，請參閱 關聯 範本。

注意：根據預設，清單最多包含 1,000 家旅館。 若要判斷未分組旅館群組中的旅館總數，請使用 $count 查詢參數。 若要指定要傳回的旅館數目，請使用 $top 查詢參數。 若要逐頁查看群組中的所有旅館，請使用$top和 $skip 查詢參數。

注意：使用此呼叫只會在UI體驗中逐頁瀏覽旅館。 請勿使用此呼叫來下載所有旅館。 若要下載所有旅館，請改用 報表 功能。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 Hotel 物件的清單。

樣本參數：
  • {subAccountId}—設定為子帳戶的標識碼，其中包含要取得的未分組旅館價格廣告。

SubAccounts ('{subAccountId}') /Associations 範本

動詞 說明
獲取 取得旅館和旅館群組關聯的清單。

注意：根據預設，清單最多包含1,000個關聯。 若要判斷子帳戶中的關聯總數，請使用 $count 查詢參數。 若要指定要傳回的關聯數目，請使用 $top 查詢參數。 若要逐頁查看子帳戶中的所有關聯，請使用$top和 $skip 查詢參數。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 HotelAssociation 物件的清單。

樣本參數：
  • {subAccountId}—設定為包含要取得之關聯的子帳戶標識碼。

SubAccounts ('{subAccountId}') /Associate 範本

動詞 說明
發佈 將旅館和旅館群組關聯的清單新增至子帳戶。

要求本文：包含 AssociationCollection 物件。 欄 HotelAssociation 位包含最多 500 個 HotelAssociation 物件的清單。 每個物件都會將旅館與旅館群組產生關聯。

您只能將旅館與一個旅館群組產生關聯。 根據預設，旅館會與 未分組的 旅館群組相關聯。 若要將旅館與新的旅館群組建立關聯，請使用此範本。 當您將旅館與新的旅館群組建立關聯時，服務會移除先前的關聯。

回應本文：包含 CollectionResponse 物件。 欄 value 位包含 HotelAssociation 物件的清單。 此清單只包含驗證失敗的關聯。 如果沒有錯誤，清單會是空的。 關聯的 Errors 欄位包含關聯失敗的原因清單。

樣本參數：
  • {subAccountId}—設定為要加入關聯之子帳戶的標識符。

ReportJobs 範本

動詞 說明
發佈 將報表要求加入至報表佇列。

要求本文：包含 ReportJob 物件，可定義您要新增至佇列的報表要求。

回應本文：如果報表要求成功新增至佇列，則本文是包含報表作業標識碼的 AddResponse 物件。 在後續的 GET 要求中使用標識符來取得報表作業的狀態 (請參閱 ReportJobs ('{jobId}') 範本) 。

ReportJobs ('{jobId}')

動詞 說明
獲取 取得指定報表作業的狀態。

回應本文：包含 ReportJob 物件。 使用欄 Status 位來判斷作業何時完成。 當作業完成時，請使用 欄位中的 Url URL 來下載報表。

樣本參數：
  • {jobId}—要取得其狀態之報表作業的標識符。 將 設定為POST要求傳回之報表作業的標識碼。

$batch範本

動詞 說明
發佈 傳送最多可包含500個要求的批次要求。 深入瞭解

要求本文：包含個別要求的字串。

回應本文：包含對應回應的字串。

查詢參數

以下是要求可能指定的查詢參數。

參數 說明
$count 判斷回應是否包含 @odata.count 欄位的 OData 參數。 一般而言，當您要求實體清單，例如旅館群組清單時，會包含此參數。 欄 @odata.count 位包含可用的資源實體總數，而不是要求中傳回的資源實體總數。 例如，如果您將 $top 設為 40，但存在 1,000 個實體， @odata.count 則會設定為 1,000，而不是 40。 若要包含計數，請將 $count設為 true。
$filter OData 參數，指定用來篩選數據的表達式清單。

注意： 您只能搭配 / Associations 資源使用 $filter 參數。 如需詳細資訊，請 參閱篩選旅館關聯。
$select OData 參數，指定要包含在回應中的欄位逗號分隔清單。 功能變數名稱區分大小寫。 例如，若要在回應中包含旅館的名稱、合作夥伴識別碼和報價欄位，請指定下列參數：

$select=Name,PartnerHotelId,Bid
$skip OData 參數，指定傳回實體之前要略過的資源實體數目。 $skip值必須是 $top的倍數。 如果您指定超出範圍的值，回應會包含空集合。 使用$top和$skip來逐頁瀏覽資源實體清單。
$top OData 參數，指定要傳回的資源實體數目。 默認值為 1,000，而您可以指定的最大值為 5,000。 使用$top和$skip來逐頁瀏覽資源實體清單。

標頭

以下是要求和響應標頭。

頁首 說明
授權 要求標頭。

將此標頭設定為持有人 OAuth 存取令牌。 例如，「授權：持有人 QTkxRUFBRjEzOTUyNEIx...」。 如需取得令牌的相關信息，請參閱 使用者入門。
Content-Type 要求和回應標頭。

要求或響應主體中的內容類型。 若為 POST 和 PATCH，請將此標頭設定為 application/json。
X-MS-RequestId 回應標頭。

包含要求詳細數據的記錄項目標識碼。 如果發生錯誤，您應該一律擷取此標識碼。 如果您無法判斷並解決問題，請包含此標識碼以及您提供支援小組的其他資訊。

注意事項

此 API 僅支援使用 OAuth 存取令牌進行驗證 (請參閱授權標頭) 。 您不能使用 UserName 和 Password 標頭來指定舊版認證。

此 API 不需要開發人員令牌。 如果您包含 DeveloperToken 標頭，API 會忽略它。

資源物件

以下是 API 所使用的資源物件。

物件 描述
AddResponse 定義新增資源之要求的回應物件。
AdsApiError 定義發生的錯誤。
AdvanceBookingWindowMultiplier 定義當使用者事先預訂指定天數時，要調整基本報價的數量。
AssociationCollection 定義旅館關聯的集合。
預算 定義子帳戶中旅館價格廣告的每日預算。
CollectionResponse 為取得資源清單的要求定義回應物件。
CheckinDayOfWeekMultiplier 定義當使用者簽入其中一個指定的工作日時，要調整基本報價的數量。
DateTypeMultiplier 定義使用者使用特定日期搜尋旅館時，調整基本報價的數量。
DeviceMultiplier 如果使用者使用其中一個指定的裝置來搜尋旅館，則定義調整基本報價的數量。
FixedBid 定義固定的約定金額。
旅館 定義旅館廣告。
HotelAssociation 定義旅館與旅館群組之間的關聯。
HotelGroup 定義旅館價格廣告的邏輯群組。
LengthOfStayMultiplier 定義如果使用者維持指定的夜間數目或更長的時間，要調整基本報價的數量。
PercentageBid 根據夜間總房間費率的百分比來定義申請。
ReportJob 定義報表作業。
SiteMultiplier 定義當使用者在其中一個指定的 Bing 網站上搜尋旅館時，要調整基本報價的數量。
SubAccount 定義最上層旅館價格廣告群組。 您可以在邏輯上將此視為記錄活動。
UserCountryMultiplier 定義當使用者存取其中一個 Bing 網域時，要調整基本報價的數量。

注意事項

回應物件包含內容欄位。 因為未來可能會隱藏此欄位，或模型可能會變更，所以您不應該對它採取相依性。 相依於此欄位可能會在未來中斷您的程式代碼。

AddResponse

定義新增資源之要求的回應物件。

名稱 值 類型
數值 您新增之資源的識別碼。 物件

AdsApiError

定義發生的錯誤。

名稱 值 類型
代碼 識別錯誤的符號代碼。 如需程式代碼清單，請參閱 錯誤碼。 String
郵件 錯誤的描述。 String
參數 造成錯誤的物件、欄位或參數名稱。 String

AdvanceBookingWindowMultiplier

定義當使用者事先預訂指定天數時，要調整基本報價的數量。

名稱 值 類型 新增 更新
因素 調整基底報價依據的百分比金額。 有效範圍為 0.00 到 11.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
MinimumNumberOfDays 預約前的最小天數。 如果預約是以指定的天數或更長的時間事先進行，請套用乘數。 整數 必要 選用
@odata.type 物件的型別。 此欄位設定為 「#Model.AdvanceBookingWindowMultiplier」。。 String 必要 必要

AssociationCollection

定義旅館關聯的集合。

名稱 值 類型 新增 更新
HotelAssociations 旅館和旅館群組關聯的清單。 清單最多可包含 500 個關聯。 HotelAssociation[] 必要項目 不適用

出價

定義中標的基類。

請勿指定這個類別，而是指定 FixedBid 或 PercentageBid 類別。

名稱 值 類型 新增 更新
金額 美元報價金額。 如需您市場有效報價範圍的詳細資訊，請參閱 貨幣 主題中的貨幣值數據表。 客戶的帳戶會指定使用的貨幣。 雙精度浮點數 必要 選用

Budget

定義子帳戶中旅館價格廣告的每日預算。

名稱 值 類型 新增 更新
金額 每日預算金額。 如需市場有效預算的詳細資訊，請參閱 貨幣 主題中的貨幣值數據表。 客戶的帳戶會指定用於預算的貨幣。 雙精度浮點數 必要 選用

CheckinDayOfWeekMultiplier

定義當使用者簽入其中一個指定的工作日時，要調整基本報價的數量。

名稱 值 類型 新增 更新
DaysOfWeek 工作日清單。 如果使用者正在檢查其中一個指定的天數，請套用乘數。 以下是可能區分大小寫的值。

  • 星期一
  • 星期二
  • 星期三
  • 星期四
  • 星期五
  • 星期六
  • 星期天
 String[] 必要 選用
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
@odata.type 物件的型別。 此欄位設定為 「#Model.CheckinDayOfWeekMultiplier」。 String 必要 必要

CollectionResponse

為取得資源清單的要求定義回應物件。

名稱 值 類型
數值 要求的資源清單。 根據要求，清單包含下列其中一種類型的物件：例如，如果您要求旅館群組清單，則 value 會包含物件清單 HotelGroup 。 object[]
@odata.count 可用的資源實體總數，而不是 中的 Value實體數目。 只有當您在要求中包含$count查詢參數時，回應才會包含此字段。

DateTypeMultiplier

定義使用者使用特定日期搜尋旅館時，調整基本報價的數量。

名稱 值 類型 新增 更新
DateType 搜尋中使用的日期類型。 以下是可能區分大小寫的值。

  • 預設值— 使用者未使用特定日期搜尋旅館
  • 已選取 — 使用者使用特定日期搜尋旅館。
 String[] 必要 選用
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
@odata.type 物件的型別。 此字段設定為 「#Model.DateTypeMultiplier」。。 String 必要 必要

DeviceMultiplier

如果使用者使用其中一個指定的裝置來搜尋旅館，則定義調整基本報價的數量。

名稱 值 類型 新增 更新
DeviceTypes 裝置類型的清單。 如果使用者使用裝置類型來搜尋旅館，請套用乘數。 以下是可能區分大小寫的值。

  • 電腦
  • 行動裝置
  • 片
 String[] 必要 選用
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
@odata.type 物件的型別。 此欄位設定為 「#Model.DeviceMultiplier」。。 String 必要 必要

FixedBid

定義固定的約定金額。

名稱 值 類型 新增 更新
金額 固定的美元報價金額。 如需您市場有效報價範圍的詳細資訊，請參閱 貨幣 主題中的貨幣值數據表。 客戶的帳戶會指定使用的貨幣。

比對金額是每晚的報價。 例如，如果標價為 $3.50，而路線是 3 晚停留，則最終的報價為 $10.50。		 雙精度浮點數 必要 選用
@odata.type 物件的型別。 此欄位設定為 「#Model.FixedBid」。 String 必要 必要

旅館

定義旅館廣告。

名稱 值 類型 新增 更新
出價 基本的報價。 除非您指定一或多個乘數， (查看 BidMultipliers) ，否則 Microsoft 會在銀場中使用此報價。 如果您未指定申請，則旅館會依該順序繼承旅館群組或子帳戶的報價。 取得旅館時，如果旅館未指定報價，則此字段會包含繼承的報價。

以下是您可以指定的報價類型。若要暫停旅館，請指定百分比的約定，並將其 (0) 的報價金額設定為零。

若要移除旅館的報價，請將 設定為 Bid null。		 物件 不適用 選用
BidMultipliers 要套用至基本報價的乘數清單。 Microsoft 會將乘數套用至基本的報價，並使用調整后的報價。 如果旅館未指定報價，乘數會調整繼承的報價。

如果您未指定乘數，則旅館會依該順序從旅館群組或子帳戶繼承它們。 取得旅館時，如果旅館未指定乘數，此字段會包含繼承的乘數。

如果旅館指定乘數，而您想要移除它們，請將 設定為 BidMultipliers 空陣列。

以下是您可以指定的乘數類型。		 object[] 不適用 選用
BidMultiplierSource 中標乘數的來源。 以下是可能的值。
  • SubAccount
  • HotelGroup
  • 旅館
例如，如果旅館和旅館群組未指定乘數，則旅館會從子帳戶繼承乘數。 在此情況下，此欄位會設定為 SubAccount。		 String 不適用 唯讀
BidSource 中標的來源。 以下是可能的值。
  • SubAccount
  • HotelGroup
  • 旅館
例如，如果旅館指定了報價，則此字段會設定為 Hotel。		 String 不適用 唯讀
CountryCode 旅館所在國家/地區的兩個字母 ISO 3116 郡代碼。 國家/地區與您在旅館摘要檔案中為旅館指定的國家/地區相同。 String 唯讀 唯讀
識別碼 系統產生的標識碼，可唯一識別旅館。 String 不適用 必要項目
名稱 旅館的名稱。 此名稱與您在旅館摘要檔案中指定的名稱相同。 String 不適用 唯讀
PartnerHotelId 您用來在旅館摘要檔案中識別旅館的標識碼。 String 不適用 唯讀
狀態 旅館實體的狀態。 以下是可能的值。
  • 作用中— 旅館不會刪除，而且可能會更新。
  • 已刪除— 使用者已刪除旅館。 使用者只能使用UI刪除旅館。
 String 不適用 唯讀

HotelAssociation

定義旅館與旅館群組之間的關聯。

Update 資料行包含 N/A 值，因為沒有 HTTP 更新作業。 若要更新旅館的關聯，請使用新增 (POST) 作業。 請參閱 關聯 範本。

名稱 值 類型 新增 更新
錯誤 關聯驗證失敗的原因清單。

只有在您嘗試新增關聯時驗證失敗時，回應才會包含此欄位。		 AdsApiError 唯讀 不適用
HotelGroupId 要與旅館建立關聯之旅館群組的標識符。 String 必要項目 不適用
HotelGroupName 旅館群組的名稱。 String 唯讀 不適用
HotelId 要與指定旅館群組相關聯的旅館標識碼 (請參閱 HotelGroupId) 。 您只能將旅館與一個旅館群組建立關聯。

根據預設，所有旅館都會與旅館群組相關聯，不論是使用者定義的群組或預設 的未分組 旅館群組。 若要將旅館從一個群組移至另一個群組，請張貼指定旅館標識元和新旅館群組標識元的新關聯;服務會移除先前的關聯。		 String 必要項目 不適用
HotelName 旅館的名稱。 String 唯讀 不適用
PartnerHotelId 您用來在旅館摘要檔案中指定旅館的標識碼。 String 唯讀 不適用

HotelGroup

定義旅館的邏輯群組。

名稱 值 類型 新增 更新
出價 如果群組中的旅館未指定報價，則會繼承其基本的報價。 如需使用方式，請參閱 BidHotel 物件中的 。

如果您未指定中標，群組會從子帳戶繼承該標示。 取得旅館群組時，如果群組未指定報價，此字段會包含繼承的報價。

以下是您可以指定的報價類型。若要暫停群組中的所有旅館，請指定百分比的報價，並將其 (0) 的報價金額設定為零。

若要移除群組的報價，請將 設定為 Bid null。		 物件 選用 選用
BidMultipliers 群組中旅館未指定乘數時繼承的乘數清單。 如需使用方式，請參閱 BidMultipliersHotel 物件中的 。

如果您未指定乘數，群組會從子帳戶繼承它們。

如果旅館群組指定乘數，而您想要移除它們，請將 設定為 BidMultipliers 空陣列。

以下是您可以指定的乘數類型。		 object[] 選用 選用
BidMultiplierSource 中標乘數的來源。 以下是可能的值。
  • SubAccount
  • HotelGroup
例如，如果旅館群組未指定乘數，則旅館群組會從子帳戶繼承乘數。 在此情況下，此欄位會設定為 SubAccount。		 String 唯讀 唯讀
BidSource 中標的來源。 以下是可能的值。
  • SubAccount
  • HotelGroup
例如，如果旅館群組指定乘數，則此字段會設定為 HotelGroup。		 String 唯讀 唯讀
HotelAssociationCount 與旅館群組相關聯的旅館數目。 Unsigned Integer 唯讀 唯讀
識別碼 系統產生的標識碼，可唯一識別群組。 String 唯讀 必要項目
名稱 群組的名稱。 名稱最多可包含 256 個字元。 String 必要項目 唯讀
狀態 旅館群組實體的狀態。 以下是可能的值。
  • 作用中— 旅館群組不會刪除，而且可能會更新。
  • 已刪除— 使用者已刪除旅館群組。 使用者只能使用UI刪除旅館群組。
 String 唯讀 唯讀

LengthOfStayMultiplier

定義如果使用者維持指定的夜間數目或更長的時間，要調整基本報價的數量。

名稱 值 類型 新增 更新
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
MinimumNumberOfNights 套用乘數所需的最小夜間數目。 如果使用者保持指定的夜間數目或更長，請套用乘數。 有效值為 1 到 14。 整數 必要 選用
@odata.type 物件的型別。 此字段設定為 「#Model.LengthOfStayMultiplier」。。 String 必要 必要

乘數

定義乘數的基類。

請勿指定這個類別，而是指定其中一個乘數類別，例如 UserCountryMultiplier。

名稱 值 類型 新增 更新
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用

PercentageBid

根據夜間總房間費率的百分比來定義申請，包括稅金和其他費用。

名稱 值 類型 新增 更新
金額 百分比的約定金額。 有效範圍為 0 到 1,000。 例如，若要申請房間總費率的 5%，請將 設定為 Amount 5.0。

比對金額是每晚的報價。 例如，如果約定為 3%，總房間費率為 $99，而路線是 3 晚停留，則最終的報價為 $8.91。		 雙精度浮點數 必要 選用
@odata.type 物件的型別。 此欄位設定為 「#Model.PercentageBid」。 String 必要 必要

ReportJob

定義報表作業。

名稱 值 類型 新增
Columns 要包含在報表中的數據行清單。 報表所包含的順序不具決定性。 報表服務也可以交錯其他未明確要求的相關數據行。 數據行名稱會區分大小寫。 如需數據行名稱的清單，請參閱您要求 (報表類型的報表數據行，例如，針對 PerformanceReport，請參閱效能 報 表數據行) 。 數據行必須在租用時包含一個維度類型數據行和一個計量類型數據行。 String[] 必要項目
壓縮 要套用至報表的壓縮類型。 以下是可能不區分大小寫的值。
  • Zip
預設值為無壓縮。		 String 選用
EndDate 報表的 UTC 結束日期，格式為 YYYY-MM-dd。 月份和日期必須包含兩位數。 例如，使用 2018-01-04 而不是 2018-01-04。

報表包含包含在開始和結束日期內的數據。 結束日期必須晚於或晚於開始日期。

注意： 輪詢以取得作業狀態時，服務會傳回YYYY-MM-ddTHH：mm：ssZ (格式的日期，例如2017-10-30T00：00：00Z) 。		 String 必要項目
篩選器 要套用的 OData 篩選字串。 篩選字串的最大長度為 1,000 個字元。 如需使用篩選的相關信息，請參閱 篩選報表數據。

注意： 您指定的報表資料列名稱和列舉值會區分大小寫。 例如，您必須指定 DeviceType 而非 devicetype，而非 Desktop。		 String 選用
格式 報表中內容的格式。 以下是可能不區分大小寫的值。
  • CSV
預設值為 CSV。		 String 選用
HotelGroupId 要限制報表的旅館標識碼。 若要設定此欄位，您必須設定 SubaccountId。 String 選用
識別碼 可唯一識別報表作業的標識碼。 String 唯讀
IncludeNonPerformingHotels 布爾值，判斷報表是否包含在報告期間未收到曝光的旅館。 若要包含不執行的旅館，請將此字段設定為 true;否則為 false。 預設值為 false 。

如需您在要求非執行中旅館時可能指定之數據行的限制，請參閱 在報表中包含非執行中的旅館。		 布林值 選用
ReportType 要下載的實體或報表類型。 以下是可能區分大小寫的值。 String 必要項目
StartDate 報表的 UTC 開始日期，格式為 YYYY-MM-dd。 月份和日期必須包含兩位數。 例如，2018-1-4 必須是 2018-01-04。 您可以指定的最早日期是從今天起的三年。

注意： 輪詢以取得作業狀態時，服務會傳回YYYY-MM-ddTHH：mm：ssZ (格式的日期，例如2017-10-30T00：00：00Z) 。		 String 必要項目
狀態 報表作業的狀態。 以下是可能的值。
  • 已完成— 報表作業已順利完成。 使用欄位中的 Url URL 下載報表。
  • 失敗— 作業因為某些原因而失敗。 如果錯誤是暫時性錯誤，您可以重新提交作業。 如果作業再次失敗，請在 X-MS-RequestId 標頭中擷取要求標識符，並連絡支持人員。
  • InProgress— 服務正在建置報表。
  • PendingExecution— 報表要求已排入佇列
 String 唯讀
SubaccountId 要限制報表的子帳戶標識碼。 String 選用
Url 要下載之報表的 URL。 當 已完成時 Status ，服務會提供URL。 URL 的有效時間為 5 (5) 分鐘，從您取得設定為 [已完成] 的報表作業 Status 起算。 如果 URL 過期，請傳送 GET 要求以再次取得作業的狀態和新的 URL。

SiteMultiplier

定義當使用者在其中一個指定的 Bing 網站上搜尋旅館時，要調整基本報價的數量。

名稱 值 類型 新增 更新
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
網站 網站清單。 如果使用者使用指定的網站來搜尋旅館，請套用乘數。 以下是可能區分大小寫的值。
  • LocalUniversal— 使用者正在搜尋 Bing.com 上的旅館。
  • MapResults— 使用者正在搜尋 Bing.com/maps 上的旅館。
  • PropertyPromotionAd— 地圖搜尋中顯示的第一個結果頁面。
 String[] 必要 選用
@odata.type 物件的型別。 此欄位設定為 「#Model.SiteMultiplier」。 String 必要 必要

SubAccount

定義最上層旅館價格廣告群組。 您可以在邏輯上將此視為記錄活動。

名稱 值 類型 新增 更新
出價 如果旅館或其所屬的群組未指定報價，則其繼承的基底報價。 如需使用方式，請參閱 BidHotel 物件中的 。

以下是您可以指定的報價類型。若要暫停子帳戶中的所有旅館，請指定百分比的申請，並將其 (0) 的報價金額設定為零。		 物件 必要 選用
BidMultipliers 如果旅館或其所屬群組未指定乘數，則為旅館繼承的乘數清單。 預設值為 0。 如需使用方式，請參閱 BidMultipliersHotel 物件中的 。

如果子帳戶指定乘數，而您想要移除它們，請將 設定為 BidMultipliers 空陣列。

以下是您可以指定的乘數類型。		 object[] 選用 選用
DailyBudget 要分散到一天的每日預算。

將預算設定為 0 可防止子帳戶中的旅館提供服務。		 預算 必要 選用
HotelAssociationCount 子帳戶中與旅館群組相關聯的旅館數目。 Unsigned Integer 唯讀 唯讀
識別碼 系統產生的標識碼，可唯一識別子帳戶。 String 唯讀 必要項目
MaximumBid 不可超過的報價金額。 FixedBid 選用 選用
名稱 子帳戶的名稱。 名稱最多可包含 128 個字元。 String 必要項目 唯讀
狀態 子帳戶實體的狀態。 以下是可能的值。
  • 作用中— 子帳戶不會刪除，而且可能會更新。
  • 已刪除— 使用者已刪除子帳戶。 使用者只能使用 UI 刪除子帳戶。
 String 唯讀 唯讀

UserCountryMultiplier

定義當使用者存取其中一個 Bing 網域時，要調整基本報價的數量。

名稱 值 類型 新增 更新
Countries 兩個字母 ISO 3116 國家/地區代碼的清單。 如需可能的國家/地區代碼清單，請參閱 允許的國家/地區代碼。

如果使用者使用指定的國家/地區代碼存取 Bing 網域，請套用乘數。 例如，如果清單包含US和DE，則如果使用者使用 Bing.com 與 us 或 de country code (例如，bing.com？cc=de) ，則 Microsoft 會使用乘數。		 String[] 必要 選用
因素 調整基底報價依據的百分比金額。 有效範圍是 0.00 到 10.00。 例如，如果固定的約定為 $5，而乘數為 5，則最終的報價為 $25。 使用相同的乘數，如果百分比的報價為 5%，而總房間費率為 $100，則最終的報價為 $25。 雙精度浮點數 必要 選用
@odata.type 物件的型別。 此字段設定為 「#Model.UserCountryMultiplier」。。 String 必要 必要

HTTP 狀態碼

要求可能會傳回下列 HTTP 狀態代碼。

狀態碼 描述
200 已成功擷取資源。
201 已成功新增資源。
204 已成功更新或刪除資源。
400 不正確的要求。 查詢參數值無效或要求本文中的內容無效。
401 未經授權。 用戶的認證無效。
403 禁止。 報表的下載 URL 已過期。 從取得 URL 開始，您有七天的時間可以下載報表。 如果 URL 過期，您必須提交新的作業要求。
404 找不到。
429 太多要求。 API 會限制您每分鐘可能會提出的要求數目。 此限制不會記載，而且可能會變更。 如果您超過限制，API 會傳回此狀態代碼。 收到此錯誤之後，您必須等候 60，才能重新傳送要求。
500 伺服器錯誤。

錯誤碼

報告錯誤碼

錯誤碼 描述
CompressionTypeNotSupported 欄 Compression 位設定為不支援的值。 如需支援的壓縮演算法清單，請參閱 壓縮。
DuplicateValues [ 資料行] 欄位多次包含相同的數據行名稱。
FilterTooLong 您設定為 Filter 的 OData 篩選字串太長。 如需允許的最大長度，請參閱 篩選。
FormatVersionNotSupported 欄 Format 位設定為不支援的值。 如需支援的格式清單，請參閱 格式。
InvalidDateRange 您指定的報告期間無效。 如需指定有效日期範圍的資訊，請參閱 StarteDate 和 EndDate 字 段。
InvalidReportName 欄 ReportType 位設定為無效的報表名稱。 如需有效報表名稱的清單，請參閱 ReportType。
InvalidSelect 您指定的一或多個資料行無效。 比較您用來針對所要求報表所記錄的數據行名稱。 請記住，名稱會區分大小寫。

國家或地區代碼

您可以使用下列國家/地區代碼來設定 CountriesUserCountryMultiplier 的欄位。

國家/地區名稱 國家/地區代碼
阿富汗 Af
阿爾巴尼亞 鋁
阿爾及利亞 Dz
安道爾 廣告
安哥拉 坳
安奎拉 艾
南極洲 Aq
安地卡及巴布達 銀
荷蘭 () AN
美屬薩摩亞 AS
阿根廷 Ar
亞美尼亞 是
荷屬阿魯巴 AW
澳洲 金
奧地利 AT
亞塞拜然 Az
巴哈馬 Bs
巴林 Bh
孟加拉 屋宇 署
巴貝多 Bb
白俄羅斯 BY
比利時 BE
貝里斯 Bz
百慕達 Bm
貝南 北京
不丹 Bt
玻利維亞 博
波士尼亞與赫塞哥維納 八
波札那 Bw
巴西 Br
汶萊 億
保加利亞 BG
布吉納法索 高爐
蒲隆地 BI
Cabo Verde CV
柬埔寨 Kh
喀麥隆 釐米
加拿大 CA
開曼群島 肯塔基州
中非共和國 Cf
查德 Td
智利 Cl
中國 快遞 之 家
聖誕島 殘雪
Cocos Islands 副本
哥倫比亞 CO
葛摩 公里
剛果 Cg
作為) (共和國的共和國 Cd
庫克群島 Ck
哥斯大黎加 鉻
科特迪瓦 (象牙海岸) 詞
克羅埃西亞 人力資源
賽普勒斯 CY
捷克共和國 Cz
丹麥 DK
吉布地 Dj
多米尼克 Dm
多明尼加 DO
厄瓜多 電子商務
埃及 EG
薩爾瓦多 SV
赤道幾內亞 Gq
厄利垂亞 ER
愛沙尼亞 Ee
Eswatini 深圳
衣索比亞 Et
福克蘭群島 Fk
法羅群島 佛
斐濟 福建
芬蘭 FI
法國 FR
法屬圭亞那 女朋友
法屬玻里尼西亞 PF
加彭 Ga
甘比亞 通用汽車
喬治亞 通用電氣
德國 DE
迦納 Gh
直布羅陀 Gi
希臘 GR
格陵蘭 Gl
格瑞那達 Gd
瓜地洛普 Gp
關島 古
瓜地馬拉 燃氣輪機
幾內亞 Gn
幾內亞比索 Gw
蓋亞那 Gy
海地 HT
聖地參閱 Va
宏都拉斯 Hn
香港特別行政區 香港
匈牙利 胡
冰島 是
印度 IN
印尼 識別碼
伊拉克 智商
愛爾蘭 IE
以色列 I l
義大利 IT
牙買加 Jm
日本 Jp
約旦 喬
哈薩克 KZ
肯亞 科
吉里巴斯 K i
韓國 KR
科威特 千瓦
吉爾吉斯 公斤
嫫國 人員 共和國 洛杉磯
拉脫維亞 低壓
黎巴嫩 磅
賴索托 LS
賴比瑞亞 Lr
利比亞 LY
列支敦斯登 李
立陶宛 LT
盧森堡 路
澳門特別行政區 莫
馬達加斯加 鎂
馬拉威 M w
馬來西亞 我
馬爾地夫 Mv
馬利 毫升
馬爾他 MT
馬紹爾群島 MH
馬丁尼克 Mq
茅利塔尼亞 先生
模里西斯 木
馬約特島 劉日東
墨西哥 MX
密克羅尼西亞 調頻
摩爾多瓦 Md
摩納哥 Mc
蒙古 錳
蒙特內哥羅 我
蒙哲臘 女士
摩洛哥 馬
莫三比克 Mz
緬甸 毫米
納米比亞 NA
諾魯 星期日
尼泊爾 Np
荷蘭 NL
新喀里多尼亞 數控
紐西蘭 紐西蘭
尼加拉瓜 鎳
尼日 NE
奈及利亞 議員
紐埃島 女
諾福克島 Nf
挪威 否
北馬其頓 Mk
北馬利安納群島 Mp
阿曼 Om
巴基斯坦 Pk
帛琉 PW
巴勒斯坦民族權力機構 Ps
巴拿馬 Pa
巴布亞紐幾內亞 Pg
巴拉圭 PY
秘魯 體育
菲律賓 PH
皮特康 Pn
波蘭 PL
葡萄牙 鉑
波多黎各 公關
卡達 Qa
留尼旺 RE
羅馬尼亞 Ro
俄羅斯聯邦 如
盧安達 烏爾曼
聖赫勒拿、阿希sion 和 Tristan da Cunha Sh
聖克里斯多福及尼維斯 KN
聖露西亞 立法會
聖皮埃與密克隆群島 下午
聖文森及格瑞那丁 Vc
聖馬利諾 Sm
São Tomé 和 Príncipe 聖
沙烏地阿拉伯 Sa
塞內加爾 錫
塞爾維亞 Rs
塞席爾 Sc
獅子山 SL
新加坡 S g
斯洛伐克 Sk
斯洛維尼亞 四
西班牙 ES
索羅門群島 某人
薩摩亞 Ws
索馬利亞 所以
南非 咱
斯里蘭卡 路
蘇利南 鍶
瑞典 SE
瑞士 CH
台灣 TW
塔吉克 Tj
坦尚尼亞 TZ
泰國 TH
東帝汶 Tl
多哥 Tg
托克勞群島 TK
東加 TO
千里達及托巴哥 TT
突尼西亞 Tn
Türkiye Tr
土庫曼 Tm
土克斯及開科斯群島 Tc
吐瓦魯 電視
烏干達 Ug
烏克蘭 Ua
阿拉伯聯合大公國 Ae
英國 G b
美國 美國
烏拉圭 UY
烏茲別克 UZ
萬那杜 Vu
委內瑞拉 VE
越南 VN
維京群島 (英) Vg
維京群島 (美 ) 六
瓦利斯群島和富圖那群島 WF
葉門 你們
尚比亞 Zm
辛巴威 ZW