سرور شریک

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

قالب درخواست و پاسخ

در ابتدا فقط فرمت‌های JSON پشتیبانی می‌شوند. اگر فرمت‌های درخواست یا پاسخ بیشتری مورد نیاز است، برای بحث در مورد مورد استفاده خود با تیم Travel Transport به آدرس transport-help@google.com تماس بگیرید.

درخواست‌ها با استفاده از روش HTTP POST ارسال می‌شوند و پیام درخواست در بدنه POST قرار می‌گیرد.

توجه داشته باشید که برای وضوح ساختاری، مستندات رابط API به صورت تعاریف پیام Protocol Buffer ارائه شده است و ترجمه تعریف پیام Protocol Buffer به یک شیء JSON توسط نگاشت JSON استاندارد تعریف می‌شود، که از گزینه‌هایی برای انتشار فیلدها با مقادیر پیش‌فرض و استفاده از نام‌های فیلدهای proto به جای نام‌های lowerCamelCase استفاده می‌کند.

احراز هویت

گوگل از احراز هویت HTTP Digest، OAuth 2.0 و احراز هویت گواهی کلاینت پشتیبانی می‌کند (به پیکربندی شریک مراجعه کنید). شریک باید در طول آزمایش API، اعتبارنامه‌های صحیح را در اختیار گوگل قرار دهد:

  • برای خلاصه: نام کاربری و رمز عبور.
  • برای OAuth 2.0: client_id و client_secret.
  • برای گواهی: یک گواهی SSL Client.

کدهای وضعیت و مدیریت خطا

به طور کلی، کدهای وضعیت زیر می‌توانند در پاسخ‌های HTTP بازگردانده شوند:

کد HTTP توضیحات HTTP یادداشت‌ها
2xx باشه خطا نیست؛ در صورت موفقیت برگردانده می‌شود. انتظار می‌رود بدنه پاسخ حاوی یک نتیجه موفقیت‌آمیز (مثلاً TripOptionsResult) باشد، نه یک پاسخ خطا.
۴۰۰ درخواست بد درخواست دریافتی نامعتبر بود. پاسخ‌های خطای مختص به متد باید برای بازگرداندن جزئیات بیشتر خطا در بدنه پاسخ استفاده شوند. HTTP 400 معمولاً فقط در صورتی باید استفاده شود که گوگل خطای فنی مرتکب شده باشد (مثلاً فیلدی در درخواست نامش اشتباه باشد).
۴۰۳ ممنوعه مجوز رد/ممنوع است (تماس‌گیرنده شناخته شده و رد شده است). این پاسخ نباید برای رد شدن‌های ناشی از اتمام منابع استفاده شود (به جای آن برای این خطاها از Too Many Requests استفاده کنید). اگر تماس‌گیرنده قابل شناسایی نباشد، نباید از Forbidden استفاده شود (به جای آن برای این خطاها از Unauthorized استفاده کنید).
۴۰۴ یافت نشد منبع درخواستی یافت نشد. پاسخ‌های خطای مختص به متد باید برای بازگرداندن جزئیات خطای بیشتر در بدنه پاسخ استفاده شوند.
۴۲۹ درخواست‌ها خیلی زیاده مقداری از منابع به اتمام رسیده است، شاید سهمیه هر کاربر.
۵۰۰ خطای سرور داخلی خطاهای داخلی. این بدان معناست که برخی از ثابت‌های مورد انتظار سیستم اصلی، دچار مشکل شده‌اند. این کد خطا برای خطاهای جدی در نظر گرفته شده است و نشان‌دهنده‌ی وجود اشکال در پیاده‌سازی سرور API شریک است.
۵۰۳ سرویس در دسترس نیست سرویس در دسترس نیست. این به احتمال زیاد یک وضعیت گذرا است که با تلاش مجدد با یک backoff قابل اصلاح است.
۵۰۴ مهلت زمانی دروازه مهلت قبل از اتمام عملیات به پایان رسیده است. برای عملیاتی که وضعیت سیستم را تغییر می‌دهند، این خطا ممکن است حتی اگر عملیات با موفقیت انجام شده باشد، بازگردانده شود. به عنوان مثال، پاسخ موفقیت‌آمیز از سرور می‌تواند به اندازه کافی به تأخیر بیفتد تا مهلت منقضی شود.

توجه داشته باشید که برای همه پیش‌شرط‌ها، آرگومان‌های نامعتبر یا خطاهای یافت نشد:

  • باید از پاسخ‌های مختص به متد یا پیام‌های خطای تعریف‌شده در APIها استفاده شود.
  • کد http صحیح باید استفاده شود، همانطور که در کدهای مختص متد مشخص شده است (به عنوان مثال TripOptionsErrorType مراجعه کنید).

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

  • تعیین اینکه آیا می‌توان یک خطا را دوباره امتحان کرد یا خیر
    • SEGMENT_KEY_NOT_FOUND قابل تکرار نیست.
  • اطلاعات قدیمی را اصلاح کنید
    • Unavailable.Reason.CANCELED نشان می‌دهد که تریپ باید حذف شود (توجه داشته باشید که این بخشی از یک پاسخ موفق است)
    • Unavailable.Reason.TEMPORARILY_UNAVAILABLE و همچنین کدهای خطای SEGMENT_KEY_NOT_FOUND ، SUBOPTIMAL_ITINERARY ، BOOKING_WINDOW_NOT_SUPPORTED و TICKETING_PROHIBITED هر قیمتی را که قبلاً دریافت کرده‌ایم از حافظه پنهان حذف می‌کنند.
  • ارائه راهنمایی‌های لازم به کاربران

فهرست فعلی خطاهای مختص به روش ارائه شده در TripOptionsError یک نقطه شروع است. در صورت نیاز به انواع خطای بیشتر، لطفاً با تیم Google Travel Transport تماس بگیرید.

QPS (تعداد پرس‌وجو در ثانیه)

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

تأخیر

درخواست‌ها پس از ۱۰ ثانیه به پایان می‌رسند. هیچ دستورالعمل تأخیر اضافی برای ادغام شرکای بتا وجود نخواهد داشت. با این حال، SLO های تأخیر بیشتر در دستورالعمل‌های کیفیت داده‌های شریک ما تعریف خواهند شد.

ارزها، مالیات‌ها و هزینه‌ها

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

ارز

واحد پول برای قیمت با استفاده از فیلد currency_code مشخص می‌شود که باید یک کد ارزی معتبر ISO 4217 باشد.

مثال 10.25 دلار آمریکا:

{
  "price": {
    "currency_code": "USD",
    "units": 10,
    "nanos": 250000000
  }
}

مالیات و هزینه‌ها

قیمتی که ارائه می‌دهید باید قیمت نهایی و کل قیمتی باشد که کاربر پرداخت خواهد کرد، شامل تمام مالیات‌ها (مانند مالیات بر ارزش افزوده) و هرگونه هزینه اضافی (مانند هزینه‌های رزرو یا کارت پرداخت). می‌توان با استفاده از فیلد تکرارپذیر line_items ، جزئیات کرایه را به صورت اختیاری اضافه کرد. گوگل قیمت کل را به همراه جزئیات کرایه اختیاری به کاربر نمایش می‌دهد.