Phần này cung cấp thông tin tham khảo cho các thông báo Yêu cầu gợi ý, thông báo Phản hồi gợi ý và thông báo Truy vấn dựa trên XML của Google.
<Hint>
(thông báo Phản hồi gợi ý)
Thành phần gốc của thông báo Phản hồi gợi ý. Thông báo Phản hồi gợi ý xác định tổ hợp khách sạn/hành trình nào cần được đặt giá lại. Thông báo là phản hồi của bạn cho thông báo Yêu cầu gợi ý của Google.
Thông báo Phản hồi gợi ý chỉ nên xác định những khách sạn có giá đã thay đổi kể từ lần gần đây nhất Google nhận được Phản hồi gợi ý thành công từ máy chủ của bạn.
Thông báo Phản hồi gợi ý sử dụng một trong các phương thức sau để xác định khách sạn và hành trình mà Google nên đặt giá lại:
Hành trình chính xác: Sự kết hợp giữa ngày nhận phòng và thời gian lưu trú.
Phạm vi ngày nhận phòng: Chỉ định phạm vi ngày nhận phòng, bắt đầu từ ngày nhận phòng đầu tiên và kết thúc bằng ngày nhận phòng cuối cùng.
Thời gian lưu trú theo phạm vi ngày (hay hành trình theo phạm vi)
Mỗi phương thức trong số này yêu cầu một cú pháp khác nhau cho thông báo Phản hồi gợi ý.
Để biết thêm thông tin, hãy tham khảo thông báo Phản hồi gợi ý.
Cú pháp
Cú pháp của phần tử <Hint>
sẽ khác nhau, tuỳ thuộc vào loại thông báo Phản hồi gợi ý:
Hành trình chính xác
Dưới đây là cú pháp cho hành trình chính xác trong một thông báo Phản hồi gợi ý:
<!-- 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>
Phạm vi ngày nhận phòng
Dưới đây là cú pháp cho phạm vi ngày nhận phòng trong thông báo Phản hồi gợi ý:
<!-- 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>
Thời gian lưu trú theo phạm vi ngày
Dưới đây là cú pháp cho thời gian lưu trú theo phạm vi trong thông báo Phản hồi gợi ý:
<!-- 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>
Thuộc tính
Phần tử <Hint>
chứa một thuộc tính không bắt buộc: id
. Khi được cung cấp, thuộc tính này sẽ được đưa vào dưới dạng thuộc tính hintId
trong các thông báo <Query>
được gửi dựa trên <Hint>
này.
Phần tử con
Phần tử <Hint>
có các phần tử con sau đây:
Phần tử con | Bắt buộc? | Loại | Loại phản hồi gợi ý | Nội dung mô tả |
---|---|---|---|---|
<CheckInDate> | Required | Date | Hành trình chính xác | Ngày nhận phòng của hành trình. |
<FirstDate> | Required | Date | Phạm vi ngày nhận phòng và hành trình theo phạm vi ngày | Ngày đầu tiên trong phạm vi ngày của thông báo Phản hồi gợi ý theo phạm vi ngày nhận phòng hoặc thời gian lưu trú theo phạm vi ngày. Giá trị ngày được tính toàn bộ. |
<Item> | Required | Object | Tất cả | Vùng chứa khách sạn/hành trình cần cập nhật. |
<LastDate> | Required* | Date | Phạm vi ngày nhận phòng và hành trình theo phạm vi ngày | Ngày cuối cùng trong phạm vi ngày của thông báo Phản hồi gợi ý theo phạm vi ngày nhận phòng hoặc thời gian lưu trú theo phạm vi ngày. Giá trị ngày được tính toàn bộ. * Phần tử này là không bắt buộc đối với thời gian lưu trú theo phạm vi ngày. |
<LengthOfStay> | Required | integer | Hành trình chính xác | Số đêm của hành trình, được biểu thị bằng số nguyên dương. |
<Property> | Required | string | Tất cả | Mã của một khách sạn, giống với mã trong Danh sách khách sạn. Số lượng phần tử
|
<Stay> | Required | Object | Hành trình chính xác | Vùng chứa các phần tử <CheckinDate> và <LengthOfStay> trong thông báo Phản hồi gợi ý sử dụng hành trình chính xác. Mỗi <Item> chỉ có thể chứa một <Stay> duy nhất. |
<StaysIncludingRange> | Required | Object | Hành trình theo phạm vi | Vùng chứa các phần tử <FirstDate> và <LastDate> trong thông báo Phản hồi gợi ý về thời gian lưu trú theo phạm vi ngày. |
Ví dụ
Hành trình chính xác
Dưới đây là ví dụ về cách xác định nhiều hành trình cho một cơ sở lưu trú duy nhất trong thông báo Phản hồi gợi ý:
<!-- 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>
Phạm vi ngày nhận phòng
Ví dụ sau đây chỉ định hai khách sạn có giá đã thay đổi và cần được tìm nạp lại. Google nhận được tất cả các hành trình từ ngày 3 tháng 7 đến ngày 6 tháng 7 đối với cơ sở lưu trú 12345 và 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>
Xin lưu ý rằng để thông báo phạm vi ngày nhận phòng có thể chỉ định nhiều thuộc tính trong một <Item>
, bạn phải đặt giá trị của <MultipleItineraries>
trong <QueryControl>
thành "checkin_range"
.
Thời gian lưu trú theo phạm vi ngày
Ví dụ sau đây cho thấy hai cách sử dụng thời gian lưu trú theo phạm vi ngày, một cách cho số đêm và cách còn lại cho một đêm:
<!-- 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>
Xin lưu ý rằng để thông báo thời gian lưu trú theo phạm vi có thể chỉ định nhiều thuộc tính trong một <Item>
, giá trị của <MultipleItineraries>
trong <QueryControl>
phải được đặt thành "affected_dates"
.
Đối với mỗi ví dụ này, Google sẽ phản hồi bằng một <Query>
. Sau đó, bạn nên phản hồi bằng một <Transaction>
chứa thông tin cập nhật về giá của các khách sạn/hành trình được chỉ định.
<HintRequest>
Thành phần gốc của thông báo Yêu cầu gợi ý. Google sẽ gửi thông báo Yêu cầu gợi ý đến máy chủ của bạn và dự kiến phản hồi sẽ cho biết những khách sạn và hành trình có giá đã thay đổi kể từ lần gần đây nhất Google nhận được Phản hồi gợi ý thành công từ máy chủ của bạn.
Nếu giá có thay đổi, Google sẽ gửi <Query>
để tìm nạp dữ liệu giá mới cho các khách sạn và hành trình được chỉ định.
Để biết thêm thông tin, hãy tham khảo bài viết Thông báo yêu cầu gợi ý.
Cú pháp
Phần tử <HintRequest>
sử dụng cú pháp sau:
Cú pháp
<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
<LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>
Thuộc tính
Phần tử <HintRequest>
chưa có thuộc tính nào.
Phần tử con
Phần tử <HintRequest>
có các phần tử con sau đây:
Phần tử con | Loại | Nội dung mô tả |
---|---|---|
<LastFetchTime> | DateTime | Lần gần đây nhất mà Google nhận được thông báo Phản hồi gợi ý cho một thông báo Yêu cầu gợi ý.
Nếu thời gian này cũ hơn lần gần nhất bạn cập nhật giá trên máy chủ của mình, bạn nên phản hồi bằng thông báo Phản hồi gợi ý chỉ định những khách sạn nào đã thay đổi. Nếu gần đây không có lần tìm nạp thành công nào, giá trị này sẽ được đặt thành một giá trị khoảng thời gian cố định (để tránh các vấn đề nghiêm trọng hơn với những nội dung tồn đọng lớn). Giá trị khoảng thời gian cố định hiện tại là 1000 giây, nhưng giá trị này có thể thay đổi. Để biết thêm thông tin, hãy tham khảo bài viết Thông báo Phản hồi gợi ý. |
Ví dụ
Ví dụ sau đây cho thấy một thông báo Yêu cầu gợi ý:
thông báo Yêu cầu gợi ý
Dưới đây là ví dụ về một thông báo Yêu cầu gợi ý:
<?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>
Phần tử gốc của thông báo Query
. Thông báo Query
là các yêu cầu cập nhật giá hoặc siêu dữ liệu của Google. Thông tin này được dùng với cả chế độ phân phối Chế độ phân phối giá lấy dữ liệu và Giá đã thay đổi.
Có ba loại thông báo Query
:
Cung cấp mức giá hiện tại: Google phản hồi một yêu cầu cụ thể của người dùng và yêu cầu cập nhật giá theo thời gian thực. Khi nhận được tin nhắn
Live pricing query
, đối tác cần phản hồi bằng một thông báo<Transaction>
. Thông báo này có chứa thông tin về giá được yêu cầu trong các phần tử<Result>
.Khi áp dụng giá theo bối cảnh: Google sẽ cập nhật bộ nhớ đệm về giá dựa trên các bối cảnh phổ biến trước đây. Khi nhận được thông báo
With context query
, bạn nên phản hồi bằng một thông báo<Transaction>
chứa thông tin về giá được yêu cầu trong các phần tử<Result>
.Siêu dữ liệu: Google yêu cầu thông tin cập nhật về siêu dữ liệu cho các phòng và Gói dịch vụ phòng của các khách sạn được chỉ định. Khi nhận được thông báo
Metadata Query
, bạn nên phản hồi bằng thông báo<Transaction>
. Thông báo này nêu rõ dữ liệu về phòng và Gói dịch vụ phòng trong các phần tử<PropertyDataSet>
.
Để biết thêm thông tin, hãy tham khảo bài viết Tổng quan về giá đối với các truy vấn về giá và siêu dữ liệu của Gói dịch vụ phòng đối với các truy vấn siêu dữ liệu.
Dưới đây là cú pháp cho 3 loại khác nhau.
Cú pháp
Phần tử <Query>
sử dụng cú pháp sau:
Cung cấp mức giá hiện tại
<?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>
Có bối cảnh
<?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>
Metadata
<HotelInfoProperties>
<Property>property_ID</Property>
...
</HotelInfoProperties>
Thuộc tính
Phần tử <Query>
có thể chứa một thuộc tính: latencySensitive
.
Thuộc tính latencySensitive
là không bắt buộc. Khi được cung cấp và đặt thành true
, thuộc tính này cho biết truy vấn là Live Pricing Query
. Để yêu cầu Google gửi truy vấn bằng thuộc tính latencySensitive
, vui lòng hỏi Giám đốc Quản lý Khách hàng về Kỹ thuật (TAM) của bạn.
Phần tử con
Phần tử <Query>
có các phần tử con sau đây:
Phần tử con | Loại truy vấn | Loại | Nội dung mô tả |
---|---|---|---|
<AffectedNights> | Pricing | integer | Số đêm cho thời gian lưu trú theo phạm vi ngày. Phần tử này chỉ được dùng cho những truy vấn giá của Thời gian lưu trú theo phạm vi ngày sử dụng chế độ Mức giá đã thay đổi. |
<Checkin> | Pricing | Date | Ngày thay đổi giá cụ thể. |
<Context> | Pricing (Live Pricing Queries only) | <Context> | Đối với các Truy vấn giá hiện tại, hãy chỉ định một số tham số dùng để thực hiện truy vấn. Các phần tử con bao gồm:
Bạn có thể sử dụng lặp lại phần tử |
<FirstDate> | Pricing | Date | Ngày bắt đầu của phạm vi các hành trình có áp dụng mức giá này. Phần tử này chỉ dùng cho những truy vấn giá của Phạm vi ngày nhận phòng được dùng với chế độ Mức giá đã thay đổi. |
<HotelInfoProperties> | Metadata | string | Một hoặc nhiều cơ sở lưu trú mà Google muốn cập nhật siêu dữ liệu về phòng và Gói dịch vụ phòng trong thông báo Query về siêu dữ liệu. Phần tử này có thể chứa một hoặc nhiều phần tử <Property> chỉ định mã cơ sở lưu trú khách sạn. |
<LastDate> | Pricing | Date | Ngày kết thúc của phạm vi hành trình có áp dụng mức giá này. Phần tử này chỉ dùng cho các truy vấn giá của Phạm vi ngày nhận phòng dùng với chế độ Lấy dữ liệu + Gợi ý. |
<Nights> | Pricing | integer | Số đêm cho một hành trình cụ thể, tối đa 30 đêm. |
<PropertyList> | Pricing | Object | Một hoặc nhiều mã nhận dạng của khách sạn yêu cầu thông tin cập nhật về giá. Hãy xác định từng khách sạn trong một phần tử <PropertyList> <Property>pid1</Property> <Property>pid2</Property> </PropertyList> |
Ví dụ
Truy vấn giá
Ví dụ sau đây thể hiện một thông báo Truy vấn giá yêu cầu cập nhật giá cho một nhóm khách sạn, có phòng cho 3 đêm và bắt đầu từ ngày 10 tháng 6 năm 2018:
<?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>
Truy vấn về chế độ cung cấp mức giá hiện tại
Ví dụ sau đây cho thấy một Truy vấn giá hiện tại có giới hạn thời gian phản hồi là 500 mili giây:
<?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>
Có truy vấn theo ngữ cảnh
<?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>
Truy vấn siêu dữ liệu
<?xml version="1.0" encoding="UTF-8"?>
<Query>
<HotelInfoProperties>
<Property>pid5</Property>
<Property>pid8</Property>
<Property>pid13</Property>
<Property>pid21</Property>
</HotelInfoProperties>
</Query>
Để xem thêm ví dụ, bao gồm cả truy vấn giá theo phạm vi ngày lưu trú và ngày nhận phòng, hãy xem ví dụ về thông báo Query
.
<Context>
Phần tử <Context>
mô tả thông tin của một Live pricing query
, bao gồm số lượng và loại khách, quốc gia của người dùng và thiết bị của người dùng.
Không bao giờ sử dụng nhiều <Context>
với nhiều quốc gia hoặc thiết bị của người dùng. Khi dùng nhiều <Context>
để truy vấn nhiều mức sức chứa, vui lòng cung cấp mỗi mức giá của số người lưu trú dưới dạng một Gói dịch vụ phòng bổ sung cho cơ sở lưu trú/hành trình tương ứng. Mỗi cơ sở lưu trú/hành trình phải có một khối <Result>
duy nhất có các mức giá cho nhiều mức lưu trú.
Để biết thông tin chi tiết về phản hồi cho truy vấn <Context>
, hãy xem <OccupancyDetails>
.
Cú pháp
Phần tử <Context>
sử dụng cú pháp sau:
Cú pháp
<?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>
Phần tử con
Phần tử <Context>
có các phần tử con sau đây:
Phần tử con | Loại truy vấn | Loại | Nội dung mô tả |
---|---|---|---|
<Occupancy> | Pricing | integer | Xác định tổng số khách. Mặc dù không bắt buộc, nhưng các truy vấn có Lưu ý: |
<OccupancyDetails> | Pricing | Object | Bắt đầu bằng <Occupancy> . Chỉ định khách theo loại, bao gồm:
Mặc dù không bắt buộc, nhưng các truy vấn có Lưu ý: |
<UserCountry> | Pricing | string | Lọc mức giá theo quốc gia nơi người dùng đang ở. Giá trị này là một
mã quốc gia gồm 2 chữ cái như Các truy vấn có |
<UserDevice> | Pricing | string | Lọc giá theo loại thiết bị mà người dùng sử dụng để tìm kiếm. Các loại tệp có thể được thu thập dữ liệu bao gồm:
Các truy vấn có xác định |
Ví dụ
Người trong nhà
Ví dụ sau đây cho thấy một truy vấn Cung cấp mức giá hiện tại cho <Occupancy>
trong <Context>
. Truy vấn Cung cấp mức giá hiện tại dành cho 3 khách là người lớn.
<?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>
Thông tin về số người lưu trú
Ví dụ sau đây cho thấy một truy vấn Cung cấp mức giá hiện tại có <OccupancyDetails>
trong <Context>
.
Truy vấn chế độ Cung cấp mức giá hiện tại dành cho 4 khách, trong đó có 2 trẻ em và đang tìm kiếm một mức giá phù hợp với yêu cầu đặt phòng của khách ở Hoa Kỳ qua thiết bị di động:
<?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>
Nhiều bối cảnh
Ví dụ sau đây cho thấy việc sử dụng phần tử <Context>
bổ sung trong truy vấn Cung cấp mức giá hiện tại.
<?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>