این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

پرس و جو & نکات مرجع XML

این بخش مرجعی برای پیام‌های درخواست راهنمایی (Hint Request) ، پیام‌های پاسخ راهنمایی (Hint Response) و پیام‌های پرس‌وجو (Query) مبتنی بر XML گوگل ارائه می‌دهد.

`<Hint>` (پیام پاسخ راهنمایی)

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

یک پیام Hint Response باید فقط هتل‌هایی را مشخص کند که قیمت‌های آنها از آخرین باری که گوگل یک Hint Response موفق از سرورهای شما دریافت کرده است، تغییر کرده است.

پیام‌های 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 را نشان می‌دهد:

<!-- Check-in Ranges Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>hotel_ID</Property>
    [...]

    <!-- Required -->
    <FirstDate>first_checkin_date</FirstDate>
    <!-- Required -->
    <LastDate>last_checkin_date</LastDate>
  </Item>
  ...
</Hint>

اقامت‌های محدود

کد زیر سینتکس مربوط به «ماندن در بازه‌های زمانی» در یک پیام پاسخ Hint را نشان می‌دهد:

<!-- Ranged Stay Hint Response -->
<?xml version="1.0" encoding="UTF-8"?>
<Hint>
  <Item>
    <!-- At least one is required -->
    <Property>1458700</Property>
    <Property>5418701</Property>
    <StaysIncludingRange>
      <!-- Required -->
      <FirstDate>2025-04-28</FirstDate>
      <!-- Optional -->
      <LastDate>2025-04-29</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	همه	شناسه یک هتل، با استفاده از همان شناسه فهرست هتل . تعداد عناصر `<Property>` که می‌توانید در یک بلوک `<Item>` مشخص کنید، با نوع پیام پاسخ Hint تعیین می‌شود: برنامه‌های سفر دقیق: تا ۱۰۰ هتل. محدوده‌های ورود: اگر `<MultipleItineraries>` در پیام `<QueryControl>` روی `"checkin_range"` تنظیم کنید، بیش از یک محدوده وجود خواهد داشت. ماندگاری در محدوده‌ی زمانی مشخص: اگر `<MultipleItineraries>` در پیام `<QueryControl>` روی `"affected_dates"` تنظیم کنید، بیش از یک مورد.
<Stay>	Required	Object	برنامه‌های دقیق سفر	یک ظرف برای عناصر `<CheckinDate>` و `<LengthOfStay>` در یک پیام دقیق پاسخ Hint برای مسیر سفر. هر `<Item>` می‌تواند فقط شامل یک `<Stay>` باشد.
<StaysIncludingRange>	Required	Object	برنامه‌های سفر متنوع	یک ظرف برای عناصر `<FirstDate>` و `<LastDate>` در یک پیام پاسخ راهنمایی اقامتی با بازه زمانی مشخص.

مثال‌ها

برنامه‌های دقیق سفر

مثال زیر چندین مسیر سفر را برای یک ویژگی واحد، یک پیام پاسخ Hint، تعریف می‌کند:

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

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

مثال زیر دو هتل را مشخص می‌کند که قیمت آنها تغییر کرده و باید دوباره دریافت شوند. گوگل تمام برنامه‌های سفر بین ۳ تا ۶ جولای را برای هتل‌های ۱۲۳۴۵ و ۶۷۸۹۰ دریافت می‌کند:

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

اقامت‌های محدود

مثال زیر دو کاربرد مختلف از اقامت‌های متنوع را نشان می‌دهد، یکی برای طیفی از شب‌ها و دیگری برای یک شب:

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

برای هر یک از این مثال‌ها، گوگل با یک <Query> پاسخ می‌دهد و شما باید با یک <Transaction> که شامل به‌روزرسانی‌های قیمت برای هتل‌ها/برنامه‌های سفر مشخص شده است، پاسخ دهید.

`<HintRequest>`

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

اگر هرگونه تغییر قیمتی وجود داشته باشد، گوگل یک <Query> ارسال می‌کند که داده‌های قیمت‌گذاری به‌روز شده را برای هتل‌ها و برنامه‌های سفر مشخص شده دریافت می‌کند.

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

نحو

عنصر <HintRequest> از سینتکس زیر استفاده می‌کند:

نحو

