پیام های پرس و جو

پیام‌های جستجو، درخواست‌هایی از گوگل برای قیمت‌گذاری یا به‌روزرسانی‌های فراداده هستند. آن‌ها با هر دو حالت تحویل Pull و Changed Pricing استفاده می‌شوند.

عنصر ریشه پیام‌های کوئری، <Query> است.

ساختار پیام کوئری به نوع پیام بستگی دارد:

  • قیمت‌گذاری: گوگل یک پیام جستجو ارسال می‌کند که درخواست به‌روزرسانی قیمت‌ها را برای هتل‌های مشخص‌شده دارد.

  • فراداده: گوگل یک پیام جستجو ارسال می‌کند که داده‌هایی درباره اتاق و اطلاعات بسته در هتل‌های مشخص‌شده را درخواست می‌کند.

شما در طول پیکربندی اولیه خود، نقطه پایانی که گوگل برای پیام‌های پرس‌وجو و پرس‌وجوهای قیمت‌گذاری زنده استفاده می‌کند را تعریف می‌کنید. برای اطلاعات بیشتر، با مدیر حساب فنی (TAM) خود تماس بگیرید.

گوگل یک پیام کوئری را به عنوان یک درخواست HTTP POST ارسال می‌کند که هدر Content-Type آن روی "application/xml" و هدر User-Agent آن روی Google-HotelAdsPrices تنظیم شده است. استثنای این قانون در طول آزمایش دستی ادغام نقطه پایانی قیمت از طریق Google-TravelAds-Live رخ می‌دهد. این کوئری‌های نمونه ممکن است حاوی هدر User-Agent باشند یا نباشند.

قالب‌بندی دقیق پیام‌های پرس‌وجو را می‌توان در مرجع XML پرس‌وجو یافت.

پیام‌های استعلام قیمت

پیام‌های استعلام قیمت، ترکیب ملک و مسیر سفری را که برای آن قیمت ارائه می‌دهید، مشخص می‌کنند.

وقتی سرور شما یک پیام «درخواست قیمت‌گذاری» دریافت می‌کند، باید با یک پیام <Transaction> که حاوی اطلاعات قیمت‌گذاری درخواستی است، پاسخ دهد.

برای اطلاعات بیشتر، به «مرور کلی قیمت‌ها» مراجعه کنید.

سه نوع خاص از پیام‌های پرس‌وجو وجود دارد:

  1. قیمت‌گذاری زنده: در صورت فعال بودن، درخواست‌ها زمانی ارسال می‌شوند که کاربر به طور فعال در حال مشاهده قیمت‌ها برای ملک یا ترکیب برنامه سفر مشخص شده است و شما یک بازه زمانی مشخص برای پاسخگویی دارید.

  2. با زمینه: در صورت فعال بودن، توصیه‌های زمینه کاربر در هر پرسشی که گوگل برای شما ارسال می‌کند، گنجانده می‌شود و این توصیه‌ها منعکس‌کننده رایج‌ترین انواع کاربرانی هستند که به دنبال ملک یا ترکیب‌های مسیر داده شده می‌گردند. پیروی از این توصیه‌ها ممکن است کارایی پاسخ‌های شما را افزایش دهد.

  3. فراداده: این درخواستی برای جزئیات مربوط به اتاق‌ها و بسته‌های مربوط به ملک‌های مشخص شده است.

استعلام قیمت زنده

درخواست‌های قیمت‌گذاری زنده، درخواست‌هایی از گوگل برای به‌روزرسانی‌های قیمت در لحظه در پاسخ به جستجوهای کاربر هستند. گوگل درخواست جستجویی را از کاربر برای ترکیب هتل یا برنامه سفر دریافت می‌کند و از آنجا که داده‌های قیمت‌گذاری در دسترس یا به‌روز نیستند، گوگل در زمان جستجو از شما درخواست به‌روزرسانی قیمت می‌کند. با درخواست قیمت‌گذاری زنده، گوگل تلاش می‌کند قیمتی را دریافت کرده و آن را در نتایج جستجو در زمان جستجو نمایش دهد.

