查询和提示 XML 参考

本部分提供了基于 Google XML 的 Hint 请求消息， Hint 响应消息， 和查询消息。

<Hint>（提示响应消息）

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

Hint Response 消息应仅指定那些价格已 自上次 Google 从以下对象收到成功的提示响应后发生了变化 您的服务器。

Hint 响应消息可使用以下方法之一来指定 Google 应重新定价的酒店和行程：

  • 确切行程：入住日期和 住宿晚数。

  • 入住日期范围：指定入住日期范围，从第一个入住日期开始，到最后一个入住日期结束。

  • 非固定行程（或非指定行程）

每种方法都需要使用不同的提示响应消息语法。

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

语法

<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 -->
    <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>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 签到范围和范围限定的行程 入住范围或范围的日期范围的第一个日期 keep Hint 响应消息。包括日期。
<Item> Required Object 全部 用于更新的酒店/行程的容器。
<LastDate> Required* Date 签到范围和范围限定的行程

入住范围或范围的日期范围的结束日期 keep Hint 响应消息。日期包括当天。

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

酒店的 ID，与酒店列表中使用的 ID 相同。数值 <Property>个元素，您可以在单个 <Item> 块由提示类型决定 响应消息：

  • 确切行程：最多 100 家酒店。
  • 所在位置范围：如果您设置了多个范围 通过<QueryControl>消息向"checkin_range" <MultipleItineraries>。
  • 远程住宿：如果您设置了多个入住 通过<QueryControl>消息向"affected_dates" <MultipleItineraries>。
<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 获取 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>

提示请求消息的根元素。Google 会发送提示请求 “消息”发送至您的服务器，并预计会得到一个响应，该响应指明了酒店 自上次 Google 收到 来自您的服务器的成功 Hint 响应。

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

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

语法

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

语法

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

属性

<HintRequest> 元素没有属性。

子元素

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

子元素 类型 说明
<LastFetchTime> DateTime Google 上次成功接收“提示响应”消息的时间 。

如果这个时间早于您上次 更新价格时，您应该在响应中提供提示 指明已更改酒店的响应消息。

如果最近没有成功提取，则将设置为 固定间隔值（以避免使用较大的 积压）。当前的固定间隔值为 1000 秒，但 可能会发生变化。

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

示例

以下示例展示了一条 Hint Request 消息：

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> 元素中指定客房和客房套餐的相关数据。

如需了解详情，请参阅价格概览（针对价格查询）和客房套餐元数据（针对元数据查询）。

三种不同类型的语法如下：

语法

<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> 元素。
<LastDate> Pricing Date 定价所针对的一系列行程的结束日期 。此元素仅用于入住日期范围定价 与“拉取 + 提示”搭配使用的查询。
<Nights> Pricing integer 特定行程的住宿晚数，最多 30 晚。
<PropertyList> Pricing Object

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

在 <Property> 元素中定义每家酒店。通过 value 是一个与您的酒店列表中的酒店 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> 元素。

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

包含 <OccupancyDetails> 的查询虽然不是强制性的， 应能生成包含相应 Room 的事务消息 为每个 <Occupancy> 定义的 Bundle，但如果 客房套餐不可用，建议您 指定 <OccupancyDetails> 元素。

注意：<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> 元素 创建 Deployment 清单

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