<?xml version="1.0" encoding="UTF-8"?>
<HintRequest>
  <LastFetchTime>last_fetch_time</LastFetchTime>
</HintRequest>

ویژگی‌ها

عنصر <HintRequest> هیچ ویژگی (attribute) ندارد.

عناصر فرزند

عنصر <HintRequest> دارای عناصر فرزند زیر است:

عنصر فرزند	نوع	توضیحات
<LastFetchTime>	DateTime	آخرین باری که گوگل موفق شد یک پیام پاسخ راهنمایی به یک پیام درخواست راهنمایی ارسال کند. اگر این زمان قدیمی‌تر از آخرین باری است که قیمت‌ها را در سرور خود به‌روزرسانی کرده‌اید، باید با یک پیام Hint Response که مشخص می‌کند کدام هتل‌ها تغییر کرده‌اند، پاسخ دهید. اگر اخیراً هیچ واکشی موفقیت‌آمیزی انجام نشده باشد، این مقدار روی یک بازه زمانی ثابت تنظیم می‌شود (برای جلوگیری از مشکلات جدی‌تر ناشی از حجم زیاد داده‌ها). مقدار بازه زمانی ثابت فعلی ۱۰۰۰ ثانیه است، اما ممکن است تغییر کند. برای اطلاعات بیشتر، به پیام‌های پاسخ اشاره‌ای مراجعه کنید.

عنصر فرزند

نوع

توضیحات

DateTime

آخرین باری که گوگل موفق شد یک پیام پاسخ راهنمایی به یک پیام درخواست راهنمایی ارسال کند.

اگر این زمان قدیمی‌تر از آخرین باری است که قیمت‌ها را در سرور خود به‌روزرسانی کرده‌اید، باید با یک پیام Hint Response که مشخص می‌کند کدام هتل‌ها تغییر کرده‌اند، پاسخ دهید.

اگر اخیراً هیچ واکشی موفقیت‌آمیزی انجام نشده باشد، این مقدار روی یک بازه زمانی ثابت تنظیم می‌شود (برای جلوگیری از مشکلات جدی‌تر ناشی از حجم زیاد داده‌ها). مقدار بازه زمانی ثابت فعلی ۱۰۰۰ ثانیه است، اما ممکن است تغییر کند.

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

مثال‌ها

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

پیام درخواست راهنمایی

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

<?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 درخواست‌هایی از گوگل برای قیمت‌گذاری یا به‌روزرسانی‌های فراداده هستند. آن‌ها با هر دو حالت تحویل قیمت‌گذاری Pull و Changed استفاده می‌شوند.

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

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

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

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

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

قیمت‌گذاری زنده: گوگل به درخواست یک کاربر خاص پاسخ می‌دهد و درخواست به‌روزرسانی قیمت در لحظه را دارد. وقتی شرکا یک پیام Live pricing query دریافت می‌کنند، باید با یک پیام <Transaction> که حاوی اطلاعات قیمت‌گذاری درخواستی در عناصر <Result> است، پاسخ دهند.
نکته کلیدی: به دلیل تجربه جستجوی جدید ، جستجوی زنده برای کاربران منطقه اقتصادی اروپا (EEA) دسترسی محدودی دارد.
قیمت‌گذاری با متن: گوگل حافظه پنهان قیمت خود را بر اساس متن‌هایی که از نظر تاریخی محبوب هستند، به‌روزرسانی می‌کند. وقتی یک پیام With Context query دریافت می‌کنید، باید با یک پیام <Transaction> که حاوی اطلاعات قیمت‌گذاری درخواستی در عناصر <Result> است، پاسخ دهید.
- با کوئری‌های متنی برای یک واحد مسکونی
  هنگام ارائه نرخ‌ها در پاسخ به پرس‌وجوهای With Context، فقط باید نرخ مربوط به زمینه مشخص‌شده را ارسال کنید. اشغال نرخ پایه به حداقل ۲ ساکن نیاز دارد، بنابراین اگر یک ساکن در نرخ پایه ارسال شود، نادیده گرفته می‌شود و همچنان به عنوان اشغال مضاعف در نظر گرفته می‌شود. در این حالت، باید نرخ پایه را به عنوان غیرقابل دسترس ارسال کنید و از نرخ تو در تو در داخل اشغال تکی استفاده کنید. به مثال پاسخ With Context مراجعه کنید. می‌توانید با تنظیم ویژگی mergeable روی "true" از Changed Pricing with Context برای ادغام نرخ‌ها استفاده کنید. اطلاعات بیشتر .