تمام درخواست‌های استعلام قیمت زنده دارای محدودیت زمانی پاسخ هستند که معمولاً تا ۴۰۰۰ میلی‌ثانیه است. این محدودیت در درخواست استعلام قیمت زنده مشخص شده است. اگر پاسخی در این محدودیت زمانی ارائه نشود، منجر به از دست رفتن مشارکت برای آن فرصت خاص می‌شود. با این حال، توصیه می‌کنیم در هر صورت قیمتی ارائه دهید تا بتوان آن را ذخیره کرد و برای فرصت‌های آینده استفاده کرد. اتصال برای پاسخ به مدت ده دقیقه یا طبق آنچه در پیکربندی همکار مشخص شده است، باز می‌ماند.

پرس‌وجوهای قیمت‌گذاری زنده همچنین وابسته به متن هستند و می‌توانند قیمت‌ها را برای پارامترهای زیر بازیابی کنند: کشور کاربر، نوع دستگاه، تعداد مهمانان و اینکه آیا این مهمانان بزرگسال هستند یا کودک. با پرس‌وجوهای قیمت‌گذاری زنده، می‌توانید قیمت‌های به‌روزتری را نشان دهید که با آنچه مشتری جستجو کرده است مطابقت دارند.

درخواست‌های قیمت‌گذاری زنده به عنوان یک مکانیسم ثانویه برای به‌روزرسانی قیمت‌ها در نظر گرفته شده‌اند. مکانیسم اصلی برای تغییر قیمت هنوز از طریق قیمت‌گذاری Pull یا Changed است. درخواست‌های قیمت‌گذاری زنده به پر کردن شکاف‌هایی که گوگل برای ترکیب هتل‌ها یا برنامه‌های سفر قیمت ندارد، کمک می‌کند.

قوانین استفاده از استعلام قیمت زنده

  • هیچ داده ذخیره‌شده‌ای برای برنامه سفر داده‌شده وجود ندارد زیرا برنامه سفر درخواست‌شده غیرمعمول است، مثلاً تاریخ‌ها خیلی دور هستند یا هتل خیلی به‌ندرت جستجو می‌شود.

  • تاریخ درخواستی، تاریخ غیر پیش‌فرض است.

توجه: تاریخ‌های پیش‌فرض برای استعلام قیمت زنده واجد شرایط نیستند. استعلام قیمت زنده فقط برای تاریخ‌های غیر پیش‌فرض درخواست می‌شود.

گوگل معمولاً نتایج قیمت‌گذاری زنده را ذخیره می‌کند تا دوباره همان هتل یا برنامه سفر درخواست نشود. این موتور جستجو می‌تواند هم ترکیب‌های تک هتل یا برنامه سفر و هم ترکیب‌های چند هتل یا برنامه سفر را درخواست کند.

ویژگی قیمت‌گذاری زنده با متن، گوگل را قادر می‌سازد تا درخواست‌های قیمت‌گذاری زنده خاصی را بر اساس نوع دستگاه کاربر، کشوری که از آن جستجو می‌کند و تعداد ساکنین از جمله کودکان ارسال کند. هم پیام جستجو و هم پیام تراکنش گسترش می‌یابند تا عنصر <Context> را که پارامترهای جستجو را تعریف می‌کند، در بر بگیرند. قیمت‌های دریافتی از جستجوهای قیمت‌گذاری زنده با متن، اگر قیمت برای یک ظرفیت خاص باشد، می‌توانند به عنوان یک بسته اتاق و اگر برای یک کشور یا دستگاه کاربر باشد، به عنوان یک نرخ مشروط ذخیره شوند.

با کوئری‌های متنی

