مرحله 5: به‌روزرسانی‌های هم‌زمان API

موجودی سیستم شما در طول روز به دلیل رزروهای جدید، لغو رزروها و تغییرات برنامه از سوی فروشندگان شما در نوسان است. API به‌روزرسانی بلادرنگ، مکانیزمی برای اطلاع‌رسانی به گوگل در مورد این تغییرات در موجودی موجود است. همچنین می‌توانید از به‌روزرسانی‌های بلادرنگ API برای اطلاع‌رسانی به گوگل در مورد تغییراتی که در رزروهای موجود ایجاد می‌شود، استفاده کنید.

به‌روزرسانی‌ها و فیدهای API در لحظه

به‌روزرسانی‌های بلادرنگ API برای اطلاع‌رسانی به گوگل در مورد تغییرات تدریجی در موجودی و رزروها به صورت بلادرنگ استفاده می‌شوند. علاوه بر به‌روزرسانی‌های بلادرنگ API، فیدهای کامل موجودی را روزانه ارسال کنید تا مطمئن شوید که گوگل دقیق‌ترین و به‌روزترین دانش را از موجودی موجود در سیستم شما دارد. فیدهای کامل به عنوان تصویری از وضعیت فعلی موجودی در سیستم شما عمل می‌کنند.

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

API های مورد نیاز برای به‌روزرسانی بلادرنگ

API های به‌روزرسانی بلادرنگ (RTU)
اعلان رزرو	اجباری	هر زمان که تغییری در رزرو ایجاد شد (مثلاً اصلاح یا لغو)، به RTUهای رزرو، اعلان رزرو ارسال کنید.
جایگزینی RTU در دسترس بودن	به صورت مشروط مورد نیاز است[1]	برای ارسال به‌روزرسانی‌ها به موجودی انبار، RTUهای جایگزینی دسته‌ای یا جایگزینی تکی ارسال کنید. انتشار و انعکاس تغییرات ممکن است چند دقیقه طول بکشد.
RTU تجاری	اختیاری	اگر می‌خواهید تغییرات در اطلاعات فروشنده را به صورت آنی اعمال کنید، RTU های فروشنده را ارسال کنید. انتشار و انعکاس تغییرات ممکن است چندین ساعت طول بکشد.
خدمات RTU	اختیاری	اگر می‌خواهید اطلاعات سرویس را به صورت بلادرنگ تغییر دهید، RTU سرویس ارسال کنید. یک مورد استفاده رایج این است که اگر قیمت سرویس در طول روز به طور چشمگیری نوسان داشته باشد، پیاده‌سازی RTU سرویس برای جلوگیری از شکست سفارش به دلیل عدم تطابق قیمت توصیه می‌شود. انتشار و انعکاس تغییرات ممکن است چندین ساعت طول بکشد.

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

جایگزینی API RTU در دسترس بودن

از API مربوط به Availability Replace برای ارائه به‌روزرسانی‌های مربوط به دسترس‌پذیری در موارد استفاده زیر استفاده کنید:

• یک کاربر در سیستم شما رزرو انجام می‌دهد، بنابراین جایگاه خالی دیگر در دسترس نیست.
• یک فروشنده، موجودی خود را در سیستم شما تغییر می‌دهد.
• کاربر از طریق گوگل رزرو انجام می‌دهد، بنابراین زمان خالی دیگر در دسترس نیست.
• رزروی که از طریق گوگل انجام شده باشد، مثلاً مستقیماً توسط فروشنده لغو می‌شود. شما باید رزرو و همچنین موجودی را به‌روزرسانی کنید، زیرا جایگاه اصلی اکنون دوباره در دسترس است.
• فراخوانی BatchAvailabilityLookup از سرور رزرو، موجودی را برمی‌گرداند که با موجودی واقعی مطابقت ندارد.

برای اطلاعات بیشتر، به منابع زیر مراجعه کنید:

• آموزش: نحوه ساختاردهی به‌روزرسانی‌های بلادرنگ
• مثال کلاینت جاوا برای به‌روزرسانی‌های بلادرنگ با استفاده از فراخوانی‌های RESTful
• صفحه مرجع API به‌روزرسانی موجودی

