查詢 &；提示 XML 參考資料

本節提供以 Google XML 為基礎的參考資訊 Hint 要求訊息、 Hint Response 訊息、 和查詢訊息。

<Hint> (提示回應訊息)

Hint 回應訊息的根元素。提示回應訊息 指定應調整哪些飯店/行程組合的價格。這些是你的 回覆提示要求訊息 都是由 Google 開發的

提示回應訊息應僅指定價格有相關房價的飯店 自 上次收到 Google 從上次成功收到 Hint 回應後變更過來的結果： 伺服器

Hint Response 訊息會使用下列其中一種方法，指定 但 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 屬性的形式加入 <Query> 中 根據此<Hint>傳送的訊息。

子元素

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

子項元素 必填與否 類型 提示回應類型 說明
<CheckInDate> Required Date 確切的行程 行程入住日期。
<FirstDate> Required Date 入住範圍和範圍行程 入住範圍或範圍內，日期範圍的第一個日期 保持 Hint 回應訊息。日期內含。
<Item> Required Object 全部 要更新的飯店/行程容器。
<LastDate> Required* Date 入住範圍和範圍行程

入住範圍或範圍內日期範圍的最後日期 保持 Hint 回應訊息。日期內含。

* 此元素是範圍入住的選用元素。
<LengthOfStay> Required integer 確切行程 行程住宿晚數，以正數表示 整數值。
<Property> Required string 全部

飯店的 ID，使用與飯店清單相同的 ID。圖表中的數字 在單一元素中指定的 <Property> 元素 <Item> 區塊取決於提示類型 回覆訊息：

  • 確切的行程：最多 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>

Hint 要求訊息的根元素。Google 會傳送提示要求 訊息傳送給伺服器，並預期回應中指定了飯店和 價格在 Google 上次收到 伺服器傳回成功的 Hint 回應。

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

詳情請參閱提示要求訊息。

語法

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

語法

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

屬性

<HintRequest> 元素沒有屬性。

子元素

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

子項元素 類型 說明
<LastFetchTime> DateTime Google 上次成功收到提示回應訊息的時間 Hint 要求訊息。

如果該時間早於你上次 然後以提示回應 指出哪些飯店變更了的回應訊息。

如果最近沒有成功擷取，系統會將這個值設為 固定間隔值 (避免大型資料集 待處理工作)。目前的固定間隔值為 1000 秒 隨時可能變動

如需更多資訊 請參閱提示回應訊息。

範例

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

提示要求訊息

以下範例顯示 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 則訊息屬於要求 ，以更新價格或中繼資料。兩者都用於提取式 和價格變更的放送模式。

Query 訊息有三種類型：

  • 即時價格：Google 會回應特定使用者要求 即時價格更新合作夥伴收到Live pricing query時 訊息，合作夥伴應以 <Transaction> 訊息回應 <Result> 元素包含要求的定價資訊。

  • 與情境價格：Google 會根據情境更新價格快取 是歷來熱門產品收到With context query時 訊息，您應該以 <Transaction> 訊息回應， <Result> 元素中要求的價格資訊。

  • 中繼資料：Google 會要求更新會議室和會議室套裝組合的中繼資料 查詢指定飯店的飯店資訊收到「Metadata Query」訊息時， 應傳回 <Transaction> 訊息，指出 <PropertyDataSet> 元素中的會議室和會議室套裝組合。

詳情請參閱「定價總覽」一文 查看定價查詢和 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 特定日期範圍的住宿晚數。這個元素會使用這個元素 僅適用於採用「價格變更」模式的查詢。
<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 中繼資料。這個元素 可包含一或多個 <Property> 元素 請指定飯店房源 ID。
<LastDate> Pricing Date 價格範圍的行程結束日期 此元素僅適用於入住日期範圍定價 搭配「提取 + 提示」使用的查詢。
<Nights> Pricing integer 特定行程的住宿晚數，最多 30 個。
<PropertyList> Pricing Object

需要更新價格的飯店的一或多個 ID。

在 <Property> 元素中定義每間飯店。 值是與飯店清單中的飯店 ID 相符的字串。適用對象 範例：

<PropertyList>
  <Property>pid1</Property>
  <Property>pid2</Property>
</PropertyList>

範例

定價查詢

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

<?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>所定義。

注意：<Occupancy> 不一定每次都會顯示 文字片段這種情況下，建議您傳回所有 使用人數
<OccupancyDetails> Pricing Object 前方加上 <Occupancy>。依類型指定邀請對象： 包括：

  • <NumAdults>：成人房客人數
  • <Children> 和 <Child="age">： 指定哪些邀請對像是兒童 (通常為 0 到 17 歲)，以及 可選擇加入每個孩子的年齡

    • 雖然非強制規定，但使用 <OccupancyDetails> 的查詢 應會收到包含適當 Room Bundle 的交易訊息 是依據每筆查詢<Occupancy>所定義。

    注意： <OccupancyDetails> 不一定每次都會出現 出現在查詢中此時，請務必假設所有邀請對象 成人。
<UserCountry> Pricing string

依使用者所在國家/地區篩選費率。這個值是 雙字母的國家/地區代碼，例如 “US” 代表美國，或是 區碼，例如 "EU" 代表「歐洲」。

定義 <UserCountry> 的查詢應結果 含有適當 <Rates> 的交易訊息 為所查詢國家/地區定義的方塊
<UserDevice> Pricing string

依據使用者搜尋的裝置類型篩選費率。 可能的類型包括：

  • mobile
  • desktop
  • tablet

定義 <UserDevice> 的查詢應會產生 交易訊息和適當的 <Rates> 依據所查詢裝置類型定義的區塊。

範例

可住人數

以下範例顯示 <Occupancy> 的即時價格查詢 在 <Context>內。即時價格查詢適用於 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>