本節提供以 Google XML 為基礎的提示要求訊息、提示回應訊息和查詢訊息的參考資料。
<Hint>
(提示回應訊息)
Hint 回應訊息的根元素。提示回應訊息:指定哪些飯店/行程組合應重新定價。對方是您對 Google 的 Hint 要求訊息的回應。
提示回應訊息只能指定自 Google 上次收到伺服器成功的 Hint 回應後,價格有所變動的飯店。
提示回應訊息會使用下列其中一種方法,指定 Google 應重新訂價的飯店和行程:
確切行程:入住日期與入住時間長度的組合。
入住日期範圍:指定入住日期範圍,從第一次入住日期開始,並結束於上次入住日期。
範圍式住宿 (或特定期間的行程)
每個方法都需要不同的 Hint 回應訊息語法。
詳情請參閱 Hint 回應訊息。
語法
<Hint>
元素會根據 Hint 回應訊息的類型,使用不同的語法:
確切行程
以下是提示回應訊息中確切行程的語法:
<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<Property>hotel_ID</Property>
...
<Stay>
<CheckInDate>checkin_date</CheckInDate>
<LengthOfStay>number_of_nights</LengthOfStay>
</Stay>
</Item>
...
</Hint>
入住範圍
以下是提示回應訊息中的簽到範圍語法:
<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<!-- At least one is required -->
<!-- Can be > 1 if MultipleItineraries is "checkin_range" in your
QueryControl message -->
<Property>hotel_ID</Property>
[...]
<!-- Required -->
<FirstDate>first_checkin_date</FirstDate>
<!-- Required -->
<LastDate>last_checkin_date</LastDate>
</Item>
...
</Hint>
範圍住宿
以下顯示在提示回應訊息中的範圍保留語法:
<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<!-- At least one is required -->
<!-- Can be > 1 if MultipleItineraries is "affected_dates" in your
QueryControl message -->
<Property>hotel_ID</Property>
[...]
<StaysIncludingRange>
<!-- Required -->
<FirstDate>first_date</FirstDate>
<!-- Optional -->
<LastDate>last_date</LastDate>
</StaysIncludingRange>
</Item>
...
</Hint>
屬性
<Hint>
元素包含選用屬性:id
。如有提供,系統會根據此 <Hint>
傳送的 <Query>
訊息,納入 hintId
屬性。
子元素
<Hint>
元素包含下列子元素:
子元素 | 必填與否 | 類型 | 提示回覆類型 | 說明 |
---|---|---|---|---|
<CheckInDate> | Required | Date | 確切行程 | 行程的入住日期。 |
<FirstDate> | Required | Date | 入住範圍和範圍行程 | 入住日期範圍或指定日期範圍的開始日期, 保持提示回應訊息。日期含括在內。 |
<Item> | Required | Object | 全部 | 要更新的飯店/行程的容器。 |
<LastDate> | Required* | Date | 入住範圍和範圍行程 | 入住日期範圍或指定日期範圍內的 提示回覆訊息結束日期。日期含括在內。 * 如果是範圍住宿,此元素為選用。 |
<LengthOfStay> | Required | integer | 確切行程 | 行程的夜數,以正整數表示。 |
<Property> | Required | string | 全部 | 飯店的 ID,請使用與飯店清單相同的 ID。您可以在單一
|
<Stay> | Required | Object | 確切行程 | 確切行程提示回應訊息中的 <CheckinDate> 和 <LengthOfStay> 元素的容器。每個 <Item> 只能包含一個 <Stay> 。 |
<StaysIncludingRange> | Required | Object | 特定範圍行程 | <FirstDate> 和 <LastDate> 元素的容器,位於範圍保留的 Hint 回應訊息中。 |
範例
確切行程
以下範例為單一屬性的 Hint 回應訊息定義多個行程:
<!-- Exact Itinerary Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<Property>12345</Property>
<Stay>
<CheckInDate>2018-07-03</CheckInDate>
<LengthOfStay>3</LengthOfStay>
</Stay>
</Item>
<Item>
<Property>12345</Property>
<Stay>
<CheckInDate>2018-07-03</CheckInDate>
<LengthOfStay>4</LengthOfStay>
</Stay>
</Item>
</Hint>
入住範圍
以下範例指定兩間飯店的價格已變更,且應重新擷取。Google 會在 7 月 3 日至 7 月 6 日間,取得資源 12345 和 67890 的所有行程:
<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<Item>
<Property>12345</Property>
<Property>67890</Property>
<FirstDate>2018-07-03</FirstDate>
<LastDate>2018-07-06</LastDate>
</Item>
</Hint>
請注意,如要讓檢查範圍訊息可在單一 <Item>
中指定多個屬性,您必須將 <QueryControl>
中的 <MultipleItineraries>
值設為 "checkin_range"
。
範圍住宿
以下範例顯示兩種不同的範圍住宿用途,一項用於特定住宿範圍的住宿夜數,另一種則用於單晚:
<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
<!-- Google fetches prices for all itineraries (first and last date are set) -->
<Item>
<Property>12345</Property>
<StaysIncludingRange>
<FirstDate>2018-07-03</FirstDate>
<LastDate>2018-07-06</LastDate>
</StaysIncludingRange>
</Item>
<!-- Google fetches prices for a single night (first date only) -->
<Item>
<Property>67890</Property>
<StaysIncludingRange>
<FirstDate>2018-07-03</FirstDate>
</StaysIncludingRange>
</Item>
</Hint>
請注意,如果要在單一 <Item>
中指定多個屬性,範圍住宿訊息,必須將 <QueryControl>
中的 <MultipleItineraries>
值設為 "affected_dates"
。
對於這些範例,Google 都會回應 <Query>
,而您應該回應 <Transaction>
,其中包含指定飯店/行程的最新價格資訊。
<HintRequest>
Hint 要求訊息的根元素。Google 會向您的伺服器傳送 Hint 要求訊息並預期回應,指出自 Google 上次收到伺服器成功的 Hint 回應後,價格有所變動的飯店和行程。
如果價格有任何變動,Google 就會傳送 <Query>
,用於擷取指定飯店和行程的最新價格資料。
詳情請參閱提示要求訊息。
語法
<HintRequest>
元素使用下列語法:
語法
<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
<LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>
屬性
<HintRequest>
元素沒有屬性。
子元素
<HintRequest>
元素包含下列子元素:
子元素 | 類型 | 說明 |
---|---|---|
<LastFetchTime> | DateTime | 上次 Google 成功收到提示要求訊息的提示訊息的時間。
如果這個時間早於上次在伺服器上更新價格的時間,您應該回覆提示訊息訊息,指出哪些飯店已有異動。 如果近期未曾成功擷取,會設為固定的時間間隔 (以免大型待處理記錄檔發生更嚴重的問題)。目前的固定間隔值為 1000 秒,但可能會有變動。 詳情請參閱 Hint 回應訊息。 |
範例
以下範例顯示「Hint 要求訊息」:
Hint 要求訊息
以下範例顯示 Hint 要求訊息:
<?xml version="1.0" encoding="UTF-8"?>
<HintRequest id="ABCDEF" timestamp="2018-06-07T16:20:00Z">
<LastFetchTime>2018-03-25T00:04:09Z</LastFetchTime>
</HintRequest>
<Query>
Query
訊息的根元素。Query
訊息是 Google 針對價格或中繼資料更新提出的要求。這類定價可搭配「提取」和「變更價格」放送模式使用。
Query
訊息有三種類型:
即時價格:Google 會回應特定使用者要求,要求即時更新價格。合作夥伴收到
Live pricing query
訊息時,合作夥伴應回覆<Transaction>
訊息,其中含有<Result>
元素中要求的定價資訊。使用內容價格:Google 會根據歷來熱門的背景資訊更新價格快取。收到
With context query
訊息時,您應該以<Transaction>
訊息回應,其中應含<Result>
元素中要求的定價資訊。中繼資料:Google 會要求更新指定飯店的客房和客房套裝組合中繼資料。當您收到
Metadata Query
訊息時,應以<Transaction>
訊息回應,指定<PropertyDataSet>
元素中會議室和 Room 套件的相關資料。
詳情請參閱定價查詢的定價總覽,並針對中繼資料查詢使用 Room Bundle 中繼資料。
以下是三種不同類型的語法。
語法
<Query>
元素使用下列語法:
即時價格
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
<Checkin>YYYY-MM-DD</Checkin>
<Nights>number_of_nights</Nights>
<!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
<FirstDate>YYYY-MM-DD</FirstDate>
<LastDate>YYYY-MM-DD</LastDate>
<!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
<AffectedNights>number_of_nights</AffectedNights>
<PropertyList>
<Property>hotel_id</Property>
...
</PropertyList>
<!-- See documentation below for <Context> -->
<Context>
...
</Context>
</Query>
包含情境
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>YYYY-MM-DD</Checkin>
<Nights>number_of_nights</Nights>
<!-- Only for Check-in Date Range pricing queries (Changed Pricing) -->
<FirstDate>YYYY-MM-DD</FirstDate>
<LastDate>YYYY-MM-DD</LastDate>
<!-- Only for Ranged Stay pricing queries (Changed Pricing) -->
<AffectedNights>number_of_nights</AffectedNights>
<PropertyContextList>
<PropertyContext>
<Property>hotel_id</Property>
...
<!-- See documentation below for <Context> -->
<Context>
...
</Context>
</PropertyContext>
</PropertyContextList>
</Query>
Metadata
<HotelInfoProperties>
<Property>property_ID</Property>
...
</HotelInfoProperties>
屬性
<Query>
元素可以包含一個屬性:latencySensitive
。
latencySensitive
為選用屬性。提供並設為 true
時,表示查詢為 Live Pricing Query
。如要讓 Google 傳送具有 latencySensitive
屬性的查詢,請洽詢您的客戶技術顧問 (TAM)。
子元素
<Query>
元素包含下列子元素:
子元素 | 查詢類型 | 類型 | 說明 |
---|---|---|---|
<AffectedNights> | Pricing | integer | 特定範圍的住宿夜數。這個元素僅適用於搭配變更價格使用 Ranged Stay 定價查詢。 |
<Checkin> | Pricing | Date | 特定價格異動的日期。 |
<Context> | Pricing (Live Pricing Queries only) | <Context> | 針對即時價格查詢,請指定用於查詢的特定參數。子元素包括:
您可以在單一要求中重複使用 |
<FirstDate> | Pricing | Date | 價格適用行程範圍的開始日期。這個元素僅適用於「入住日期範圍」定價查詢 (搭配已變更價格使用)。 |
<HotelInfoProperties> | Metadata | string | Google 要在中繼資料 Query 訊息中更新一或多個房源和 Room Bundle 中繼資料,這個元素可包含一或多個指定飯店房源 ID 的 <Property> 元素。 |
<LastDate> | Pricing | Date | 價格適用的行程結束日期。這個元素僅適用於搭配提取 + 提示使用的「入住日期範圍」定價查詢。 |
<Nights> | Pricing | integer | 特定行程的住宿晚數,最多 30 晚。 |
<PropertyList> | Pricing | Object | 一或多個需要更新價格的飯店 ID。 在 <PropertyList> <Property>pid1</Property> <Property>pid2</Property> </PropertyList> |
範例
定價查詢
以下範例顯示要求更新一組飯店價格 (從 2018 年 6 月 10 日開始提供 3 晚可預訂) 的定價查詢訊息:
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>2023-05-23</Checkin>
<Nights>3</Nights>
<PropertyList>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</PropertyList>
</Query>
即時價格查詢
以下範例顯示回應時間限制為 500 毫秒的即時價格查詢:
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<Checkin>2017-06-07</Checkin>
<Nights>5</Nights>
<DeadlineMs>500</DeadlineMs>
<PropertyList>
<Property>8675309</Property>
</PropertyList>
<Context>
<Occupancy>4</Occupancy>
<OccupancyDetails>
<NumAdults>2</NumAdults>
<Children>
<Child age="8"/>
<Child age="5"/>
</Children>
</OccupancyDetails>
<UserCountry>US</UserCountry>
<UserDevice>mobile</UserDevice>
</Context>
</Query>
使用結構定義查詢
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<Checkin>2023-05-23</Checkin>
<Nights>2</Nights>
<PropertyContextList>
<PropertyContext>
<Property>8675309</Property>
<!-- In the future, occupancy and device might be specified -->
<Context><UserCountry>US</UserCountry></Context>
<Context><UserCountry>GB</UserCountry></Context>
</PropertyContext>
<PropertyContext>
<Property>8675310</Property>
<Property>8675311</Property>
<Context><UserCountry>CA</UserCountry></Context>
</PropertyContext>
</PropertyContextList>
</Query>
中繼資料查詢
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<HotelInfoProperties>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</HotelInfoProperties>
</Query>
如需其他範例,包括日期範圍入住和入住日期範圍的定價查詢,請參閱 Query
訊息範例。
<Context>
<Context>
元素會說明 Live pricing query
的資訊,包括訪客數量和類型、使用者國家/地區和使用者裝置。
多個 <Context>
一律無法和不同的使用者國家/地區或使用者裝置使用。如要使用多個 <Context>
查詢多個可住人數,請針對每個可住人數提供每個可住價格,做為相應屬性/行程的額外 Room 套裝組合。每個房源/行程應有一個 <Result>
區塊,其中納入多種人次的價格。
如需 <Context>
查詢的回應詳細資料,請參閱 <OccupancyDetails>
。
語法
<Context>
元素使用下列語法:
語法
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true_or_false">
<Checkin>date</Checkin>
<Nights>number_of_nights</Nights>
<DeadlineMs>number_of_milliseconds</DeadlineMs>
<PropertyList>
<Property>property_ID</Property>
</PropertyList>
<Context>
<Occupancy>total_number_of_guests</Occupancy>
<OccupancyDetails>
<NumAdults>number_of_adults</NumAdults>
<Children>
<Child age=age_of_one_child_guest/>
<Child age=age_of_one_child_guest/>
</Children>
</OccupancyDetails>
<UserCountry>end_user_country</UserCountry>
<UserDevice>user_device_type</UserDevice>
</Context>
</Query>
子元素
<Context>
元素包含下列子元素:
子元素 | 查詢類型 | 類型 | 說明 |
---|---|---|---|
<Occupancy> | Pricing | integer | 指定房客總數。 雖然您不一定要使用 注意: |
<OccupancyDetails> | Pricing | Object | 前面有 <Occupancy> 。依據類型指定邀請對象,包括:
雖然您不一定要使用 注意: |
<UserCountry> | Pricing | string | 依使用者所在的國家/地區篩選費率。這個值是由 2 個英文字母組成的國家/地區代碼,例如 定義 |
<UserDevice> | Pricing | string | 依據使用者用來搜尋的裝置類型篩選費率。可能的類型包括:
定義 |
範例
人員偵測狀態
以下範例顯示 <Context>
中 <Occupancy>
的即時價格查詢。即時價格查詢適用於 3 位成人訪客。
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<Checkin>2017-06-07</Checkin>
<Nights>4</Nights>
<DeadlineMs>500</DeadlineMs>
<PropertyList>
<Property>45617</Property>
</PropertyList>
<Context>
<Occupancy>3</Occupancy>
<UserCountry>US</UserCountry>
<UserDevice>mobile</UserDevice>
</Context>
</Query>
可住人數詳細資料
以下範例顯示 <Context>
內帶有 <OccupancyDetails>
的即時價格查詢。即時價格查詢適用於 4 位房客,其中 2 位是兒童,並在行動裝置上尋找適用於美國訪客預訂的費率:
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<Checkin>2017-06-07</Checkin>
<Nights>5</Nights>
<DeadlineMs>500</DeadlineMs>
<PropertyList>
<Property>8675309</Property>
</PropertyList>
<Context>
<Occupancy>4</Occupancy>
<OccupancyDetails>
<NumAdults>2</NumAdults>
<Children>
<Child age="4"/>
<Child age="12"/>
</Children>
</OccupancyDetails>
<UserCountry>US</UserCountry>
<UserDevice>mobile</UserDevice>
</Context>
</Query>
多個情境
以下範例顯示如何在即時價格查詢中使用額外的 <Context>
元素。
<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<Checkin>2017-06-07</Checkin>
<Nights>4</Nights>
<DeadlineMs>500</DeadlineMs>
<PropertyList>
<Property>45617</Property>
</PropertyList>
<Context>
<Occupancy>3</Occupancy>
<UserCountry>US</UserCountry>
<UserDevice>mobile</UserDevice>
</Context>
<Context>
<Occupancy>6</Occupancy>
<OccupancyDetails>
<NumAdults>4</NumAdults>
<Children>
<Child age="6"/>
<Child age="10"/>
</Children>
</OccupancyDetails>
<UserCountry>US</UserCountry>
<UserDevice>mobile</UserDevice>
</Context>
</Query>