- قیمت‌گذاری (که قبلاً با نکات نمایش داده می‌شد) با متن تغییر کرد
  وقتی در پاسخ به یک کوئری Changed Pricing with Context، یک پیام <Transaction> ارسال می‌کنید، گوگل آن را به عنوان جایگزینی کامل برای اطلاعات قیمت‌گذاری و در دسترس بودن برای یک هتل یا برنامه سفر مشخص در نظر می‌گیرد و تمام نرخ‌های مرتبط با زمینه از پاسخ حذف شده و از حافظه پنهان حذف می‌شوند.
  برای جلوگیری از رونویسی، باید ویژگی mergeable را در عنصر <Result> در پیام <Transaction> روی "true" تنظیم کنید. گوگل نرخ‌ها را با نرخ‌های ذخیره‌شده‌ی موجود برای زمینه‌ی ارائه شده در پاسخ اضافه می‌کند. اگر از ویژگی mergeable استفاده نمی‌کنید، باید تمام نرخ‌ها را برای تمام زمینه‌های قابل اجرا در پاسخ ارسال کنید.
- پرس و جوی قیمت زنده با متن
  پرس‌وجوی قیمت‌گذاری زنده با Context به طور پیش‌فرض رفتار ویژگی قابل ادغام را دارد، بنابراین تنظیم این ویژگی الزامی نیست. شما فقط باید نرخ(های) مربوط به context(های) خاصی را که گوگل درخواست کرده است، در صورتی که همه contextهای دیگر ثابت بمانند، ارسال کنید. اگر contextهای دیگر تغییر کرده باشند، باید صریحاً تغییرات را برای آن contextها ارسال کنید؛ در غیر این صورت، نرخ‌های جدید در حافظه پنهان گوگل به‌روزرسانی نمی‌شوند.
  نکته کلیدی: قیمت‌گذاری تغییر یافته با متن به طور پیش‌فرض بازنویسی می‌شود؛ پرس‌وجوی قیمت‌گذاری زنده با متن به طور پیش‌فرض ادغام می‌شود.
فراداده: گوگل به‌روزرسانی‌های فراداده را برای اتاق‌ها و بسته‌های اتاق هتل‌های مشخص‌شده درخواست می‌کند. وقتی یک پیام Metadata Query دریافت می‌کنید، باید با یک پیام <Transaction> پاسخ دهید که داده‌های مربوط به اتاق‌ها و بسته‌های اتاق را در عناصر <PropertyDataSet> مشخص می‌کند. برای اطلاعات بیشتر، به فراداده بسته اتاق مراجعه کنید.

نحو

عنصر <Query> از سینتکس زیر استفاده می‌کند:

استعلام قیمت

<?xml version="1.0" encoding="UTF-8"?>
<Query>
  <Checkin>YYYY-MM-DD</Checkin>
  <Nights>number_of_nights</Nights>
  <PropertyList>
    <Property>hotel_id</Property>
    ...
  </PropertyList>
</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 است. برای اینکه گوگل پرس‌وجوهایی با ویژگی latencySensitive ارسال کند، با مدیر حساب فنی (TAM) خود تماس بگیرید.

عناصر فرزند

عنصر <Query> دارای عناصر فرزند زیر است:

