בקטע הזה יש חומר עזר להודעות של בקשת רמז על בסיס XML, להודעות רמזים ולהודעות שאילתה.
<Hint>
(הודעת רמז לתשובה)
רכיב הבסיס של הודעת Hint Response. הודעות רמז: מציינות אילו שילובים של מלונות ומלונות צריך לתמחר מחדש. אלה הם התשובה שלכם להודעת רמז מ-Google.
הודעת Hint Response צריכה לציין רק את המלונות שהמחירים שלהם השתנו מאז הפעם האחרונה ש-Google קיבלה תגובת Hint Response מוצלחת מהשרתים שלכם.
בהודעות Hint Response נעשה שימוש באחת מהשיטות הבאות כדי לציין אילו מלונות ותוכניות נסיעה Google צריכה לתמחר מחדש:
מסלולי נסיעה מדויקים: שילוב של תאריך הצ'ק-אין ומשך השהייה.
טווח תאריכי הצ'ק אין: מציין טווח של תאריכי צ'ק אין, החל מתאריך הצ'ק אין הראשון ומסתיים בתאריך הצ'ק אין האחרון.
שהיות בטווח מסוים (או מסלולי נסיעה בטווח טווח)
כל אחת מה-methods האלו דורשת תחביר שונה להודעת Hint Response.
מידע נוסף זמין במאמר בנושא הודעות Hint Response.
תחביר
לרכיב <Hint>
יש תחביר שונה, בהתאם לסוג הודעת Hint Response:
מסלולי נסיעה מדויקים
כך נראה התחביר של מסלולי הנסיעה המדויקים בהודעת Hint Response:
<!-- 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>
טווחי צ'ק-אין
כך נראה התחביר של טווחי הצ'ק-אין בהודעת Hint Response:
<!-- 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>
שהיות לטווח ארוך
כך מוצג התחביר של השהיות בטווח מסוים בהודעת Hint Response:
<!-- 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
בהודעות
<Query>
שנשלחות על סמך הערך הזה של <Hint>
.
רכיבי צאצא
הרכיב <Hint>
כולל את רכיבי הצאצא הבאים:
רכיב צאצא | חובה? | סוג | סוג התגובה לרמז | תיאור |
---|---|---|---|---|
<CheckInDate> | Required | Date | מסלולי נסיעה מדויקים | תאריך הצ'ק אין של מסלול הנסיעה. |
<FirstDate> | Required | Date | טווחי צ'ק-אין ומסלולי נסיעה | התאריך הראשון בטווח התאריכים של טווח הצ'ק-אין או של הודעת 'רמז לשהייה בטווח'. התאריכים כוללים את הזמן. |
<Item> | Required | Object | הכול | מאגר לעדכון המלון/כרטיס הנסיעה. |
<LastDate> | Required* | Date | טווחי צ'ק-אין ומסלולי נסיעה | התאריך האחרון של טווח התאריכים של טווח הצ'ק-אין או של הודעת רמז לשהייה בטווח. התאריכים כוללים את הזמן. * הרכיב הזה הוא אופציונלי לשהיות בטווח זמן. |
<LengthOfStay> | Required | integer | מועדי נסיעה מדויקים | מספר הלילות של מסלול הנסיעה, מבוטא כמספר שלם חיובי. |
<Property> | Required | string | הכול | המזהה של מלון, עם אותו מזהה כמו ברשימת המלונות. מספר רכיבי
|
<Stay> | Required | Object | מסלולי נסיעה מדויקים | קונטיינר של הרכיבים <CheckinDate> ו-<LengthOfStay> בהודעת תגובה מדויקת של מסלול נסיעה. כל <Item> יכול להכיל רק <Stay> יחיד. |
<StaysIncludingRange> | Required | Object | מסלולי נסיעה | קונטיינר של הרכיבים <FirstDate> ו-<LastDate> בהודעת Hint Response לטווח ארוך. |
דוגמאות
מסלולי נסיעה מדויקים
בדוגמה הבאה מוגדרים מספר מסלולי נסיעה לנכס יחיד בהודעת Hint Response:
<!-- 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 מקבלת את כל מסלולי הנסיעה בין 3 ביולי ל-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>
שימו לב שכדי שההודעה של טווח הצ'ק-אין תוכל לציין כמה מאפיינים ב-<Item>
אחד, הערך של <MultipleItineraries>
ב-<QueryControl>
צריך להיות "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>
אחת, הערך של <MultipleItineraries>
ב-<QueryControl>
צריך להיות "affected_dates"
.
לכל אחת מהדוגמאות האלה Google מגיבה עם <Query>
, והתשובה היא <Transaction>
שכוללת עדכוני מחירים למלונות או למסלולי הנסיעה שצוינו.
<HintRequest>
רכיב הבסיס של הודעת בקשה לרמז. Google שולחת לשרת שלכם הודעת Hint Request ומצפה לקבלת תגובה שמפרטת את המלונות והמסלולים שהמחירים שלהם השתנו מאז הפעם האחרונה ש-Google קיבלה תגובת רמז מוצלחת מהשרת.
אם יש שינויים במחירים, Google שולחת את הקוד <Query>
כדי לאחזר את נתוני המחירים המעודכנים של המלונות ומסלולי הנסיעה שצוינו.
למידע נוסף, אפשר לעיין ב-Hint Request Messages.
תחביר
הרכיב <HintRequest>
משתמש בתחביר הבא:
תחביר
<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
<LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>
מאפיינים
לרכיב <HintRequest>
אין מאפיינים.
רכיבי צאצא
הרכיב <HintRequest>
כולל את רכיבי הצאצא הבאים:
רכיב צאצא | סוג | תיאור |
---|---|---|
<LastFetchTime> | DateTime | הפעם האחרונה ש-Google הצליחה לקבל הודעת Hint Response
להודעת Hint Request.
אם המועד הזה חל לפני הפעם האחרונה שבה עדכנתם את המחירים בשרת, עליכם להשיב בהודעת Hint Response ולציין אילו מלונות השתנו. אם לא הייתה שליפה מוצלחת לאחרונה, הערך יוגדר לערך מרווח קבוע (כדי למנוע בעיות חמורות יותר בגלל עיכובים גדולים). הערך הנוכחי של המרווח הקבוע הוא 1,000 שניות, אבל עשוי להשתנות. למידע נוסף, אפשר לעיין ב-Hint Response Messages. |
דוגמאות
בדוגמה הבאה מוצגת הודעת בקשה לרמז:
הודעת בקשה לרמז
הדוגמה הבאה מציגה הודעת Hint Request:
<?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>
.
למידע נוסף, ראו סקירה כללית של התמחור לשאילתות תמחור, והמטא-נתונים של חבילת החדרים בנוגע לשאילתות מטא-נתונים.
התחביר של שלושת הסוגים השונים מתואר בהמשך.
תחביר
הרכיב <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 של המטא-נתונים. הרכיב הזה
יכול להכיל רכיב <Property> אחד או יותר
שמציינים את המזהים של המלונות. |
<LastDate> | Pricing | Date | תאריך הסיום של טווח מסלולי הנסיעה שעליהם חל התמחור. הרכיב הזה משמש רק לשאילתות תמחור של טווח תאריכים של צ'ק-אין, שנעשה בהן שימוש עם שליפת טיפים ורמזים. |
<Nights> | Pricing | integer | מספר הלילות בתוכנית נסיעה ספציפית, עד 30. |
<PropertyList> | Pricing | Object | אחד או יותר מהמזהים של המלון שצריך לעדכן את המחירים שלו. מגדירים כל מלון ברכיב <PropertyList> <Property>pid1</Property> <Property>pid2</Property> </PropertyList> |
דוגמאות
שאילתת תמחור
בדוגמה הבאה מוצגת הודעת שאילתת תמחור שכוללת בקשה לעדכוני מחירים לקבוצת מלונות, שזמינים ל-3 לילות, והחל מ-10 ביוני 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>
שאילתת תמחור בזמן אמת
בדוגמה הבאה מוצגת שאילתת תמחור בזמן אמת עם מגבלת זמן תגובה של 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 | סינון התעריפים לפי המדינה שבה המשתמש נמצא. הערך הזה הוא
קוד מדינה בן 2 אותיות, כמו שאילתות עם הגדרת |
<UserDevice> | Pricing | string | מסנן התעריפים לפי סוג המכשיר שממנו המשתמש מבצע את החיפוש. ערכים אפשריים:
שאילתות עם הגדרה של |
דוגמאות
נוכחות
בדוגמה הבאה מוצגת שאילתה לתמחור בזמן אמת של <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>
פרטי האורחים
בדוגמה הבאה מוצגת שאילתה לתמחור בזמן אמת עם <OccupancyDetails>
בתוך <Context>
.
השאילתה בנושא תמחור בזמן אמת מיועדת ל-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>