پرس‌وجوهای Context درخواست‌های منظمی برای به‌روزرسانی پایگاه داده ما برای ترکیب‌های مشخص‌شده‌ی ویژگی یا مسیر سفر هستند. آن‌ها شامل فهرستی از زمینه‌های کاربری هستند که برای آن ترکیب‌ها محبوب هستند. اگر از نرخ‌های شرطی استفاده شود، ارسال نرخ برای همه زمینه‌های کاربری ممکن ممکن است گران باشد، بنابراین می‌توانید از این فهرست زمینه‌های کاربری برای محدود کردن پاسخ خود استفاده کنید. قیمت‌های بازگشتی فقط برای زمینه‌های کاربری مشخص‌شده، اکثریت قریب به اتفاق پرس‌وجوهای مرتبط کاربر را پوشش می‌دهد.

اگر علاقه‌مند به دریافت پرسش‌های «با زمینه» هستید، با مدیر حساب فنی (TAM) خود تماس بگیرید. آن‌ها می‌توانند تأیید کنند که شما آماده دریافت چنین پیام‌هایی هستید و سپس تنظیمات پیکربندی را برای شروع ارسال زمینه‌های کاربر در پرسش‌ها به شما انجام دهند.

پیام‌های جستجوی فراداده

پیام‌های پرس‌وجوی فراداده حاوی جزئیاتی در مورد اطلاعات اتاق و بسته برای ویژگی‌های مشخص‌شده هستند.

وقتی یک پیام پرس‌وجوی فراداده دریافت می‌کنید، باید با یک پیام <Transaction> پاسخ دهید که قیمت‌گذاری برای ویژگی‌های درخواستی در عناصر <Result> را مشخص می‌کند.

برای اطلاعات بیشتر، به تعریف فراداده‌های اتاق و بسته مراجعه کنید.

نمونه‌های پیام پرس‌وجو

این بخش چندین نمونه از پیام‌های پرس‌وجوی قیمت‌گذاری و یک پیام پرس‌وجوی فراداده را نشان می‌دهد. مثال‌های بیشتر در مرجع XML پرس‌وجو یافت می‌شوند.

نمونه برنامه سفر

مثال زیر یک <Query> قیمت‌گذاری را نشان می‌دهد که به‌روزرسانی قیمت را برای ۴ هتل، با ۳ شب اقامت و شروع از ۲۳ مه ۲۰۲۳ درخواست می‌کند:

<?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>

این مثال درخواست به‌روزرسانی قیمت‌ها برای هر هتل را می‌دهد:

5/23/18 - 6/26/18

مثال استعلام قیمت زنده

مثال زیر یک پرس و جوی قیمت گذاری زنده با محدودیت زمان پاسخ ۵۰۰ میلی ثانیه را نشان می‌دهد:

<?xml version="1.0" encoding="UTF-8"?>
<Query latencySensitive="true">
<!-- Note that the latencySensitive attribute is not present by default but can
     be configured to be displayed, on request, by Google. This attribute is only
     displayed for a Live Pricing Query request -->
  <Checkin>2023-05-23</Checkin>
  <Nights>2</Nights>
  <DeadlineMs>500</DeadlineMs>
<!-- The deadline represents the timeframe by which a response will need to be
     received by. This element is only displayed for a Live Pricing Query request -->
  <PropertyList>
    <Property>6781291</Property>
  </PropertyList>
<!-- Note that Context tags are potentially repeatable -->
  <Context>
<!-- The total number of guests occupying the room (adults+children) -->
    <Occupancy>3</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
<!-- In this example one of the 3 guests is a 5yr old child -->
      <Children>
        <Child age="5"/>
      </Children>
    </OccupancyDetails>
<!-- The user was located in the US when this search was made -->
    <UserCountry>US</UserCountry>
<!-- The user was searching from a mobile device at the time of search -->
    <UserDevice>mobile</UserDevice>
  </Context>
</Query>

این مثال قیمت یک هتل را درخواست می‌کند:

6/23/23 - 6/25/23

نمونه‌ای از پاسخ پیام تراکنش به این پرس‌وجو را می‌توانید در مرجع XML قیمت‌گذاری و موجودی اتاق (تراکنش‌ها) پیدا کنید.

با مثال‌های کوئری متنی

مثال‌های زیر برای کوئری With Context هستند:

