RTUها عمدتاً برای بهروزرسانیهایی هستند که نمیتوانید آنها را پیشبینی کنید، مانند بسته شدن اضطراری، یا ابردادههایی که بهطور دورهای تغییر میکنند (مانند ETA). اگر نیازی نیست تغییر شما فوراً منعکس شود، میتوانید به جای آن از مصرف خوراک دستهای استفاده کنید. به روز رسانی های زمان واقعی در بیش از پنج دقیقه پردازش نمی شوند.
راه اندازی Google Cloud Platform
- راه اندازی یک پروژه GCP برای دسترسی به RTU API به یک پروژه GCP نیاز است.
- به ویرایشگر اجازه دسترسی به food-support@google.com را بدهید
- شماره پروژه GCP را به Google POC خود اطلاع دهید. پروژه GCP شما باید با حساب Actions Center شما مرتبط باشد تا بهروزرسانیهای بیدرنگ کار کنند.
- فعال کردن Maps Booking API:
- در GCP به APIs & Services > Library بروید.
- «Google Maps Booking API» را جستجو کنید.
- نمونه Sandbox ("Google Maps Booking API (Dev)") را پیدا کنید و روی فعال کردن کلیک کنید
- نمونه تولید ("Google Maps Booking API") را پیدا کنید و روی فعال کردن کلیک کنید
- یک حساب سرویس با نقش ویرایشگر در پروژه GCP خود ایجاد کنید. برای جزئیات بیشتر، به تنظیمات حساب سرویس مراجعه کنید.
- اطمینان حاصل کنید که فیدهای دستهای را در محیطی که در آن روی بهروزرسانیهای همزمان کار میکنید آپلود میکنید.
- برای احراز هویت API توصیه می کنیم کتابخانه Google Client را به زبان مورد نظر خود نصب کنید. از «https://www.googleapis.com/auth/mapsbooking» به عنوان محدوده OAuth استفاده کنید. نمونه کدهای موجود در زیر از این کتابخانه ها استفاده می کنند. در غیر این صورت، باید مطابق با استفاده از OAuth 2.0 برای دسترسی به Google API، مبادلات رمز را به صورت دستی انجام دهید.
راه اندازی حساب سرویس
برای درخواستهای HTTPS تأیید شده به APIهای Google، مانند API بهروزرسانیهای همزمان، به یک حساب سرویس نیاز دارید.
برای راهاندازی حساب سرویس، موارد زیر را انجام دهید:
- به کنسول Google Cloud Platform دسترسی پیدا کنید.
- حساب شما در Action Center همچنین دارای یک پروژه Google Cloud مرتبط با آن است. آن پروژه را انتخاب کنید، اگر قبلاً انتخاب نشده است.
- در منوی سمت چپ روی Service Accounts کلیک کنید.
- روی ایجاد حساب سرویس کلیک کنید.
- یک نام برای حساب سرویس وارد کنید و روی ایجاد کلیک کنید.
- برای انتخاب نقش ، پروژه > ویرایشگر را انتخاب کنید.
- روی Continue کلیک کنید.
- اختیاری: کاربران را اضافه کنید تا به آنها اجازه دسترسی به حساب سرویس داده شود و روی انجام شد کلیک کنید.
- روی بیشتر > ایجاد کلید برای حساب سرویسی که ایجاد کردید کلیک کنید.
- JSON را به عنوان قالب انتخاب کنید و روی Create کلیک کنید.
- پس از ایجاد جفت کلید عمومی/خصوصی جدید، آن را در دستگاه خود دانلود کنید.
کار با API
API به روز رسانی بلادرنگ از دو نوع عملیات پشتیبانی می کند: به روز رسانی و حذف. افزودن موجودیتهای جدید از طریق API بهروزرسانی بیدرنگ پشتیبانی نمیشود. اگر چندین بهروزرسانی را در یک درخواست API قرار دهید، بهروزرسانیهای بیدرنگ میتوانند دستهبندی شوند. شما می توانید تا 1000 به روز رسانی را در یک تماس API جمع کنید. توصیه میکنیم از یک رویکرد مبتنی بر ماشه برای ارسال بهروزرسانیها از طریق RTU استفاده کنید (یعنی در صورت تغییر دادهها در سیستم شما، بهروزرسانی بیدرنگ به Google را آغاز کند) به جای رویکرد مبتنی بر فرکانس (یعنی هر X دقیقه سیستم شما را برای تغییرات اسکن کنید) ممکن است.
API به روز رسانی بلادرنگ در هر دو محیط سندباکس و تولید عمل می کند. محیط Sandbox برای آزمایش درخواستهای API و محیط تولید برای بهروزرسانی محتوای قابل مشاهده برای سفارش کاربران End-to-End استفاده میشود.
- Sandbox -
partnerdev-mapsbooking.googleapis.com
- تولید -
mapsbooking.googleapis.com
نقاط پایانی
API بهروزرسانیهای بیدرنگ دو نقطه پایانی را برای رسیدگی به درخواستهای دریافتی برای بهروزرسانی موجودی نشان میدهد:
- به روز رسانی -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
- DELETE -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
پارامتر PARTNER_ID را میتوانید در مرکز اقدامات در صفحه حساب و کاربران پیدا کنید، همانطور که در تصویر زیر نشان داده شده است.
با در نظر گرفتن 10000001 به عنوان مقدار PARTNER_ID به عنوان مثال از تصویر بالا، URL های کامل برای ارسال درخواست های API در جعبه ایمنی و تولید مانند نمونه های زیر خواهند بود.
به روز رسانی سندباکس
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
Sandbox DELETE
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
به روز رسانی تولید
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
تولید DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete
به روز رسانی نهادها
برای بهروزرسانی موجودیهای موجود، از نقطه پایانی بهروزرسانی در درخواست HTTP POST استفاده کنید. هر درخواست POST باید پارامتر 10000001 را به همراه یک بار JSON حاوی موجودی که میخواهید بهروزرسانی کنید، داشته باشد.
توجه: اطمینان حاصل کنید که فیدهای داده روزانه شما حاوی هرگونه تغییری است که از طریق API بهروزرسانیهای همزمان ارسال میشود. در غیر این صورت، اطلاعات شما ممکن است قدیمی یا قدیمی باشد.
بار درخواست به روز رسانی
بدنه درخواست یک شی JSON با لیستی از رکوردها است. هر رکورد مربوط به یک موجودیت در حال به روز رسانی است. شامل قسمت proto_record
و generation_timestamp
است که زمان بهروزرسانی موجودیت را نشان میدهد:
{ "records": [ { "proto_record":"ServiceData PROTO", "generation_timestamp":"UPDATE_TIMESTAMP" } ] }
-
ServiceData PROTO
: ترجمه پروتو یا JSON موجودیت ServiceData که در حال به روز رسانی هستید. -
UPDATE_TIMESTAMP
: مطمئن شوید که مُهر زمانی مربوط به زمان ایجاد موجودیت را در سیستمهای باطن خود لحاظ کنید. اگر این فیلد گنجانده نشود، روی زمانی تنظیم میشود که Google درخواست را دریافت میکند. هنگام بهروزرسانی یک موجودیت از طریق یک درخواستbatchPush
، از فیلدgeneration_timestamp
برای نسخهسازی موجودیت استفاده میشود. قالب مورد انتظار مقادیر زمانی را در طرح موجودی رابطه ای مشاهده کنید.
- حجم بدنه محموله نباید بیش از 5 مگابایت باشد.
- فضاهای سفید را برای کاهش اندازه بردارید.
- میتواند تا 1000 بهروزرسانی در یک درخواست
batchPush
وجود داشته باشد.
مثال ها
یک ETA را به روز کنید
فرض کنید شما نیاز فوری دارید تا ETA یک سرویس تحویل را از 30-60 دقیقه به 60-90 دقیقه به روز کنید. بهروزرسانی شما باید حاوی JSON برای کل موجودیت سرویس باشد.
یک نهاد خدماتی را در نظر بگیرید که به شکل زیر است:
{ "service": { "service_id": "service/entity002", "service_type": "DELIVERY", "parent_entity_id": "entity002", "lead_time": { "min_lead_time_duration": "600s", "max_lead_time_duration": "1800s" }, "action_link_id": "delivery_link/entity002" } }
به روز رسانی بلادرنگ شما توسط HTTP POST به شرح زیر است (بدن درخواست برای خوانایی بسیار چاپ شده است):
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "3600" }, "max_lead_time_duration" : { "seconds": "5400" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }] }
چندین نهاد را به روز کنید
برای بهروزرسانی چندین نهاد رستوران در یک تماس API، چندین رکورد را در قسمت proto_record بدنه درخواست اضافه کنید.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery", "service_type" : "DELIVERY", "parent_entity_id" : "23456", "disabled" : "false", "action_link_id": "delivery_link/entity002", "lead_time" : { "min_lead_time_duration" : { "seconds": "1800" }, "max_lead_time_duration" : { "seconds": "3600" } } } }, "generation_timestamp": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee", "fee_type" : "DELIVERY", "fixed_amount" : { "currency_code" : "USD", "units" : "10", "nanos" : "0" }, "service_ids": ["service/entity002"] } }, "generation_timestamp" : "2023-09-13T17:11:10.750Z" }] }
موجودیت ها را حذف کنید
برای حذف موجودی ها از موجودی خود، از نقطه پایانی DELETE در درخواست HTTP POST استفاده کنید. هر درخواست POST باید شامل پارامتر PARTNER_ID به همراه بار JSON باشد که حاوی شناسه نهادی است که میخواهید حذف کنید.
توجه: اطمینان حاصل کنید که فیدهای داده روزانه شما حاوی هرگونه تغییری است که از طریق API بهروزرسانی بیدرنگ ارسال میشود. در غیر این صورت، مصرف دستهای روزانه تغییرات بلادرنگ شما را بازنویسی میکند.
POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete Host: mapsbooking.googleapis.com Content-Type: application/json { "records": [{ "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "service" : { "service_id" : "23456/delivery" } }, "delete_time": "2023-09-13T17:11:10.750Z" }, { "proto_record": { "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData", "fee" : { "fee_id" : "12345/delivery_fee" } }, "delete_time" : "2023-09-13T17:11:10.750Z" }] }
افزودن موجودیت ها
از بهروزرسانیهای بیدرنگ برای افزودن موجودیتهای جدید استفاده نکنید، زیرا ممکن است منجر به ناهماهنگی دادهها شود. در عوض، از فیدهای دسته ای استفاده کنید.
اعتبارسنجی و کدهای پاسخ API
دو نوع اعتبار سنجی در تماس های API به روز رسانی بلادرنگ انجام می شود:
- Request-level - این اعتبارسنجی ها بررسی می کنند که payload از طرح پیروی می کند و هر
proto_record
حاوی یکid
و فیلدهایtype
است. این بررسی ها همزمان هستند و نتایج در بدنه پاسخ API برگردانده می شوند. یک کد پاسخ 200 و یک متن خالی JSON{}
به این معنی است که این اعتبارسنجیها تصویب شده و موجودیتهای موجود در آن درخواست برای پردازش در صف قرار گرفتند. کد پاسخ غیر 200 به این معنی است که یک یا چند مورد از این اعتبارسنجی ها ناموفق بوده و کل درخواست رد می شود (شامل همه موجودات موجود در بار). به عنوان مثال، اگر یکproto_record
فاقد یک@type
باشد، پاسخ خطای زیر برگردانده میشود:
{ "error": { "code": 400, "message": "Record:{...}", "status": "INVALID_ARGUMENT", "details": [ { "@type": "type.googleapis.com/google.rpc.DebugInfo", "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." } ] }
- Entity-level : هر موجودیت (proto_record) در payload در برابر طرح اعتبارسنجی می شود. مسائلی که در این مرحله از اعتبار سنجی با آن مواجه می شوند در پاسخ API گزارش نمی شوند. آنها فقط در داشبورد گزارش RTU مرکز اقدامات گزارش می شوند.
توجه: کد پاسخ 200 به این معنی نیست که همه نهادها با موفقیت وارد شدند.
سهمیه های API
بهروزرسانیهای بلادرنگ API دارای سهمیه 1500 درخواست در هر 60 ثانیه یا به طور متوسط 25 درخواست در ثانیه هستند. هنگامی که از یک سهمیه فراتر رود، Google با پیام خطای زیر پاسخ می دهد:
{ "error": { "code": 429, "message": "Insufficient tokens for quota ...", "status": "RESOURCE_EXHAUSTED", "details": [...] } }
برای انجام این کار، دوباره تماس را در فواصل زمانی بزرگتر تکرار کنید تا زمانی که موفق شود. اگر به طور منظم سهمیه را تمام می کنید، در نظر بگیرید که موجودیت های بیشتری را در یک درخواست API قرار دهید. می توانید حداکثر 1000 موجودیت را در یک تماس API قرار دهید.
زمان پردازش به روز رسانی های زمان واقعی
موجودی که از طریق به روز رسانی بلادرنگ به روز می شود در 5 دقیقه پردازش می شود.