查询和提示 XML 参考

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

<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 -->
    <!-- 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 All 要更新的酒店/行程的容器。
<LastDate> Required* Date 入住范围和范围行程

入住范围或指定住宿地点的日期范围的最后日期 提示响应消息。包含日期。

* 对于范围住宿，此元素是可选的。
<LengthOfStay> Required integer 确切行程 行程的住宿晚数，以正整数表示。
<Property> Required string All

酒店的 ID，使用的 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> 元素的容器。

示例

确切行程

以下示例为 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 将获取媒体资源 12345 和 67890 之间 7 月 3 日至 7 月 6 日的所有行程：

<!-- 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 从您的服务器收到成功的提示响应后价格发生了更改的酒店和行程。

如有任何价格变动，Google 随后会发送 <Query>，用于获取指定酒店和行程的更新价格数据。

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

语法

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

语法

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

属性

<HintRequest> 元素没有属性。

子元素

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

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

如果这个时间早于您上次在服务器上更新价格的时间，那么您应该使用提示响应消息进行响应，指明哪些酒店已更改。

如果没有最近的成功提取，此值将设置为固定的间隔值（以避免大型积压造成的更严重问题）。当前的固定间隔值为 1, 000 秒，但可能会发生变化。

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

示例

以下示例展示了一条提示请求消息：

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 软件包元数据（适用于元数据查询）。

三种不同类型的语法如下所述。

语法

<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 消息中更新其客房和客房套餐元数据的一个或多个房源。此元素可以包含一个或多个指定酒店房源 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> 定义的适当房间套餐。

注意：<Occupancy> 不一定会显示在查询中。在这种情况下，您应返回所有入住人数的价格。
<OccupancyDetails> Pricing Object 其前面为 <Occupancy>。按类型指定访客，包括：

  • <NumAdults>：成人房客数量
  • <Children> 和 <Child="age">：指定哪些访客是儿童（通常为 0-17 岁），并且可以选择性地添加每个孩子的年龄。

    • 使用 <OccupancyDetails> 进行的查询虽然不是强制性的，但应生成一条事务消息，其中包含为查询的每个 <Occupancy> 定义的适当房间套餐。

    注意 ：<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>