پرس و جوی پایه با متن 

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>2023-05-23</Checkin>
  <Nights>2</Nights>
  <PropertyContextList>
    <PropertyContext>
      <Property>8675309</Property>
      <!-- In the future, 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>
  <Checkin>2025-07-10</Checkin>
  <Nights>2</Nights>
  <PropertyContextList>
    <PropertyContext>
      <Property>8675309</Property>
      <Context>
        <UserCountry>US</UserCountry>
      </Context>
      <Occupancy>3</Occupancy>
      <OccupancyDetails>
        <NumAdults>2</NumAdults>
        <Children>
          <Child age="7"/>
        </Children>
      </OccupancyDetails>
    </PropertyContext>
    <PropertyContext>
      <Property>8675310</Property>
      <Context>
        <UserCountry>GB</UserCountry>
      </Context>
      <Occupancy>1</Occupancy>
      <OccupancyDetails>
        <NumAdults>1</NumAdults>
      </OccupancyDetails>
    </PropertyContext>
  </PropertyContextList>
</Query>

با استفاده از کوئری‌های Context، فقط زمینه کشور کاربر مشخص می‌شود. در آینده، چنین کوئری‌هایی ممکن است دستگاه کاربر را نیز مشخص کنند.

محدوده‌های تاریخ ورود

اگر از قیمت‌گذاری تغییر یافته استفاده می‌کنید، ساختار پیام پرس‌وجو به نوع راهنمایی که برای محدوده‌های تاریخ ورود، برنامه‌های سفر دقیق یا برنامه‌های سفر با محدوده مشخص استفاده می‌کنید، بستگی دارد. برای اطلاعات بیشتر در مورد هر یک از این انواع راهنمایی، به پیام‌های پاسخ راهنمایی مراجعه کنید.

مثال زیر یک پیام <Query> قیمت‌گذاری را برای محدوده‌های تاریخ ورود نشان می‌دهد:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <FirstDate>2023-05-23</FirstDate>
  <LastDate>2023-05-26</LastDate>
  <Nights>3</Nights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

این مثال درخواست به‌روزرسانی قیمت‌ها را برای اقامت‌های زیر (برای هر هتل) ارائه می‌دهد:

5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/24/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23

اقامت‌های دور از دسترس

مثال زیر یک پیام <Query> قیمت‌گذاری برای اقامت‌های محدود را نشان می‌دهد:

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <FirstDate>2023-05-23</FirstDate>
  <LastDate>2023-05-26</LastDate>
  <AffectedNights>3</AffectedNights>
  <PropertyList>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </PropertyList>
</Query>

این مثال درخواست به‌روزرسانی قیمت‌ها برای هر هتل را می‌دهد: 

5/23/23 - 5/24/23
5/23/23 - 5/25/23
5/23/23 - 5/26/23
5/24/23 - 5/25/23
5/24/23 - 5/26/23
5/24/23 - 5/27/23
5/25/23 - 5/26/23
5/25/23 - 5/27/23
5/25/23 - 5/28/23

به علاوه اقامت‌هایی که قبل از شب مورد نظر شروع شده‌اند (اما شامل می‌شوند): 

5/20/23 - 5/23/23
5/21/23 - 5/23/23
5/21/23 - 5/24/23
5/22/23 - 5/23/23
5/22/23 - 5/24/23
5/22/23 - 5/25/23

پیام جستجوی فراداده

مثال زیر یک پیام <Query> را نشان می‌دهد که درخواست به‌روزرسانی فراداده برای اتاق و اطلاعات بسته برای چندین ویژگی را دارد: 

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <HotelInfoProperties>
    <Property>pid5</Property>
    <Property>pid8</Property>
    <Property>pid13</Property>
    <Property>pid21</Property>
  </HotelInfoProperties>
</Query>

شما به این نوع پیام پرس‌وجو با یک پیام تراکنش پاسخ می‌دهید که فراداده‌های اتاق و بسته را تعریف می‌کند. برای اطلاعات بیشتر، به تعریف فراداده‌های اتاق و بسته مراجعه کنید.