يوضّح هذا القسم كيفية إرسال تعديلات حسّاسة للوقت في مستودعك
كياناتك إلى Google. تتيح لك واجهة برمجة التطبيقات لتعديلات الوقت الفعلي إمكانية نشر التعديلات وحذف
العناصر في المستودع التجريبي أو المستودع العلني في الوقت الفعلي تقريبًا.
هذه الوظيفة مخصّصة في المقام الأول للتعديلات التي لا يمكنك توقّعها،
مثل عمليات الإغلاق في حالات الطوارئ أو إزالة عناصر من القائمة أو تعديل سعر أحد عناصر القائمة، والتي يجب أن تظهر بسرعة في واجهة مستخدِم Google. إذا لم يكن عليك تطبيق التغيير
على الفور، يمكنك استخدام ميزة
نقل البيانات المجمّعة بدلاً من ذلك. تتم معالجة التعديلات في الوقت الفعلي في غضون
خمس دقائق كحد أقصى.
المتطلبات الأساسية
يجب استيفاء العناصر التالية قبل تنفيذ ميزة "التعديلات في الوقت الفعلي":
تم تفعيل Maps Booking API:
في Google Cloud Platform، انتقِل إلى APIs & Services (واجهات برمجة التطبيقات والخدمات) > Library (المكتبة).
ابحث عن "Google Maps Booking API".
ابحث عن مثيل Sandbox ("Google Maps Booking API (Dev)") وانقر على
تفعيل.
ابحث عن نسخة الإصدار العلني ("Google Maps Booking API") وانقر على
تفعيل.
يتم إنشاء حساب خدمة بدور المحرِّر في مشروعك على Google Cloud Platform (GCP). لمزيد من التفاصيل، يُرجى الاطّلاع على إعداد الحساب.
يتم استضافة خلاصات بيانات الإصدار العلني أو ميزة "المساحة الرملية" ونقل بياناتها. لمزيد من التفاصيل،
راجِع نقل البيانات المجمّعة.
لمصادقة واجهة برمجة التطبيقات، ننصحك بتثبيت
مكتبة Google Client library بلغتك المفضّلة. استخدِم "https://www.googleapis.com/auth/mapsbooking" كنطاق OAuth. وتستخدم نماذج الرموز البرمجية المضمّنة أدناه هذه المكتبات. بخلاف ذلك،
عليك معالجة عمليات تبادل الرموز المميّزة يدويًا كما هو موضّح في
استخدام بروتوكول OAuth 2.0 للوصول إلى Google APIs.
نظرة عامة
تتيح واجهة برمجة التطبيقات التعديلات في الوقت الفعلي نوعَين من العمليات. العملية الأولى هي
upsert لتعديل العناصر الحالية. أما العملية
الثانية فهي "حذف" لإزالة العناصر من مستودعك. يتم تنفيذ كل من
العمليتين على نطاق من الكيانات المدرَجة في نص الطلب. يمكنك
إجراء تعديلات على ما يصل إلى 1,000 عنصر في طلب واحد من واجهة برمجة التطبيقات. تقبل واجهة برمجة التطبيقات
جميع الطلبات الواردة وتضعها في قائمة انتظار لإجراء المزيد من المعالجة.
لذلك، تتم معالجة طلبات RTU بشكل غير متزامن.
تعمل واجهة برمجة التطبيقات لميزة "التعديلات في الوقت الفعلي" في بيئتين: بيئة المحاكاة والإنتاج.
تُستخدَم بيئة الاختبار التجريبي لاختبار طلبات واجهة برمجة التطبيقات وبيئة الإنتاج لتعديل المحتوى المرئي لمستخدمي ميزة "الطلب من خلال تجربة سلسة". أسماء المضيفين
في كلتا البيئتَين:
وضع الحماية - partnerdev-mapsbooking.googleapis.com
الإنتاج - mapsbooking.googleapis.com
نقاط النهاية
تعرض واجهة برمجة التطبيقات لتعديلات الوقت الفعلي نقطتَي نهاية لمعالجة الطلبات الواردة
لتعديلات المستودع:
يمكن العثور على المَعلمة PARTNER_ID في مركز الإجراءات
المعروضة باسم رقم تعريف الشريك في صفحة الحساب والمستخدِمون، كما هو موضّح في
لقطة الشاشة أدناه.
على سبيل المثال، إذا كانت القيمة PARTNER_ID هي 10000001 من screenshot أعلاه، ستظهر عناوين URL الكاملة لإرسال طلبات واجهة برمجة التطبيقات في بيئة المحاكاة و
الإنتاج على النحو الموضّح في الأمثلة أدناه.
# Production UPSERT
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/owg.v2/record:batchPush
# Production DELETE
https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/owg.v2/record:batchDelete
تعديل الكيانات
لتحديث الكيانات في مستودعك، استخدِم نقطة نهايةUPSERT،
وأرسِل طلبات POST عبر بروتوكول HTTP. يجب أن يتضمّن كل طلب POST المَعلمة
PARTNER_ID بالإضافة إلى الحمولة بتنسيق JSON التي تحتوي على
البيانات المنظَّمة لأي نوع من أنواع الكيانات المدرَجة في مخطّط المستودع.
حمولة طلب Upsert
نص الطلب هو عنصر JSON يحتوي على قائمة بالسجلّات. يتوافق كل سجلّ
مع عنصر يتم تعديله. يتألّف من الحقل data_record
الذي يحتوي على الحمولة الأساسية للكيان بترميز Base64 والحقل generation_timestamp
الذي يشير إلى وقت تعديل الكيان:
BASE_64_ENCODED_ENTITY: سلسلة JSON المُشفَّرة بترميز Base64 للموضوع
يجب أن يكون للكيان JSON الذي تم فك ترميزه البنية نفسها كما في مواصفات الخلاصة، على سبيل المثال:
{"@type":"MenuSection","name":"My Updated Menu Section","menuId":{"@id":"10824","displayOrder":1},"@id":"853705"}
UPDATE_TIMESTAMP: احرص على تضمين الطابع الزمني لوقت إنشاء
العنصر في أنظمة الخلفية. يُستخدَم الطابع الزمني هذا لمحاولة
ضمان ترتيب تعديلات المستودع بشكل صحيح. في حال عدم تضمين هذا الحقل،
سيتم ضبطه على الوقت الذي تتلقّى فيه Google الطلب. عند تعديل
كيان من خلال طلب batchPush، يتم استخدام حقل generation_timestamp
لـ إصدار الكيان. اطّلِع على التنسيق المتوقع
لقيم الوقت في مخطّط المستودع.
يجب أن يستوفي كل طلب تحديث في الوقت الفعلي الشروط التالية:
يجب ألا يتجاوز حجم محتوى الحمولة 5 ميغابايت. على غرار الخلاصات المُجمَّعة، ننصحك بإزالة المسافات البيضاء من أجل تكييف المزيد من البيانات.
يمكن أن يتضمّن طلب batchPush ما يصل إلى 1,000 عنصر.
أمثلة
المثال 1: تعديل مطعم
لنفترض أنّك بحاجة إلى تعديل رقم هاتف مطعم بشكل عاجل. يحتوي
التعديل على ملف JSON للمطعم بأكمله.
لا تستخدِم التعديلات في الوقت الفعلي لإضافة كيانات جديدة لأنّ ذلك قد يؤدي إلى حدوث تناقضات في البيانات. بدلاً من ذلك، استخدِم عملية
الخلاصات المجمّعة كما هو موضّح في مقالة نقل البيانات المجمّعة.
حذف الكيانات
لحذف كيانات من مستودعك، استخدِم DELETEنقطة النهاية وأرسِل طلبات POST عبر بروتوكول HTTP. يجب أن يحتوي كل طلب POST على المَعلمة PARTNER_ID مع الحمولة بتنسيق JSON التي تحتوي على معرّف أيّ عنصر في مستودعك.
حذف الحمولة في الطلب
يتم تنظيم نص طلب الحذف بشكل مشابه ل
طلب التعديل.
وتتضمّن أيضًا قائمة بالسجلّات التي تحتوي على حقلَي data_record وdelete_time:
BASE_64_ENCODED_REFERENCE: سلسلة JSON بترميز Base64 والتي تشير إلى العنصر الذي تتم إزالته يتألّف المرجع فقط
من نوع العنصر والمعرّف، على سبيل المثال تمثيل JSON لمحاولة
الرجوع إلى MenuSection:
{"@type":"MenuSection","@id":"853705"}
DELETE_TIMESTAMP: احرص على تضمين الطابع الزمني لوقت حذف
العنصر في نظامك الداخلي. يُستخدَم الطابع الزمني لتحديد الترتيب الذي سيتم فيه تطبيق عملية الحذف على المستودع.
يمكن أن يتضمّن طلب batchDelete ما يصل إلى 1,000 عنصر.
أمثلة
المثال 1: إزالة كيانَين من MenuItem
لإزالة عنصرَين من القائمة في طلب واحد من واجهة برمجة التطبيقات، سيكون طلب HTTP POST على النحو التالي:
هناك نوعان من عمليات التحقّق التي يتم إجراؤها على طلبات البيانات من واجهة برمجة التطبيقات لتعديل البيانات في الوقت الفعلي:
على مستوى الطلب: تتحقّق عمليات التحقّق هذه من أنّ الحمولة تتبع مخطّط upsert أو delete
، وأنّ كل data_record يحتوي على الحقلين @id و@type.
تكون عمليات التحقّق هذه متزامنة ويتم عرض النتائج في ملف محتوى الردّ من واجهة برمجة التطبيقات. يعني رمز الاستجابة 200 ونص JSON فارغ {} أنّه تم اجتياز عمليات التحقّق هذه وتم وضع الكيانات في هذا الطلب في قائمة الانتظار لمعالجتها. إذا كان رمز الاستجابة مختلفًا عن 200، يعني ذلك أنّه تعذّر إكمال عملية التحقّق من واحد أو أكثر من هذه الخطوات وتم رفض الطلب بالكامل (بما في ذلك جميع العناصر في الحمولة). على سبيل المثال، إذا كان data_record لا يتضمّن
@type، سيتم عرض استجابة الخطأ التالية:
{"error":{"code":400,"message":"Record:{\"@id\":\"2717/86853/DELIVERY\",\"applicableServiceType\":[\"DELIVERY\",\"TAKEOUT\"],\"menuId\":[{\"@id\":\"2717/DELIVERY\",\"displayOrder\":1},{\"@id\":\"2717/TAKEOUT\",\"displayOrder\":2}],\"name\":\"Salad\",\"offeredById\":[\"2717\"]} has following errors: \nThe entity type could not be extracted from the entity value.\n","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:{\"@id\":\"2717/86853/DELIVERY\",\"applicableServiceType\":[\"DELIVERY\",\"TAKEOUT\"],\"menuId\":[{\"@id\":\"2717/DELIVERY\",\"displayOrder\":1},{\"@id\":\"2717/TAKEOUT\",\"displayOrder\":2}],\"name\":\"Salad\",\"offeredById\":[\"2717\"]} has following errors: \nThe entity type could not be extracted from the entity value.\n [google.rpc.error_details_ext] { message: \"Record:{\\\"@id\\\":\\\"2717/86853/DELIVERY\\\",\\\"applicableServiceType\\\":[\\\"DELIVERY\\\",\\\"TAKEOUT\\\"],\\\"menuId\\\":[{\\\"@id\\\":\\\"2717/DELIVERY\\\",\\\"displayOrder\\\":1},{\\\"@id\\\":\\\"2717/TAKEOUT\\\",\\\"displayOrder\\\":2}],\\\"name\\\":\\\"Salad\\\",\\\"offeredById\\\":[\\\"2717\\\"]} has following errors: \\nThe entity type could not be extracted from the entity value.\\n\" }"}]}}
على مستوى الكيان: يتم التحقّق من صحة كلّ عنصر في الحمولة مقارنةً ب
المخطّط العلائقي.
لا يتم تسجيل المشاكل التي تواجهها في هذه المرحلة من عملية التحقّق في استجابة واجهة برمجة التطبيقات. ولا يتم تسجيلها إلّا في لوحة بيانات
إعداد تقارير RTU.
حصص واجهة برمجة التطبيقات
تبلغ حصة تعديلات واجهة برمجة التطبيقات في الوقت الفعلي 1,500 طلب كل 60 ثانية، أو 25
طلبًا في الثانية في المتوسّط. عند تجاوز الحصة، تردّ Google برسالة الخطأ التالية:
لحلّ هذه المشكلة، يُرجى إعادة محاولة إجراء المكالمة مرة أخرى على فترات زمنية أكبر بشكلٍ كبير إلى أن يتم إتمامها بنجاح. إذا كنت تستنفد الحصة بشكل منتظم، ننصحك بتضمين المزيد من الكيانات
في طلب واحد من واجهة برمجة التطبيقات. يمكنك تضمين ما يصل إلى 1,000 عنصر في طلب واحد عبر واجهة برمجة التطبيقات.
عيّنات تعليمات برمجية
في ما يلي بعض النماذج عن كيفية استخدام واجهة برمجة التطبيقات لميزة "التعديل في الوقت الفعلي" بلغات مختلفة. تستخدِم هذه العيّنات مكتبات Google Auth للمصادقة باستخدام
ملف مفتاح حساب الخدمة الذي تم إنشاؤه أثناء
إعداد الحساب.
للحصول على حلول بديلة، يُرجى الرجوع إلى مقالة
استخدام OAuth 2.0 لتطبيقات الخادم إلى الخادم.
ننصحك باستخدام المخطّط المتاح في إنشاء مكتبات العملاء لإنشاء رمز المصدر لأنواع عناصر المستودع والتعديل في الوقت الفعلي.
/* Sample code for Real-time update batchPush implementation. * * Required libraries: * - google-auth-library */const{JWT}=require('google-auth-library');// ACTION REQUIRED: Change this to the path of the service account client secret// file downloaded from the Google Cloud Console.constserviceAccountJson=require('./service-account.json');// ACTION REQUIRED: Change this to your Partner ID received from Google.// The Partner ID is available on the Partner Portal.constPARTNER_ID=1234;constHOST={prod:'https://mapsbooking.googleapis.com',sandbox:'https://partnerdev-mapsbooking.googleapis.com'};// ACTION REQUIRED: Change to 'prod' for productionconstENV='sandbox';// Feed name for Order with Google including the version.constFEED_NAME='owg.v2';// Endpoint urlconsturl=`${HOST[ENV]}/v1alpha/inventory/partners/${PARTNER_ID}/feeds/${FEED_NAME}/record:batchPush`;/** * Send a Real-time update request to update/insert entities */asyncfunctionbatchUpsert(entities){/** * Sign JWT token using private key from service account secret file * provided. The client can be created without providing a service account * secret file by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-nodejs */constclient=newJWT({email:serviceAccountJson.client_email,key:serviceAccountJson.private_key,scopes:['https://www.googleapis.com/auth/mapsbooking'],});constrequest={records:toPushRecords(entities)};constbody=JSON.stringify(request);try{constresponse=awaitclient.request({method:'POST',url,data:body,headers:{'Content-Type':'application/json'}});console.log('request body:',body);console.log('response status:',response.status);console.log('response data:',response.data);// successful response returns '{}'}catch(error){console.log('error:',error);}}/** * Maps array of entities to records for batch push requests */consttoPushRecords=(entities)=>{returnentities.map((entity)=>{// Using dateModified to set generation_timestamp. Defaulting to the// current timestamp for records that do not have dateModified.constgeneration_timestamp=entity.dateModified?entity.dateModified:newDate().toISOString();return{data_record:btoa(JSON.stringify(entity)),generation_timestamp};});};// Call batchUpsert with example entities. dateModified is optional and is// used to hold the actual timestamp when the entity was updated/created.batchUpsert([{'@type':'MenuItemOffer','@id':'6680261','menuItemId':'18931508','price':15.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'},{'@type':'MenuItemOffer','@id':'6680262','menuItemId':'18931509','price':25.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'}]);
"""Sample code for the Real-time update batchPush implementation."""# Required libraries:# - google-authimportbase64importdatetimeimportjsonfromgoogle.auth.transport.requestsimportAuthorizedSessionfromgoogle.oauth2importservice_account# ACTION REQUIRED: Change this to the Partner ID received from Google.# Partner ID is available on the Partner Portal.# https://partnerdash.google.com/apps/reservewithgoogle_PARTNER_ID='1234'# ACTION REQUIRED: Change this to the path of the service account client secret# file downloaded from the Google Cloud Console._SERVICE_ACCOUNT_KEY_JSON_FILE='service-account-creds.json'_HOST_MAP={'sandbox':'https://partnerdev-mapsbooking.googleapis.com','prod':'https://mapsbooking.googleapis.com'}# ACTION REQUIRED: Change to 'prod' for production_ENV='sandbox'# Feed name for Order with Google including the version._FEED_NAME='owg.v2'_ENDPOINT='{}/v1alpha/inventory/partners/{}/feeds/{}/record:batchPush'.format(_HOST_MAP[_ENV],_PARTNER_ID,_FEED_NAME)defbatch_upsert(entities):"""Makes a batchPush request using the Real-time updates REST service. Args: entities: The list of entity objects to update or add. """# Creates credentials by providing a json file. Credentials can also be# provided by implementing Application Default Credentials.# https://googleapis.dev/python/google-auth/latest/user-guide.htmlcredentials=service_account.Credentials.from_service_account_file(_SERVICE_ACCOUNT_KEY_JSON_FILE,scopes=['https://www.googleapis.com/auth/mapsbooking'])authorized_session=AuthorizedSession(credentials)# JSON request objectbatch_request={'records':[create_push_record(x)forxinentities]}response=authorized_session.post(_ENDPOINT,json=batch_request)print('request body:',json.dumps(batch_request))print('response status:',response.status_code)print('response data:',response.text)# successful response returns '{}'defcreate_push_record(entity):"""Creates a record from an entity for batchPush requests. Args: entity: The entity object to create the record from. Returns: The constructed record for the batchPush request payload. """data_bytes=json.dumps(entity).encode('utf-8')base64_bytes=base64.b64encode(data_bytes)# Using dateModified to set generation_timestamp. Defaulting to the# current timestamp for records that do not have dateModified.generation_timestamp=entity.dateModifiedif'dateModified'inentityelsedatetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%fZ')return{'generation_timestamp':generation_timestamp,'data_record':base64_bytes.decode('utf-8')}# Call batch_upsert with example entities. dateModified is optional and is# used to hold the actual timestamp when the entity was updated/created.batch_upsert([{'@type':'MenuItemOffer','@id':'6680261','menuItemId':'18931508','price':15.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'},{'@type':'MenuItemOffer','@id':'6680262','menuItemId':'18931509','price':25.5,'priceCurrency':'USD','applicableServiceType':['DELIVERY','TAKEOUT'],'inventoryLevel':0,'dateModified':'2022-06-19T15:43:50.970Z'}])
تم إنشاء نماذج رمز المصدر للعملاء في الحِزم rtusamples.inventory وrtusamples.realtime من خلال اتّباع الخطوات الواردة في مقالة إنشاء مكتبات العملاء.
/* * Required Libraries: * - JDK >= 11 * - google-auth-library-oauth2-http */packagertusamples;importcom.fasterxml.jackson.core.JsonProcessingException;importcom.fasterxml.jackson.databind.ObjectMapper;importcom.google.auth.oauth2.AccessToken;importcom.google.auth.oauth2.GoogleCredentials;importjava.io.FileInputStream;importjava.io.IOException;importjava.net.URI;importjava.net.http.HttpClient;importjava.net.http.HttpRequest;importjava.net.http.HttpRequest.BodyPublishers;importjava.net.http.HttpResponse;importjava.net.http.HttpResponse.BodyHandlers;importjava.nio.charset.Charset;importjava.time.Clock;importjava.time.OffsetDateTime;importjava.time.format.DateTimeFormatter;importjava.util.ArrayList;importjava.util.Arrays;importjava.util.Base64;importjava.util.List;importjava.util.Optional;importjava.util.stream.Collectors;importrtusamples.inventory.MenuItemOffer;importrtusamples.inventory.MenuItemOfferType;importrtusamples.inventory.ServiceTypeElement;importrtusamples.realtime.BatchPushGenericRecordRequest;importrtusamples.realtime.GenericRecord;/** Sample code for Real-time update batchPush implementation. */publicfinalclassBasicPush{// ACTION REQUIRED: Change this to your Partner ID received from Google. The Partner ID is// available on the Partner Portal.privatestaticfinallongPARTNER_ID=12345678;// ACTION REQUIRED: Change this to the path of the service account client secret file downloaded// from the Google Cloud Console.privatestaticfinalStringJSON_KEY_FULL_PATH="<path to your JSON credentials>/credentials.json";// ACTION REQUIRED: Change this to the endpoint that is needed.privatestaticfinalStringENDPOINT=// "https://partnerdev-mapsbooking.googleapis.com"; // for sandbox"https://mapsbooking.googleapis.com";// for prod// Feed name for Order with Google including the version.privatestaticfinalStringFEED_NAME="owg.v2";privatestaticfinalObjectMapperobjectMapper=newObjectMapper();privatestaticfinalDateTimeFormatterTIMESTAMP_FORMATTER=DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'");privatestaticfinalCharsetUTF_8=Charset.forName("UTF-8");publicstaticvoidmain(String[]args)throwsException{/** * Create credentials from service account secret file. Alternatively, the credentials can be * created by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-java */// GoogleCredentials sourceCredentials =// GoogleCredentials.getApplicationDefault()// .createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// ImpersonatedCredentials credentials =// ImpersonatedCredentials.create(// sourceCredentials,// "fo-test@projectname.iam.gserviceaccount.com",// null,// Arrays.asList("https://www.googleapis.com/auth/mapsbooking"),// 300);GoogleCredentialscredentials=GoogleCredentials.fromStream(newFileInputStream(JSON_KEY_FULL_PATH)).createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// Create example MenuItemOffer entities, dateModified is optional and is used to hold// the actual timestamp when the entity was updated/created.MenuItemOffermenuItemOfferPizza=newMenuItemOffer();menuItemOfferPizza.setID("6680261");menuItemOfferPizza.setType(MenuItemOfferType.MENU_ITEM_OFFER);menuItemOfferPizza.setMenuItemID("18931508");menuItemOfferPizza.setPrice(15.5);menuItemOfferPizza.setPriceCurrency("USD");menuItemOfferPizza.setApplicableServiceType(newServiceTypeElement[]{ServiceTypeElement.TAKEOUT,ServiceTypeElement.DELIVERY});menuItemOfferPizza.setInventoryLevel(0.0);menuItemOfferPizza.setDateModified("2022-10-07T13:00:00.000Z");MenuItemOffermenuItemOfferSalad=newMenuItemOffer();menuItemOfferSalad.setID("6680262");menuItemOfferSalad.setType(MenuItemOfferType.MENU_ITEM_OFFER);menuItemOfferSalad.setMenuItemID("18931509");menuItemOfferSalad.setPrice(25.5);menuItemOfferSalad.setPriceCurrency("USD");menuItemOfferSalad.setApplicableServiceType(newServiceTypeElement[]{ServiceTypeElement.TAKEOUT,ServiceTypeElement.DELIVERY});menuItemOfferSalad.setInventoryLevel(0.0);menuItemOfferSalad.setDateModified("2022-10-07T13:00:00.000Z");// Example array of MenuItemOffer entities to update.List<MenuItemOffer>menuItemOffers=Arrays.asList(menuItemOfferPizza,menuItemOfferSalad);// Create list of GenericRecord from menuItemOffers.List<GenericRecord>menuItemOfferGenericRecords=menuItemOffers.stream().map((menuItemOffer)->
toBatchPushRecord(menuItemOffer,menuItemOffer.getDateModified())).collect(Collectors.toList());// List of records to be updated/created.List<GenericRecord>recordsToBeUpdated=newArrayList<>();// Add list of menuItemOffer generic records.recordsToBeUpdated.addAll(menuItemOfferGenericRecords);// Request object that contains all records.BatchPushGenericRecordRequestbatchPushRequest=newBatchPushGenericRecordRequest();batchPushRequest.setRecords(recordsToBeUpdated.toArray(newGenericRecord[0]));// Execute batchPush request.BasicPushbasicPush=newBasicPush();basicPush.batchPush(batchPushRequest,credentials);}publicvoidbatchPush(BatchPushGenericRecordRequestbatchPushRequest,GoogleCredentialscredentials)throwsIOException{credentials.refreshIfExpired();AccessTokentoken=credentials.getAccessToken();StringrequestBody=objectMapper.writeValueAsString(batchPushRequest);HttpClientclient=HttpClient.newHttpClient();HttpRequestrequest=HttpRequest.newBuilder().uri(URI.create(String.format("%s/v1alpha/inventory/partners/%s/feeds/%s/record:batchPush",ENDPOINT,PARTNER_ID,FEED_NAME))).header("Content-Type","application/json").header("Authorization",String.format("Bearer %s",token.getTokenValue())).POST(BodyPublishers.ofString(requestBody)).build();HttpResponse<String>response=null;try{response=client.send(request,BodyHandlers.ofString());System.out.println("Request body:"+requestBody);System.out.println("Response status:"+response.statusCode());System.out.println("Response body:"+response.body());}catch(IOException|InterruptedExceptione){e.printStackTrace();}}publicstatic<T>GenericRecordtoBatchPushRecord(Tentity,StringdateModified){GenericRecordgenericRecord=newGenericRecord();try{Stringjson=objectMapper.writeValueAsString(entity);genericRecord.setDataRecord(Base64.getEncoder().encodeToString(json.getBytes(UTF_8)));// Using dateModified to set generation_timestamp. Defaulting to the// current timestamp for records that do not have dateModified.StringgenerationTimestamp=Optional.ofNullable(dateModified).orElse(OffsetDateTime.now(Clock.systemUTC()).format(TIMESTAMP_FORMATTER));genericRecord.setGenerationTimestamp(generationTimestamp);}catch(JsonProcessingExceptione){System.out.println(e.getMessage());}returngenericRecord;}}
/* Sample code for Real-time update batchDelete implementation. * * Required libraries: * - google-auth-library */const{JWT}=require('google-auth-library');// ACTION REQUIRED: Change this to the path of the service account client secret// file downloaded from the Google Cloud Console.constserviceAccountJson=require('./service-account.json');// ACTION REQUIRED: Change this to your Partner ID received from Google.// The Partner ID is available on the Partner Portal.constPARTNER_ID=1234;constHOST={prod:'https://mapsbooking.googleapis.com',sandbox:'https://partnerdev-mapsbooking.googleapis.com'};// ACTION REQUIRED: Change to 'prod' for productionconstENV='sandbox';// Feed name for Order with Google including the version.constFEED_NAME='owg.v2';// Endpoint urlconsturl=`${HOST[ENV]}/v1alpha/inventory/partners/${PARTNER_ID}/feeds/${FEED_NAME}/record:batchDelete`;/** * Send a Real-time update request to delete entities */asyncfunctionbatchDelete(entities){try{/** * Sign JWT token using private key from service account secret file * provided. The client can be created without providing a service account * secret file by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-nodejs */constclient=newJWT({email:serviceAccountJson.client_email,key:serviceAccountJson.private_key,scopes:['https://www.googleapis.com/auth/mapsbooking'],});constrequest={records:toDeleteRecords(entities)};constbody=JSON.stringify(request);try{constresponse=awaitclient.request({method:'POST',url,data:body,headers:{'Content-Type':'application/json'}});console.log('request body:',body);console.log('response status:',response.status);console.log('response data:',response.data);// successful response returns '{}'}catch(error){console.log('error:',error);}}/** * Maps array of entities to records for batch delete requests */consttoDeleteRecords=(entities)=>{returnentities.map((entity)=>{// Using dateModified to set delete_time. Defaulting to the current// timestamp for records that do not have dateModified.constdelete_time=entity.dateModified?entity.dateModified:newDate().toISOString();return{data_record:btoa(JSON.stringify(entity)),delete_time};});};// Call batchDelete with example entities. dateModified is optional and is// used to hold the actual timestamp when the entity was deleted.batchDelete([{'@type':'Menu','@id':'853706','dateModified':'2022-06-19T15:43:50.970Z'},{'@type':'Menu','@id':'853705','dateModified':'2022-06-19T15:13:00.280Z'}]);
"""Sample code for the Real-time update batchDelete implementation."""# Required libraries:# - google-authimportbase64importdatetimeimportjsonfromgoogle.auth.transport.requestsimportAuthorizedSessionfromgoogle.oauth2importservice_account# ACTION REQUIRED: Change this to the Partner ID received from Google.# Partner ID is available on the Partner Portal.# https://partnerdash.google.com/apps/reservewithgoogle_PARTNER_ID='1234'# ACTION REQUIRED: Change this to the path of the service account client secret# file downloaded from the Google Cloud Console._SERVICE_ACCOUNT_KEY_JSON_FILE='service-account-creds.json'_HOST_MAP={'sandbox':'https://partnerdev-mapsbooking.googleapis.com','prod':'https://mapsbooking.googleapis.com'}# ACTION REQUIRED: Change to 'prod' for production_ENV='sandbox'# Feed name for Order with Google including the version._FEED_NAME='owg.v2'_ENDPOINT='{}/v1alpha/inventory/partners/{}/feeds/{}/record:batchDelete'.format(_HOST_MAP[_ENV],_PARTNER_ID,_FEED_NAME)defbatch_delete(entities):"""Makes a batch delete request using the Real-time updates REST service. Args: entities: The list of entity objects to delete. """# Creates credentials by providing a json file. Credentials can also be# provided by implementing Application Default Credentials.# https://googleapis.dev/python/google-auth/latest/user-guide.htmlcredentials=service_account.Credentials.from_service_account_file(_SERVICE_ACCOUNT_KEY_JSON_FILE,scopes=['https://www.googleapis.com/auth/mapsbooking'])authorized_session=AuthorizedSession(credentials)# JSON request objectbatch_request={'records':[create_delete_record(x)forxinentities]}response=authorized_session.post(_ENDPOINT,json=batch_request)print('request body:',json.dumps(batch_request))print('response status:',response.status_code)print('response data:',response.text)# successful response returns '{}'defcreate_delete_record(entity):"""Creates a record from an entity for batchDelete requests. Args: entity: The entity object to create the record from. Returns: The constructed record for the batchDelete request payload. """data_bytes=json.dumps(entity).encode('utf-8')base64_bytes=base64.b64encode(data_bytes)# Using dateModified to set delete_time. Defaulting to the current# timestamp for records that do not have dateModified.delete_time=entity.dateModifiedif'dateModified'inentityelsedatetime.datetime.now().strftime('%Y-%m-%dT%H:%M:%S.%fZ')return{'delete_time':delete_time,'data_record':base64_bytes.decode('utf-8')}# Call batch_delete with example entities. dateModified is optional and is# used to hold the actual timestamp when the entity was deleted.batch_delete([{'@type':'Menu','@id':'853706','dateModified':'2022-06-19T13:10:00.000Z'},{'@type':'Menu','@id':'853705','dateModified':'2022-06-19T13:30:10.000Z'}])
تم إنشاء نماذج رمز المصدر للعميل في الحِزم rtusamples.inventory وrtusamples.realtime من خلال اتّباع الخطوات الواردة في مقالة إنشاء مكتبات العميل.
/* * Required Libraries: * - JDK >= 11 * - google-auth-library-oauth2-http */packagertusamples;importcom.fasterxml.jackson.core.JsonProcessingException;importcom.fasterxml.jackson.databind.ObjectMapper;importcom.google.auth.oauth2.AccessToken;importcom.google.auth.oauth2.GoogleCredentials;importjava.io.FileInputStream;importjava.io.IOException;importjava.net.URI;importjava.net.http.HttpClient;importjava.net.http.HttpRequest;importjava.net.http.HttpRequest.BodyPublishers;importjava.net.http.HttpResponse;importjava.net.http.HttpResponse.BodyHandlers;importjava.nio.charset.Charset;importjava.time.Clock;importjava.time.OffsetDateTime;importjava.time.format.DateTimeFormatter;importjava.util.ArrayList;importjava.util.Arrays;importjava.util.Base64;importjava.util.List;importjava.util.Optional;importjava.util.stream.Collectors;importrtusamples.inventory.Menu;importrtusamples.inventory.MenuType;importrtusamples.realtime.BatchDeleteGenericRecordsRequest;importrtusamples.realtime.GenericDeleteRecord;/** Sample code for the Real-time update batchDelete implementation. */publicfinalclassBasicDelete{// ACTION REQUIRED: Change this to your Partner ID received from Google. The Partner ID is// available on the Partner Portal.privatestaticfinallongPARTNER_ID=123456789;// ACTION REQUIRED: Change this to the path of the service account client secret file downloaded// from the Google Cloud Console.privatestaticfinalStringJSON_KEY_FULL_PATH="<path to your JSON credentials>/credentials.json";// ACTION REQUIRED: Change this to the endpoint that is needed.privatestaticfinalStringENDPOINT="https://partnerdev-mapsbooking.googleapis.com";// for sandbox// "https://mapsbooking.googleapis.com" // for prod// Feed name for Order with Google including the version.privatestaticfinalStringFEED_NAME="owg.v2";privatestaticfinalObjectMapperobjectMapper=newObjectMapper();privatestaticfinalDateTimeFormatterTIMESTAMP_FORMATTER=DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'");privatestaticfinalCharsetUTF_8=Charset.forName("UTF-8");publicstaticvoidmain(String[]args)throwsException{/** * Create credentials from service account secret file. Alternatively, the credentials can be * created by implementing Application Default Credentials. * https://github.com/googleapis/google-auth-library-java */// GoogleCredentials sourceCredentials =// GoogleCredentials.getApplicationDefault()// .createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// ImpersonatedCredentials credentials =// ImpersonatedCredentials.create(// sourceCredentials,// "fo-test@projectname.iam.gserviceaccount.com",// null,// Arrays.asList("https://www.googleapis.com/auth/mapsbooking"),// 300);GoogleCredentialscredentials=GoogleCredentials.fromStream(newFileInputStream(JSON_KEY_FULL_PATH)).createScoped(Arrays.asList("https://www.googleapis.com/auth/mapsbooking"));// Create example Menu entities, dateModified is optional and is used to hold// the actual timestamp when the entity was deleted.MenumenuLunch=newMenu();menuLunch.setID("853705");menuLunch.setType(MenuType.MENU);menuLunch.setDateModified("2022-09-19T13:10:00.000Z");MenumenuDinner=newMenu();menuDinner.setID("853706");menuDinner.setType(MenuType.MENU);menuDinner.setDateModified("2022-09-19T13:13:10.000Z");// Example array of Menu entities to update.List<Menu>menus=Arrays.asList(menuLunch,menuDinner);// Create list of GenericDeleteRecord from menus.List<GenericDeleteRecord>menuGenericDeleteRecords=menus.stream().map((menu)->toBatchDeleteRecord(menu,menu.getDateModified())).collect(Collectors.toList());// List of records to be deleted.List<GenericDeleteRecord>recordsToBeDeleted=newArrayList<>();// Add list of menu generic records.recordsToBeDeleted.addAll(menuGenericDeleteRecords);// Request object that contains all records.BatchDeleteGenericRecordsRequestbatchDeleteRequest=newBatchDeleteGenericRecordsRequest();batchDeleteRequest.setRecords(recordsToBeDeleted.toArray(newGenericDeleteRecord[0]));// Execute batchDelete request.BasicDeletebasicDelete=newBasicDelete();basicDelete.batchDelete(batchDeleteRequest,credentials);}publicvoidbatchDelete(BatchDeleteGenericRecordsRequestbatchDeleteRequest,GoogleCredentialscredentials)throwsIOException{credentials.refreshIfExpired();AccessTokentoken=credentials.getAccessToken();StringrequestBody=objectMapper.writeValueAsString(batchDeleteRequest);HttpClientclient=HttpClient.newHttpClient();HttpRequestrequest=HttpRequest.newBuilder().uri(URI.create(String.format("%s/v1alpha/inventory/partners/%s/feeds/%s/record:batchDelete",ENDPOINT,PARTNER_ID,FEED_NAME))).header("Content-Type","application/json").header("Authorization",String.format("Bearer %s",token.getTokenValue())).POST(BodyPublishers.ofString(requestBody)).build();HttpResponse<String>response=null;try{response=client.send(request,BodyHandlers.ofString());System.out.println("Request body:"+requestBody);System.out.println("Response status:"+response.statusCode());System.out.println("Response body:"+response.body());}catch(IOException|InterruptedExceptione){e.printStackTrace();}}publicstatic<T>GenericDeleteRecordtoBatchDeleteRecord(Tentity,StringdateModified){GenericDeleteRecordgenericRecord=newGenericDeleteRecord();try{Stringjson=objectMapper.writeValueAsString(entity);genericRecord.setDataRecord(Base64.getEncoder().encodeToString(json.getBytes(UTF_8)));// Using dateModified to set delete_time. Defaulting to the current// timestamp for records that do not have dateModified.StringdeleteTime=Optional.ofNullable(dateModified).orElse(OffsetDateTime.now(Clock.systemUTC()).format(TIMESTAMP_FORMATTER));genericRecord.setDeleteTime(deleteTime);}catch(JsonProcessingExceptione){System.out.println(e.getMessage());}returngenericRecord;}}
حالات الاستخدام
في ما يلي أمثلة على حالات الاستخدام التي تتضمن تعديلات في الوقت الفعلي وتعديلات على الخلاصات المجمّعة،
والمحتوى على مستوى عالٍ في طلب البيانات من واجهة برمجة التطبيقات:
السيناريو
العنصر المطلوب تعديله
الوصف والتأثيرات
إيقاف خدمة
Service
إذا كنت بحاجة إلى إيقاف خدمة لسبب غير متوقَّع
التعديلات في الوقت الفعلي: عدِّل عنصر Service في
السؤال عن طريق ضبط سمة isDisabled على true،
مع إبقاء السمات الأخرى كما هي.
الخلاصات الكاملة: احرص على تعديل الكيان من الخلاصات الكاملة
لضبط isDisabled على true قبل
عملية الجلب التالية التي تجريها Google، وإلا ستتم إعادة تفعيل الكيان.
سلعة معيّنة غير متوفّرة
MenuItemOffer
التعديلات في الوقت الفعلي: أرسِل عنصر MenuItemOffer
المُغلف مع ضبط inventoryLevel على 0 لMenuItem
المحدَّد، وبدون تغيير أي بيانات أخرى.
تغيير في سعر عنصر قائمة
MenuItemOffer
التعديلات في الوقت الفعلي: أرسِل عنصر MenuItemOffer
المحفوظ في عنصر آخر مع ضبط price على السعر المعدَّل لMenuItem معيّن، مع عدم تغيير جميع البيانات الأخرى.
إضافة كيان جديد من المستوى الأعلى
لا تنطبق إلا على الكيانات من الأنواع MenuRestaurant وService.
Menu وRestaurant وService
على سبيل المثال، تحتاج إلى إضافة قائمة طعام جديدة إلى مطعم.
الخلاصات الكاملة: أضِف الكيان في خلاصات البيانات وانتظر نقل البيانات المجمّعة.
حذف العنصر من المستوى الأعلى نهائيًا
لا تنطبق إلا على الكيانات من الأنواع MenuRestaurant وService.
الخلاصات الكاملة: احرص على إزالة الكيان من الخلاصات الكاملة قبل
عملية الجلب التالية التي تجريها Google، وإلا ستتم إعادة إضافة الكيان.
إضافة منطقة تسليم جديدة في Service معيّن
ServiceArea
الخلاصات على دفعات: أرسِل العنصر ServiceArea المعنيّ مع كل حقول
ه، كما تفعل عادةً في الخلاصات الكاملة، مع تحديد منطقة إرسال جديدة
في polygon أو geoRadius أو postalCode.
تعديل الوقت المقدَّر للوصول في Service
ServiceHours
الخلاصات المجمّعة: أرسِل ServiceHours بالطريقة نفسها في
الخلاصات، باستثناء تعديل leadTimeMin
وفقًا لذلك.
تعديل أسعار التسليم في Service
Fee
الخلاصات المجمّعة: أرسِل خلاصة Fee الكاملة التي تم تعديل
price فيها.
تعديل ساعات خدمة التوصيل أو الطعام السفري في Service
ServiceHours
الخلاصات المجمّعة: أرسِل ServiceHours بالطريقة نفسها في
الخلاصات، باستثناء تعديل سمتَي opens وcloses
وفقًا لذلك.
Service (تغيير الحد الأدنى لمبلغ الطلب)
Fee
الخلاصات المجمّعة: أرسِل Fee كاملاً مع
minPrice
معدَّلًا.
حذف MenuItem نهائيًا
Menu
الخلاصات المجمّعة: أرسِل MenuItem بالطريقة نفسها المستخدَمة في
الخلاصات، ولكن مع ترك parentMenuSectionId فارغًا.
أوقات معالجة المهام المجمّعة والتعديلات في الوقت الفعلي
سيتمّت معالجة الكيانات التي تمّ تعديلها أو حذفها من خلال خلاصة مجمّعة في غضون
ساعتَين، في حين سيتمّت معالجة الكيانات التي تمّ تعديلها من خلال تعديل في الوقت الفعلي في
5 دقائق. يتم حذف
العناصر القديمة
بعد 14 يومًا.
يمكنك إرسال ما يلي إلى Google:
مهام مجمّعة متعددة في اليوم للحفاظ على حداثة المستودع
مهمة مجمّعة واحدة في اليوم وتعديلات في الوقت الفعلي للحفاظ على حداثة مستودعك
تاريخ التعديل الأخير: 2024-11-26 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2024-11-26 (حسب التوقيت العالمي المتفَّق عليه)"],[[["This API enables partners to send time-sensitive inventory updates to Google, reflecting changes in the Google UI within five minutes."],["It supports `upsert` and `delete` operations for up to 1,000 entities per API call, processing requests asynchronously via a queue."],["Include changes made via real-time updates in your daily data feeds to maintain data consistency and avoid overwrites."],["For adding new entities, use batch ingestion instead of real-time updates, as it is not designed for this purpose."],["The `generation_timestamp` field ensures updates within a `batchPush` request are applied in the correct order, facilitating entity versioning."]]],[]]