عنصر فرزند	نوع پرس و جو	نوع	توضیحات
<AffectedNights>	Pricing	integer	تعداد شب‌ها برای اقامت در بازه‌های زمانی مختلف. این عنصر فقط برای درخواست‌های قیمت‌گذاری اقامت در بازه‌های زمانی مختلف که با قیمت‌گذاری تغییر یافته استفاده می‌شوند، استفاده می‌شود.
<Checkin>	Pricing	Date	تاریخ‌های تغییر قیمت خاص.
<Context>	Pricing (Live Pricing Queries only)	<Context>	برای پرس‌وجوهای قیمت‌گذاری زنده، پارامترهای خاصی را مشخص می‌کند که پرس‌وجو تحت آنها انجام می‌شود. عناصر فرزند شامل موارد زیر هستند: `<Occupancy>` : تعداد کل مهمانان `<OccupancyDetails>` : نوع مهمانان، مانند بزرگسالان یا کودکان `<UserCountry>` : کشوری که کاربر در آن قرار دارد `<UserDevice>` : نوع دستگاهی که مهمان برای جستجوی هتل استفاده کرده است، مانند `"mobile` "، " `tablet` " یا " `desktop` ". عنصر `<Context>` می‌تواند در یک درخواست واحد تکرار شود و امکان پرس‌وجو برای موقعیت‌های مختلف را فراهم کند. برای مشاهده فهرستی از عناصر فرزند، نحو و مثال‌ها به `<Context>` مراجعه کنید.
<FirstDate>	Pricing	Date	تاریخ شروع برای طیف وسیعی از برنامه‌های سفر که قیمت‌گذاری برای آنها اعمال می‌شود. این عنصر فقط برای پرس‌وجوهای قیمت‌گذاری محدوده تاریخ ورود که با قیمت‌گذاری تغییر یافته استفاده می‌شوند، استفاده می‌شود.
<HotelInfoProperties>	Metadata	string	یک یا چند ملک که گوگل می‌خواهد فراداده‌های اتاق و بسته اتاق آنها در یک پیام `Query` فراداده به‌روزرسانی شود. این عنصر می‌تواند شامل یک یا چند عنصر `<Property>` باشد که شناسه‌های ملک هتل را مشخص می‌کنند.
<LastDate>	Pricing	Date	تاریخ پایان برای طیف وسیعی از برنامه‌های سفر که قیمت‌گذاری برای آنها اعمال می‌شود. این عنصر فقط برای پرس‌وجوهای قیمت‌گذاری محدوده تاریخ ورود که با Pull + Hints استفاده می‌شوند، استفاده می‌شود.
<Nights>	Pricing	integer	تعداد شب‌های اقامت برای یک برنامه سفر خاص، حداکثر تا ۳۰ شب.
<PropertyList>	Pricing	Object	یک یا چند شناسه برای هتلی که نیاز به به‌روزرسانی قیمت‌ها دارد. هر هتل را در یک عنصر `<Property>` تعریف کنید. مقدار، رشته‌ای است که با شناسه هتل در فهرست هتل‌های شما مطابقت دارد. برای مثال: <PropertyList> <Property>pid1</Property> <Property>pid2</Property> </PropertyList>

مثال‌ها

استعلام قیمت

مثال زیر یک پیام جستجوی قیمت را نشان می‌دهد که درخواست به‌روزرسانی قیمت برای مجموعه‌ای از هتل‌ها را دارد که به مدت ۳ شب در دسترس هستند و از ۲۳ مه ۲۰۲۳ شروع می‌شوند:

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

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

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

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

با پاسخ متنی

مثال زیر نحوه تنظیم نرخ پایه روی unavailable(-1) برای یک ظرفیت واحد و قرار دادن نرخ‌ها در عنصر <Occupancy> را توضیح می‌دهد.

<?xml version="1.0" encoding="UTF-8"
<Transaction id="Wtdj8QoQIWcAAbaTGlIAAAC4" timestamp="2025-11-19T18:36:48Z">
<Result>
  <Property>6781291</Property>
  <Checkin>2026-01-15</Checkin>
  <Nights>1</Nights>
  <!-- Base rate is set to -1 to indicate unavailability for the default (2-person) occupancy -->
  <Baserate currency="USD">-1</Baserate>
  <Tax currency="USD">0</Tax>
  <OtherFees currency="USD">0</OtherFees>
  <Rates>
    <!-- Nested Rate for Single Occupancy -->
    <Rate rate_rule_id="rule-951">
      <Occupancy>1</Occupancy>
      <OccupancyDetails>
        <NumAdults>1</NumAdults>
      </OccupancyDetails>
      <Baserate currency="USD">150.00</Baserate>
      <Tax currency="USD">15.00</Tax>
      <OtherFees currency="USD">5.00</OtherFees>
    </Rate>
  <!-- Other nested rates for different occupancies or room types could be included here if available -->
  </Rates>
</Result>
</Transaction>

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

