يوفّر هذا القسم مرجعًا لكل من رسائل طلبات التلميحات ورسائل الاستجابة لطلبات البحث ورسائل طلب البحث المستندة إلى XML من Google.
<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
في <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 في تلقّي رسالة رد تلميح
على رسالة "طلب تلميح".
وإذا كانت هذه المدة أقدم من آخر مرة عدّلت فيها الأسعار على خادمك، عليك الرد برسالة رد تلميح تحدّد الفنادق التي تم تغييرها. إذا لم تكن هناك عملية جلب ناجحة مؤخرًا، سيتم ضبطها على قيمة فاصلة ثابتة (لتجنُّب المشاكل الأكثر خطورة بسبب قوائم المهام الكبيرة). إنّ قيمة الفاصل الزمني الثابتة الحالية هي 1, 000 ثانية، ولكنّها عُرضة للتغيير. لمزيد من المعلومات، يمكنك الاطّلاع على رسائل الرد على التلميحات. |
أمثلة
يعرض المثال التالي رسالة لطلب تلميح:
رسالة لطلب تلميح
يعرض المثال التالي رسالة "طلب تلميح":
<?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 لإجراء تعديلات على الأسعار أو البيانات الوصفية. ويتم استخدامها مع كل من وضعَي التسليم
"لسحب السحب" و"التغيير في السعر" (معروف سابقًا باسم Pull with Hints).
هناك ثلاثة أنواع من رسائل 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 | يؤدي هذا الخيار إلى فلترة الأسعار حسب البلد الذي يقيم فيه المستخدم. وتكون القيمة عبارة عن رمز بلد مكوّن من حرفَين، مثل إنّ طلبات البحث التي تم تحديد |
<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>