API اعلان رزرو RTU

APIهای اعلان رزرو، گوگل را از به‌روزرسانی‌های رزروهای موجود مطلع می‌کنند. وقتی به‌روزرسانی‌ای در مورد لغو رزرو ارسال می‌کنید، فقط اطلاعات ضروری را در درخواست با پارامتر کوئری updateMask ارسال کنید. در اینجا مثالی آورده شده است:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

دسترسی به API

ایجاد حساب کاربری سرویس

برای ایجاد یک حساب کاربری سرویس، از تب Credentials در کنسول Google API استفاده کنید. کلید خصوصی را با فرمت JSON در مکانی امن ذخیره کنید. هنگام ایجاد حساب، می‌توانید نقش را روی "مالک" تنظیم کنید.

احراز هویت APIهای رزرو نقشه‌ها

پس از ایجاد یک حساب کاربری سرویس، API های زیر را احراز هویت کنید:

• API رزرو نقشه گوگل
• API رزرو نقشه گوگل (توسعه‌یافته)

برای راهنمای گام به گام نحوه انجام این کار، به آموزش احراز هویت با استفاده از API رزرو نقشه مراجعه کنید.

از فراخوانی‌های RESTful استفاده کنید یا کتابخانه کلاینت را دانلود کنید

توصیه می‌کنیم که فراخوانی‌های RESTful را مستقیماً با JSON به API رزرو نقشه‌ها انجام دهید. برای اطلاعات بیشتر، به مستندات REST API مراجعه کنید.

همچنین می‌توانید از کتابخانه‌های کلاینت برای اتصال به API استفاده کنید.

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

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

سند Discovery را دریافت کنید

برای برخی از کتابخانه‌های کلاینت، مانند Ruby، لازم است سند Discovery مربوط به API را که متدها و پارامترهای آن را شرح می‌دهد، دریافت کنید.

برای دریافت سند Discovery از دستور زیر استفاده کنید:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

برای اطلاعات بیشتر در مورد دسترسی به API از طریق Ruby، این لینک‌ها را دنبال کنید: Ruby API Client و Ruby Auth Library .

برقراری تماس‌های مجاز با API

هنگام برقراری تماس با API، به بخش «آماده‌سازی برای برقراری تماس API مجاز» مراجعه کنید تا حساب سرویس خود را با کلید خصوصی و محدوده OAuth زیر تأیید کنید: https://www.googleapis.com/auth/mapsbooking .

سهمیه‌های API

به‌روزرسانی‌های API دارای سهمیه ۱۵۰۰ درخواست در هر ۶۰ ثانیه یا به طور متوسط ​​۲۵ درخواست در ثانیه هستند. وقتی سهمیه از حد مجاز تجاوز کند (که می‌تواند زمانی رخ دهد که شماره صحیح پروژه Google Cloud را در پورتال همکار خود اضافه نکرده باشید)، گوگل با پیام خطای زیر پاسخ می‌دهد:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

برای مدیریت این مشکل، فراخوانی را در فواصل زمانی نمایی بزرگتر تکرار کنید تا زمانی که موفق شود. اگر مرتباً سهمیه را با ReplaceServiceAvailability تمام می‌کنید، برای کاهش تعداد فراخوانی‌های API به BatchReplaceServiceAvailabily بروید. این روش به شما امکان می‌دهد چندین سرویس را در یک فراخوانی API به‌روزرسانی کنید.

سندباکس و نقاط پایانی تولید

شما می‌توانید از طریق API، هم به محیط‌های sandbox و هم به محیط‌های عملیاتی دسترسی داشته باشید. مطمئن شوید که هر دو API را در پروژه Google Cloud خود فعال کرده‌اید. هر دوی این APIها از یک محدوده استفاده می‌کنند، اما نقاط پایانی متفاوتی دارند.

نقطه پایانی تولید: https://mapsbooking.googleapis.com/

نقطه پایانی سندباکس: https://partnerdev-mapsbooking.googleapis.com/

مثال زیر در جاوا نحوه‌ی تغییر نقاط پایانی را نشان می‌دهد:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()