查询和提示 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 所有 要更新的酒店/行程的容器。
<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 会获取媒体资源 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 会向您的服务器发送提示请求消息,并预期收到一个响应,其中指明自 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 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> 元素中包含所请求的价格信息。

  • 使用情境价格: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 消息中包含其更新的客房和客房套餐元数据的一个或多个房源。此元素可以包含一个或多个指定酒店房源 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> 定义的适当 Room Bundle。

注意<Occupancy> 不一定会显示在查询中。在这种情况下,您应返回所有入住人数的价格。

<OccupancyDetails> Pricing Object 前面为 <Occupancy>。按类型指定访客,包括:

  • <NumAdults>:成人房客人数
  • <Children><Child="age">:指定哪些房客是儿童(通常为 0-17 岁),可以选择包含每个孩子的年龄。
  • 虽然不是强制性的,但使用 <OccupancyDetails> 进行的查询应该会生成一条事务消息,其中包含为查询的每个 <Occupancy> 定义的适当客房套餐。

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