يوفّر هذا القسم مرجعًا لرسائل طلب التلميح المستنِدة إلى XML من Google ورسائل طلب التلميح ورسائل طلب البحث.
<Hint>
(رسالة الرد على التلميح)
تمثّل هذه السمة العنصر الجذر في رسالة الردّ على التلميح. تحدّد رسائل الردّ على التلميحات مجموعات الفنادق/برامج الرحلات التي يجب إعادة تسعيرها. هذه الرسالة هي ردّك على رسالة لطلب تلميح من Google.
يجب أن تحدّد رسالة "الاستجابة للتلميح" فقط الفنادق التي تغيّرت أسعارها منذ آخر مرة تلقّت فيها Google رد تلميح ناجحًا من الخوادم.
تستخدِم رسائل الردّ على التلميحات إحدى الطرق التالية لتحديد الفنادق وبرامج الرحلات التي يجب على Google إعادة تسعيرها:
برامج الرحلات الدقيقة: تشمل تاريخ تسجيل الوصول ومدة الإقامة.
النطاقات الزمنية لتسجيل الوصول: تحدّد نطاقًا من تواريخ تسجيل الوصول، بدءًا من تاريخ تسجيل الوصول الأول وانتهاءً بتاريخ تسجيل الوصول الأخير.
الإقامات المُصنَّفة (أو برامج رحلات ذات نطاق زمني)
تتطلّب كل طريقة من هذه الطرق بنية مختلفة لرسالة Hint Response.
لمزيد من المعلومات، يمكنك الاطّلاع على مقالة رسائل الرد على التلميح.
البنية
يستخدم العنصر <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
في <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> في رسالة "الردّ على تلميح إقامة نطاق زمني"
|
أمثلة
برامج الرحلات الدقيقة
يحدّد المثال التالي برامج رحلات متعددة لخاصية واحدة، ورسالة "استجابة تلميح":
<!-- 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 رسالة طلب تلميح إلى خادمك، وتتوقّع تلقّي استجابة تحدّد الفنادق وبرامج الرحلات التي تغيّرت أسعارها منذ آخر مرة تلقّت فيها Google ردًّا ناجحًا بشأن التلميح من الخادم.
في حال حدوث أي تغييرات في الأسعار، ترسل Google ملف <Query>
لجلب بيانات الأسعار المعدّلة للفنادق وبرامج الرحلات المُشار إليها.
لمزيد من المعلومات، يُرجى الانتقال إلى مقالة رسائل طلب التلميح.
البنية
يستخدم العنصر <HintRequest>
البنية التالية:
البنية
<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
<LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>
السمات
لا يتضمّن العنصر <HintRequest>
أيّ سمات.
العناصر الفرعية
يحتوي العنصر <HintRequest>
على العناصر الثانوية التالية:
العنصر الفرعي | النوع | الوصف |
---|---|---|
<LastFetchTime> | DateTime | آخر مرة نجح فيها محرّك بحث Google في تلقّي رسالة "رد تلميح" إلى رسالة "طلب تلميح".
إذا كان هذا الوقت أقدم من آخر مرة عدّلت فيها الأسعار على الخادم، عليك الردّ برسالة "رد تلميح" تحدّد الفنادق التي تم تغييرها. إذا لم تكن هناك عملية جلب ناجحة مؤخرًا، سيتم ضبط ذلك على قيمة فاصل زمني ثابت (لتجنُّب حدوث مشاكل أكثر خطورة بسبب قوائم المهام الكبيرة). قيمة الفاصل الزمني الثابت الحالي هي 1000 ثانية، ولكنها عرضة للتغيير. لمزيد من المعلومات، يمكنك الاطّلاع على رسائل الرد على التلميحات. |
أمثلة
يعرض المثال التالي رسالة طلب تلميح:
رسالة طلب التلميح
يعرض المثال التالي رسالة طلب تلميح:
<?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 | عدد الليالي لإقامة متنوّعة. ويُستخدَم هذا العنصر فقط لطلبات تحديد سعر الإقامة في Ranged Stay التي يتم استخدامها مع ميزة "التسعير المتغير". |
<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 | تتم فلترة الأسعار حسب البلد الذي يقيم فيه المستخدم. وتكون القيمة رمز بلد مكوّن من حرفَين، مثل ومن المفترَض أن تؤدي طلبات البحث التي تم تحديد السمة |
<UserDevice> | Pricing | string | فلترة الأسعار حسب نوع الجهاز الذي يبحث المستخدم منه القيم المتاحة:
ومن المفترض أن تؤدي طلبات البحث التي تم تحديد السمة |
أمثلة
تواجد الأفراد في المنزل
يعرض المثال التالي طلب بحث عن السعر في الوقت الفعلي لـ <Occupancy>
ضمن <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>
</Query>
تفاصيل الإشغال
يعرض المثال التالي طلب بحث عن السعر في الوقت الفعلي مع <OccupancyDetails>
ضمن <Context>
.
طلب البحث عن السعر في الوقت الفعلي هو لـ 4 نزلاء، اثنان منهم أطفال، ويطلب سعرًا ينطبق على حجز ضيف في الولايات المتحدة من
جهاز جوّال:
<?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>