查询和提示 XML 参考

本部分提供了基于 Google XML 的提示请求消息、提示响应消息和查询消息的参考文档。

<Hint>（Hint 回应消息）

Hint 响应消息的根元素。提示响应消息用于指定应重新定价哪些酒店或行程组合。这些信息是您对 Google 发送的提示请求消息的回复。

提示响应消息应仅指定自上次 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 -->
    <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 -->
    <Property>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</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>

住宿晚数范围

以下示例展示了范围住宿的两种不同用法，一种适用于一段时间内的住宿，另一种适用于单晚住宿：

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

对于上述每个示例，Google 都会回复 <Query>，然后您应回复 <Transaction>，其中包含指定酒店/行程的价格更新。

<HintRequest>

Hint 请求消息的根元素。Google 会向您的服务器发送提示请求消息，并希望收到的响应中指定自上次 Google 从您的服务器成功收到提示响应以来价格发生变化的酒店和行程。

如果价格发生任何变化，Google 会发送 <Query> 以提取指定酒店和行程的更新价格数据。

如需了解详情，请参阅提示请求消息。

语法

<HintRequest> 元素使用以下语法：

语法

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

属性

<HintRequest> 元素没有属性。

子元素

<HintRequest> 元素具有以下子元素：

子元素 类型 说明
<LastFetchTime> DateTime Google 上次成功收到对提示请求消息的提示响应消息的时间。

如果此时间早于您上次在服务器上更新价格的时间，则您应回复一条提示响应消息，指明哪些酒店的价格发生了变化。

如果最近没有成功提取数据，则此值将设置为固定间隔值（以避免出现大量积压问题而导致更严重的问题）。当前的固定间隔值为 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 消息是 Google 发送的价格或元数据更新请求。它们可与拉取和价格更改传送模式搭配使用。

价格查询消息

价格查询消息用于指定您要为其提供价格的房源和行程组合。

当您的服务器收到价格查询消息时，应响应一个包含请求的价格信息的 <Transaction> 消息。

如需了解详情，请参阅价格概览。

Query 消息有三种特殊类型：

  • 实时价格：Google 会响应用户请求，提供实时价格更新。合作伙伴收到 Live pricing query 消息后，应回复 <Transaction> 消息，其中包含 <Result> 元素中请求的价格信息。

  • 启用情境定价：Google 会根据历史上热门的情境更新价格缓存。收到 With context query 消息后，您应回复 <Transaction> 消息，并在 <Result> 元素中包含请求的价格信息。

  • 元数据：Google 会请求更新指定酒店的客房和客房套餐的元数据。收到 Metadata Query 消息后，您应回复 <Transaction> 消息，在 <PropertyDataSet> 元素中指定客房和客房套餐的相关数据。如需了解详情，请参阅房间套装元数据。

语法

<Query> 元素使用以下语法：

价格查询

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</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 消息中更新客房和客房套餐元数据的一个或多个房源。 此元素可以包含一个或多个 <Property> 元素，用于指定酒店房源 ID。
<LastDate> Pricing Date 适用此价格的一系列行程的结束日期。此元素仅适用于与拉取 + 提示一起使用的入住日期范围价格查询。
<Nights> Pricing integer 特定行程的晚数（最多 30 晚）。
<PropertyList> Pricing Object

需要更新价格的酒店的一个或多个 ID。

在 <Property> 元素中定义每家酒店。此值是一个字符串，与酒店列表中的酒店 ID 匹配。例如：

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

示例

价格查询

以下示例展示了一个价格查询消息，该消息请求更新一组酒店的价格，入住晚数为 3 晚，开始日期为 2023 年 5 月 23 日：

<?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> 元素。

注意：<Occupancy> 可能并不总会显示在查询中。在这种情况下，您应返回所有入住人数的价格。
<OccupancyDetails> Pricing Object 前面是 <Occupancy>。按类型指定房客，包括：
  • <NumAdults>：成人同乘者人数
  • <Children> 和 <Child="age">：指定哪些房客是儿童（通常为 0-17 周岁），并可选择包含每个儿童的年龄。

虽然不是强制性要求，但使用 <OccupancyDetails> 进行查询应会生成包含为每个 <Occupancy> 定义的适当客房套餐的交易消息，但如果客房套餐不可用，建议您指定 <OccupancyDetails> 元素。

注意： <OccupancyDetails> 可能不会始终显示在查询中。在这种情况下，您应假定所有房客都是成人。
<UserCountry> Pricing string

按用户所在的国家/地区过滤费率。值是 2 个字母的国家/地区代码（例如 "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>