RTUها در درجه اول برای بهروزرسانیهایی در نظر گرفته شدهاند که نمیتوانید پیشبینی کنید، مانند بسته شدنهای اضطراری یا ابردادههایی که به صورت دورهای تغییر میکنند (مانند ETAها). اگر نیازی نیست تغییر شما فوراً منعکس شود، میتوانید به جای آن از دریافت فید دستهای استفاده کنید. بهروزرسانیهای بلادرنگ در کمتر از پنج دقیقه پردازش میشوند.
راهاندازی پلتفرم ابری گوگل
- راهاندازی یک پروژه GCP. برای دسترسی به RTU API به یک پروژه GCP نیاز است.
- به سردبیر دسترسی food-support@google.com بدهید
- شماره پروژه GCP را به Google POC خود اطلاع دهید. پروژه GCP شما باید با حساب Actions Center شما مرتبط باشد تا بهروزرسانیهای بلادرنگ کار کنند.
- فعال کردن API رزرو نقشه:
- در GCP به APIs & Services > Library بروید.
- عبارت «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 برای دسترسی به APIهای گوگل » توضیح داده شده است، انجام دهید.
تنظیم حساب کاربری سرویس
برای ارسال درخواستهای HTTPS احراز هویت شده به APIهای گوگل، مانند API بهروزرسانیهای بلادرنگ، به یک حساب کاربری سرویس نیاز دارید.
برای تنظیم حساب کاربری سرویس، موارد زیر را انجام دهید:
- به کنسول پلتفرم ابری گوگل دسترسی پیدا کنید.
- حساب شما در مرکز عملیات همچنین یک پروژه Google Cloud مرتبط با خود دارد. اگر قبلاً انتخاب نشده است، آن پروژه را انتخاب کنید.
- در منوی سمت چپ روی حسابهای سرویس (Service Accounts) کلیک کنید.
- روی ایجاد حساب کاربری سرویس کلیک کنید.
- یک نام برای حساب سرویس وارد کنید و روی ایجاد کلیک کنید.
- برای انتخاب یک نقش ، پروژه > ویرایشگر را انتخاب کنید.
- روی ادامه کلیک کنید.
- اختیاری: کاربران را اضافه کنید تا به آنها دسترسی به حساب سرویس داده شود و روی «انجام شد» کلیک کنید.
- برای حساب سرویسی که ایجاد کردهاید، روی «بیشتر » > «ایجاد کلید» کلیک کنید.
- JSON را به عنوان فرمت انتخاب کنید و روی Create کلیک کنید.
- پس از ایجاد جفت کلید عمومی/خصوصی جدید، آن را روی دستگاه خود دانلود کنید.
کار با API
API بهروزرسانیهای بلادرنگ از دو نوع عملیات پشتیبانی میکند: بهروزرسانی و حذف. افزودن موجودیتهای جدید از طریق API بهروزرسانی بلادرنگ پشتیبانی نمیشود. اگر چندین بهروزرسانی را در یک درخواست API واحد بگنجانید، بهروزرسانیهای بلادرنگ را میتوان دستهبندی کرد. میتوانید تا ۱۰۰۰ بهروزرسانی را در یک فراخوانی API واحد دستهبندی کنید. توصیه میکنیم در صورت امکان از یک رویکرد مبتنی بر ماشه برای ارسال بهروزرسانیها از طریق RTU استفاده کنید (یعنی به محض تغییر دادهها در سیستم شما، یک بهروزرسانی بلادرنگ به گوگل ارسال شود) نه یک رویکرد مبتنی بر فرکانس (یعنی هر X دقیقه سیستم خود را برای یافتن تغییرات اسکن کنید).
API بهروزرسانیهای بلادرنگ در هر دو محیط sandbox و production عمل میکند. محیط sandbox برای آزمایش درخواستهای API و محیط production برای بهروزرسانی محتوای قابل مشاهده برای کاربران سفارشدهنده End-to-End استفاده میشود.
- سندباکس -
partnerdev-mapsbooking.googleapis.com - تولید -
mapsbooking.googleapis.com
نقاط پایانی
API بهروزرسانیهای بلادرنگ، دو نقطه پایانی را برای مدیریت درخواستهای ورودی برای بهروزرسانی موجودی در اختیار قرار میدهد:
- بهروزرسانی -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush - حذف -
/v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDeleteحذف
پارامتر PARTNER_ID را میتوانید در مرکز عملیات در صفحه حساب و کاربران ، همانطور که در تصویر زیر نشان داده شده است، پیدا کنید.
با در نظر گرفتن مقدار ۱۰۰۰۰۰۰۱ به عنوان PARTNER_ID به عنوان مثال از تصویر بالا، URL های کامل برای ارسال درخواست های API در محیط sandbox و محیط عملیاتی مانند مثال های زیر خواهند بود.
بهروزرسانی سندباکس
https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush
حذف در محیط سندباکس
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
حذف تولید
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: مطمئن شوید که مهر زمانیِ تولید موجودیت در سیستمهای backend شما درج شده باشد. اگر این فیلد درج نشده باشد، روی زمانی تنظیم میشود که گوگل درخواست را دریافت میکند. هنگام بهروزرسانی یک موجودیت از طریق درخواستbatchPush، فیلدgeneration_timestampبرای نسخهبندی موجودیت استفاده میشود. قالب مورد انتظار مقادیر زمانی را در طرح موجودی رابطهای مشاهده کنید.
- حجم بدنهی بار داده نباید از ۵ مگابایت بیشتر باشد.
- برای کاهش اندازه، فضاهای خالی را حذف کنید.
- در یک درخواست
batchPushمیتوان تا ۱۰۰۰ بهروزرسانی انجام داد.
مثالها
بهروزرسانی زمان تقریبی رسیدن به مقصد (ETA)
فرض کنید نیاز فوری دارید که زمان تقریبی رسیدن (ETA) یک سرویس تحویل را از ۳۰-۶۰ دقیقه به ۶۰-۹۰ دقیقه بهروزرسانی کنید. بهروزرسانی شما باید شامل 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 payload باشد که حاوی شناسه موجودیتی است که میخواهید حذف کنید.
توجه: مطمئن شوید که فیدهای داده روزانه شما شامل هرگونه تغییری که از طریق 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 بهروزرسانی بلادرنگ انجام میشود:
- سطح درخواست - این اعتبارسنجیها بررسی میکنند که آیا محتوای درخواست (payload) از طرحواره (schema) پیروی میکند و هر
proto_recordشامل فیلدهایidوtypeاست. این بررسیها همزمان هستند و نتایج در بدنه پاسخ API بازگردانده میشوند. کد پاسخ ۲۰۰ و بدنه خالی JSON{}به این معنی است که این اعتبارسنجیها پذیرفته شدهاند و موجودیتهای موجود در آن درخواست برای پردازش در صف قرار گرفتهاند. کد پاسخ غیر ۲۰۰ به این معنی است که یک یا چند مورد از این اعتبارسنجیها با شکست مواجه شدهاند و کل درخواست (از جمله تمام موجودیتهای موجود در محتوای درخواست) رد میشود. به عنوان مثال، اگر یک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." } ] }
- سطح موجودیت : هر موجودیت (proto_record) در payload بر اساس طرحواره اعتبارسنجی میشود. مشکلاتی که در این مرحله از اعتبارسنجی رخ میدهند در پاسخ API گزارش نمیشوند. آنها فقط در داشبورد گزارشدهی RTU در مرکز اقدامات گزارش میشوند.
نکته: کد پاسخ ۲۰۰ به این معنی نیست که همه موجودیتها با موفقیت دریافت شدهاند.
سهمیههای API
بهروزرسانیهای API در لحظه، سهمیهای معادل ۱۵۰۰ درخواست در هر ۶۰ ثانیه یا به طور متوسط ۲۵ درخواست در ثانیه دارند. وقتی از سهمیه تعیینشده تجاوز شود، گوگل با پیام خطای زیر پاسخ میدهد:
{
"error": {
"code": 429,
"message": "Insufficient tokens for quota ...",
"status": "RESOURCE_EXHAUSTED",
"details": [...]
}
}برای مدیریت این مشکل، فراخوانی را در فواصل زمانی نمایی بزرگتر تکرار کنید تا زمانی که موفق شود. اگر مرتباً سهمیه را تمام میکنید، گنجاندن موجودیتهای بیشتر در یک درخواست API را در نظر بگیرید. میتوانید تا ۱۰۰۰ موجودیت را در یک فراخوانی API بگنجانید.
زمان پردازش، بهروزرسانیهای بلادرنگ
یک موجودیت که از طریق بهروزرسانی بلادرنگ بهروزرسانی میشود، در عرض ۵ دقیقه پردازش میشود.