本頁面由 Cloud Translation API 翻譯而成。

查詢 &；提示 XML 參考資料

本節提供以 Google XML 為基礎的提示要求訊息、提示回應訊息和查詢訊息。

`<Hint>` (提示回應訊息)

提示回應訊息的根元素。提示回應訊息會指定要為哪些飯店/行程組合重新價格。這些是您針對 Google 傳送的 Hint 要求訊息的回應。

Hint Response 訊息應僅指定自上次 Google 收到您的伺服器傳送成功的提示回應後，價格變動的飯店。

提示回應訊息使用下列其中一種方法，指定 Google 應重新標價的飯店和行程：

確切行程：入住日期和入住天數的組合。
入住日期範圍：指定入住日期範圍，從首次入住日期開始，結束於上次入住日期。
範圍住宿 (或固定行程)

上述每個方法都需要不同提示回應訊息的語法。

詳情請參閱「提示回應訊息」。

語法

視提示回應訊息的類型而定，<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。如果提供，就會以 hintId 屬性的形式包含在根據這個 <Hint> 傳送的 <Query> 訊息中。

子元素

<Hint> 元素包含下列子元素：

子元素	必填與否	類型	提示回應類型	說明
<CheckInDate>	Required	Date	確切行程	行程的入住日期。
<FirstDate>	Required	Date	入住範圍和範圍行程	入住日期範圍或指定時間範圍內保留提示回應訊息的日期範圍的第一個日期。日期已包含。
<Item>	Required	Object	全部	要更新的飯店/行程的容器。
<LastDate>	Required*	Date	入住範圍和範圍行程	入住日期範圍或指定時間範圍內保留提示回應訊息的日期範圍的最後日期。日期已包含。 * 指定範圍住宿選項時，不一定要使用這個元素。
<LengthOfStay>	Required	integer	確切行程	行程的住宿天數，以正整數表示。
<Property>	Required	string	全部	飯店 ID，使用與飯店清單相同的 ID。可在單一 `<Item>` 區塊中指定的 `<Property>` 元素數量，取決於提示回應訊息的類型：確切行程：最多 100 間飯店。入住範圍：如果您在 `<QueryControl>` 訊息中將 `<MultipleItineraries>` 設為 `"checkin_range"`，則為多個。範圍入住天數：如果在 `<QueryControl>` 訊息中將 `<MultipleItineraries>` 設為 `"affected_dates"`，則為多個範圍。
<Stay>	Required	Object	確切行程	確切行程提示回應訊息中 `<CheckinDate>` 和 `<LengthOfStay>` 元素的容器。每個 `<Item>` 只能包含一個 `<Stay>`。
<StaysIncludingRange>	Required	Object	範圍行程	存放範圍中 `<FirstDate>` 和 `<LastDate>` 元素的容器會保留提示回應訊息。

範例

確切行程

以下範例為單一屬性「提示回應」訊息定義多個行程：

