本部分提供了基于 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。您可以在单个
|
<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 秒,但可能会发生变化。 如需了解详情,请参阅提示响应消息。 |
示例
以下示例展示了一条 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 软件包元数据(适用于元数据查询)。
三种不同类型的语法如下所述。
语法
<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> | 对于实时价格查询,指定在哪些参数下执行查询。子元素包括:
|
<FirstDate> | Pricing | Date | 此价格适用的一系列行程的开始日期。此元素仅用于与价格更改搭配使用的入住日期范围价格查询。 |
<HotelInfoProperties> | Metadata | string | Google 希望在元数据 Query 消息中更新客房和客房套餐元数据的一个或多个房源。此元素可以包含一个或多个指定酒店房源 ID 的 <Property> 元素。 |
<LastDate> | Pricing | Date | 此价格适用的一系列行程的结束日期。此元素仅用于与“拉取 + 提示”搭配使用的入住日期范围价格查询。 |
<Nights> | Pricing | integer | 特定行程的住宿晚数,最多 30 晚。 |
<PropertyList> | Pricing | Object | 需要更新价格的酒店的一个或多个 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 | 指定邀请对象的总数。 虽然并非强制性要求,但使用 注意: |
<OccupancyDetails> | Pricing | Object | 前缀为 <Occupancy> 。按类型指定邀请对象,包括:
虽然并非强制性要求,但使用 注意 : |
<UserCountry> | Pricing | string | 根据用户所在的国家/地区过滤费率。此值是两个字母的国家/地区代码(例如 定义了 |
<UserDevice> | Pricing | string | 根据用户执行搜索时所用设备的类型过滤费率。可能的值:
定义了 |
示例
在家/外出
以下示例展示了 <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>