<?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	تعداد کل مهمانان را مشخص می‌کند. اگرچه اجباری نیست، اما پرس‌وجوهایی با `<Occupancy>` باید منجر به یک پیام تراکنش با Room Bundles مناسب تعریف‌شده برای هر `<Occupancy>` شوند، اما اگر Room Bundles در دسترس نباشند، توصیه می‌شود عنصر `<Occupancy>` را مشخص کنید. توجه: ممکن است `<Occupancy>` همیشه در یک پرس‌وجو ظاهر نشود. در چنین مواردی، باید قیمت تمام واحدهای مسکونی را برگردانید.
<OccupancyDetails>	Pricing	Object	قبل از `<Occupancy>` می‌آید. مهمانان را بر اساس نوع مشخص می‌کند، از جمله: `<NumAdults>` : تعداد مهمانان بزرگسال `<Children>` و `<Child=" age ">` : مشخص می‌کند که کدام مهمانان کودک هستند (معمولاً سن ۰ تا ۱۷ سال) و به صورت اختیاری سن هر کودک را نیز شامل می‌شود. اگرچه اجباری نیست، اما پرس‌وجوهایی با `<OccupancyDetails>` باید منجر به یک پیام تراکنش با Room Bundles مناسب تعریف‌شده برای هر `<Occupancy>` شوند، اما اگر Room Bundles در دسترس نباشند، توصیه می‌شود عنصر `<OccupancyDetails>` را مشخص کنید. نکته: `<OccupancyDetails>` ممکن است همیشه در یک پرس‌وجو ظاهر نشود. در چنین مواردی، باید فرض کنید که همه مهمانان بزرگسال هستند.
<UserCountry>	Pricing	string	نرخ‌ها را بر اساس کشوری که کاربر در آن قرار دارد فیلتر می‌کند. مقدار، یک کد کشور دو حرفی مانند `"US"` برای ایالات متحده یا یک کد منطقه مانند `"EU"` برای "Europe" است. پرس‌وجوهایی که `<UserCountry>` تعریف شده‌اند باید منجر به یک پیام تراکنش با بلوک `<Rates>` مناسب تعریف‌شده برای کشور مورد پرسش شوند.
<UserDevice>	Pricing	string	نرخ‌ها را بر اساس نوع دستگاهی که کاربر از طریق آن جستجو می‌کند، فیلتر می‌کند. مقادیر ممکن: `mobile` `desktop` `tablet` پرس‌وجوهایی که `<UserDevice>` تعریف شده‌اند باید منجر به یک پیام تراکنش با بلوک `<Rates>` مناسب تعریف‌شده برای نوع دستگاه پرس‌وجو شوند.

مثال‌ها

اشغال

مثال زیر یک پرس‌وجوی قیمت‌گذاری زنده برای <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> را نشان می‌دهد. پرس‌وجوی قیمت‌گذاری زنده برای ۴ مهمان است که ۲ نفر از آنها کودک هستند و نرخی را جستجو می‌کند که برای رزرو مهمان آمریکایی از طریق دستگاه تلفن همراه اعمال می‌شود:

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

پرس و جو & نکات مرجع XML با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

<Hint> (پیام پاسخ راهنمایی)

نحو

برنامه‌های دقیق سفر

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

اقامت‌های محدود

ویژگی‌ها

عناصر فرزند

مثال‌ها

برنامه‌های دقیق سفر

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

اقامت‌های محدود

<HintRequest>

نحو

نحو

ویژگی‌ها

عناصر فرزند

مثال‌ها

پیام درخواست راهنمایی

<Query>

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

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

قیمت‌گذاری (که قبلاً با نکات نمایش داده می‌شد) با متن تغییر کرد

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

نحو

استعلام قیمت

قیمت گذاری زنده

با کوئری متنی

فراداده

ویژگی‌ها

عناصر فرزند

مثال‌ها

استعلام قیمت

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

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

با پاسخ متنی

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

<Context>

نحو

نحو

عناصر فرزند

مثال‌ها

اشغال

جزئیات سکونت

زمینه‌های چندگانه

پرس و جو & نکات مرجع XML

`<Hint>` (پیام پاسخ راهنمایی)

`<HintRequest>`

`<Query>`

`<Context>`