<!-- 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>`

提示要求訊息的根元素。Google 會傳送提示要求訊息至您的伺服器，並預期在 Google 上次收到您的伺服器傳送成功提示回應後，價格出現變動的飯店和行程。

價格如有任何異動，Google 就會傳送 <Query>，擷取指定飯店和行程的更新價格資料。

詳情請參閱 Hint 要求訊息相關說明。

語法

<HintRequest> 元素使用下列語法：

語法

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

屬性

<HintRequest> 元素沒有屬性。

子元素

<HintRequest> 元素包含下列子元素：

子元素	類型	說明
<LastFetchTime>	DateTime	Google 上次成功接收提示要求訊息的提示回應訊息。如果這個時間早於您上次在伺服器中更新價格的時間，請回應「提示回應」訊息，指出哪些飯店有所變更。如果最近沒有成功擷取，則會設為固定間隔值 (以避免大型待處理工作發生更嚴重的問題)。目前的固定間隔值為 1000 秒，但可能會有變動。詳情請參閱提示回應訊息。

子元素

類型

說明

DateTime

Google 上次成功接收提示要求訊息的提示回應訊息。

如果這個時間早於您上次在伺服器中更新價格的時間，請回應「提示回應」訊息，指出哪些飯店有所變更。

如果最近沒有成功擷取，則會設為固定間隔值 (以避免大型待處理工作發生更嚴重的問題)。目前的固定間隔值為 1000 秒，但可能會有變動。

詳情請參閱提示回應訊息。

範例

以下範例顯示提示要求訊息：

提示要求訊息

以下範例顯示提示要求訊息：

<?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 Bundle 相關資料。

詳情請參閱定價查詢的定價總覽；如需中繼資料查詢，請參閱 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>

中繼資料

<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>	如為即時價格查詢，請指定查詢時使用的特定參數。子元素包括： `<Occupancy>`：房客總數 `<OccupancyDetails>`：訪客類型，例如成人或兒童 `<UserCountry>`：使用者所在的國家/地區 `<UserDevice>`：訪客用來搜尋飯店的裝置類型，例如 `"mobile`、`tablet` 或 `desktop`。在單一要求中可重複 `<Context>` 元素，以便查詢不同可住人數。如需子元素、語法和範例的清單，請參閱 `<Context>`。
<FirstDate>	Pricing	Date	特定行程範圍內的開始日期。這個元素僅適用於「入住日期範圍」採用「變更價格」的定價查詢。
<HotelInfoProperties>	Metadata	string	Google 希望在中繼資料 `Query` 訊息中更新一或多個屬性的會議室和 Room Bundle 中繼資料。這個元素可包含一或多個指定飯店房源 ID 的 `<Property>` 元素。
<LastDate>	Pricing	Date	價格涵蓋特定行程的結束日期。這個元素僅適用於搭配提取 + 提示使用的「入住日期範圍」定價查詢。
<Nights>	Pricing	integer	特定行程的住宿晚數 (上限為 30 天)。
<PropertyList>	Pricing	Object	一或多個需要更新價格的飯店 ID。在 `<Property>` 元素中定義每間飯店。這個值是與飯店清單中飯店 ID 相符的字串。例如： <PropertyList> <Property>pid1</Property> <Property>pid2</Property> </PropertyList>

範例

價格查詢

以下範例顯示一則定價查詢訊息，該訊息要求一組飯店的 3 晚價格更新，並自 2018 年 6 月 10 日起更新：

<?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> 查詢多個可住人數，請針對每個可住人數價格，提供相應屬性/行程的額外房型套裝組合。每個屬性/行程都應該有一個 <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	指定房客總數。雖然並非強制規定，但使用 `<Occupancy>` 的查詢應產生交易訊息，其中包含針對查詢的每個 `<Occupancy>` 定義的適當 Room Bundle。注意：`<Occupancy>` 不一定會顯示在查詢中。在這種情況下，您應該傳回所有可住人數的價格。
<OccupancyDetails>	Pricing	Object	前面加上 `<Occupancy>`。依類型指定訪客，包括： `<NumAdults>`：成人房客人數 `<Children>` 和 `<Child="age">`：指定哪些訪客為兒童 (通常為 0 至 17 歲)，並可視需要包含各個兒童的年齡。雖然並非強制規定，但使用 `<OccupancyDetails>` 的查詢應產生交易訊息，其中包含針對查詢的每個 `<Occupancy>` 定義的適當 Room Bundle。注意： `<OccupancyDetails>` 不一定會出現在查詢中。在這種情況下，您應該假設所有邀請對像都是成人。
<UserCountry>	Pricing	string	依使用者所在的國家/地區篩選費率。這個值為雙字母的國家/地區代碼 (例如美國的 `“US”`)，或是區碼 (例如 `"EU"` 代表「歐洲」)。定義 `<UserCountry>` 的查詢應會產生交易訊息，其中包含針對所查詢國家/地區定義的適當 `<Rates>` 區塊。
<UserDevice>	Pricing	string	依據使用者進行搜尋的裝置類型篩選費率。可能的類型包括： `mobile` `desktop` `tablet` 定義了 `<UserDevice>` 的查詢應會產生交易訊息，其中包含針對所查詢裝置類型定義的適當 `<Rates>` 區塊。

範例

人員偵測狀態

以下範例顯示 <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>

查詢 &；提示 XML 參考資料

<Hint> (提示回應訊息)

語法

確切行程

入住範圍

範圍住宿

屬性

子元素

範例

確切行程

入住範圍

範圍住宿

<HintRequest>

語法

語法

屬性

子元素

範例

提示要求訊息

<Query>

語法

即時價格

有背景資訊

中繼資料

屬性

子元素

範例

價格查詢

即時價格查詢

含有內容查詢

中繼資料查詢

<Context>

語法

語法

子元素

範例

人員偵測狀態

可住人數詳細資料

多個結構定義

`<Hint>` (提示回應訊息)

`<HintRequest>`

`<Query>`

`<Context>`