此页面由 Cloud Translation API 翻译。

查询和提示 XML 参考

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

`<Hint>`（提示响应消息）

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

“提示响应”消息应仅指定自 Google 上次从您的服务器收到成功“提示响应”后价格发生过变化的酒店。

提示响应消息使用以下方法之一指定 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 -->
    <!-- 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。您可以在单个 `<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 会获取房源 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>`

提示请求消息的根元素。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 秒，但可能会发生变化。如需了解详情，请参阅提示响应消息。

子元素

类型

说明

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 消息是指来自 Google 的价格或元数据更新请求。它们与拉取和价格更改传送模式结合使用。

Query 消息有三种类型：

实时价格：Google 会对特定用户请求做出响应，要求进行实时价格更新。当合作伙伴收到 Live pricing query 消息时，合作伙伴应使用 <Transaction> 消息进行响应，该消息在 <Result> 元素中包含所请求的价格信息。

要点：由于全新搜索体验，实时查询不再面向欧洲经济区 (EEA) 用户提供。
使用情境价格：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>

示例

价格查询

以下示例展示了一条价格查询消息，该消息请求一组酒店的价格更新，自 2018 年 6 月 10 日起可供入住 3 晚：

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

语法

语法

属性

子元素

示例

Hint 请求消息

<Query>

语法

实时价格

有上下文

元数据

属性

子元素

示例

价格查询

实时价格查询

使用上下文查询

元数据查询

<Context>

语法

语法

子元素

示例

在家/外出

入住人数详细信息

多个上下文

`<Hint>`（提示响应消息）

`<HintRequest>`

`<Query>`

`<Context>`