يصف هذا القسم كيفية إرسال تحديثات لمستودعك في الوقت المناسب.
الجهات الخارجية إلى Google. تتيح لك واجهة برمجة التطبيقات للتحديثات الفورية إرسال التحديثات وحذفها.
والكيانات في مستودع وضع الحماية أو مستودع الإنتاج في الوقت الفعلي تقريبًا.
هذه الوظيفة مخصصة في المقام الأول للتحديثات التي لا يمكنك توقعها،
مثل عمليات الإغلاق الطارئة أو إزالة السلع من القائمة أو تعديل السعر
لعنصر في القائمة، والذي يجب أن ينعكس بسرعة في واجهة مستخدم Google. في حال التغيير
على الفور، يمكنك استخدام
عرض البيانات بشكل مجمّع بدلاً من ذلك تتم معالجة التحديثات في الوقت الفعلي في
لا تزيد عن خمس دقائق.
المتطلبات الأساسية
يجب تقديم العناصر التالية قبل تنفيذ التحديثات في الوقت الفعلي:
تم تفعيل واجهة برمجة تطبيقات حجز الخرائط:
في Google Cloud Platform، انتقِل إلى واجهات برمجة التطبيقات الخدمات > المكتبة
ابحث عن "Google Maps Booking API" .
ابحث عن مثيل Sandbox ("واجهة برمجة تطبيقات الحجز في خرائط Google (Dev)") وانقر على
تفعيل
ابحث عن مثيل الإنتاج ("واجهة برمجة تطبيقات الحجز في خرائط Google") وانقر على
تفعيل
يتم إنشاء حساب خدمة بدور المحرِّر لمشروع Google Cloud Platform. بالنسبة
المزيد من التفاصيل، راجع
إعداد الحساب:
تتم استضافة ونقل خلاصات بيانات الإنتاج أو وضع الحماية. لمزيد من التفاصيل،
راجِع العرض المجمَّع.
بالنسبة إلى مصادقة واجهة برمجة التطبيقات، يوصى بتثبيت
مكتبة برامج Google باللغة
خِيَار. استخدام "https://www.googleapis.com/auth/mapsbooking" كبروتوكول OAuth
النطاق. وتستخدم عيّنات التعليمات البرمجية أدناه هذه المكتبات. وإلا،
عليك التعامل مع عمليات تبادل الرموز المميّزة يدويًا كما هو موضّح في
استخدام OAuth 2.0 للوصول إلى Google APIs
نظرة عامة
تتيح واجهة برمجة التطبيقات للتحديثات في الوقت الفعلي نوعين من العمليات. العملية الأولى هي
لتأكيد تحديث الكيانات الحالية. تشير رسالة الأشكال البيانية
العملية الثانية هي حذف لإزالة الكيانات من مستودعك. كلاهما
يتم إجراء العمليات على مجموعة من الكيانات المدرجة في نص الطلب. إِنْتَ
إمكانية إجراء تعديلات على ما يصل إلى 1,000 عنصر في طلب بيانات واحد لواجهة برمجة التطبيقات. تقبل واجهة برمجة التطبيقات
جميع الطلبات الواردة ويضعها في قائمة انتظار لمزيد من المعالجة.
ولذلك تتم معالجة طلبات RTU بشكل غير متزامن.
تعمل واجهة برمجة التطبيقات للتحديثات في الوقت الفعلي في بيئتين هما: وضع الحماية والإنتاج.
يتم استخدام بيئة Sandbox لاختبار طلبات واجهة برمجة التطبيقات والإنتاج
لتحديث المحتوى المرئي للمستخدمين النهائيين للطلب. أسماء المضيفين
كلتا البيئتين:
وضع الحماية - partnerdev-mapsbooking.googleapis.com
الإنتاج - mapsbooking.googleapis.com
نقاط النهاية
تعرض واجهة برمجة التطبيقات للتحديثات في الوقت الفعلي نقطتَي نهاية للتعامل مع الطلبات الواردة
لتحديثات المخزون:
يمكن العثور على المعلمة PARTNER_ID في مركز الإجراءات
يظهر على أنه رقم تعريف الشريك على صفحة الحساب والمستخدمين، كما هو موضح في
لقطة الشاشة أدناه.
لنفترض أن 10000001 هي قيمة PARTNER_ID كمثال من
لقطة الشاشة أعلاه، عناوين 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
تعديل الكيانات
لتعديل الكيانات في مستودعك، استخدِم UPSERTUPSERT.
ونرسل طلبات HTTP POST. يجب أن يتضمن كل طلب POST
معلَمة PARTNER_ID مع حمولة JSON التي تحتوي على
البيانات المنظَّمة من أي نوع عنصر مُدرَج في مخطط المستودع.
حمولة طلب التحديث
نص الطلب هو كائن 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 هو
يُستخدم في إعداد نُسخ الكيان. يمكنك الاطّلاع على توقّعات
تنسيق قيم الوقت في المستودع العلائقي
Google.
يجب أن يستوفي كل طلب تعديل في الوقت الفعلي الشروط التالية:
يجب ألا يتجاوز حجم نص الحمولة 5 ميغابايت. على غرار الإجراء المجمّع
الخلاصات، نقترح إزالة المسافات البيضاء بهدف ملاءمة المزيد من البيانات.
ويمكن إدخال ما يصل إلى 1,000 كيان في طلب batchPush.
أمثلة
المثال 1: تعديل معلومات مطعم
لنفترض أنك بحاجة بشكل عاجل إلى تحديث رقم هاتف مطعم.
يحتوي التحديث على ملف JSON للمطعم بأكمله.
لا تستخدِم التعديلات في الوقت الفعلي لإضافة كيانات جديدة لأنّ ذلك قد يؤدي إلى عدم اتّساق البيانات. بدلاً من ذلك، استخدِم الخلاصات المجمّعة.
كما هو موضَّح في عملية العرض المجمَّع.
حذف الكيانات
لحذف كيانات من مستودعك، استخدِم الزر DELETEنقطة النهاية وإرسال طلبات HTTP POST. يجب أن يكون كل طلب POST
تضمين المَعلمة PARTNER_ID مع حمولة JSON
الذي يتضمّن معرّف أي كيان في مستودعك
حذف حمولة الطلب
يتم بناء نص طلب الحذف بشكل مشابه لـ
طلب تعديل.
وتحتوي أيضًا على قائمة بسجلّات تتضمّن data_record وdelete_time:
BASE_64_ENCODED_REFERENCE: سلسلة JSON المرمّزة من Base64
يشير إلى الكيان الذي تتم إزالته. يتكون المرجع فقط
من نوع الكيان ومعرِّفه، مثل تمثيل JSON
الرجوع إلى MenuSection:
{"@type":"MenuSection","@id":"853705"}
DELETE_TIMESTAMP: احرص على تضمين الطابع الزمني لوقت
في نظام الواجهة الخلفية. يتم استخدام هذا الطابع الزمني
تحديد ترتيب تطبيق الحذف على المستودع.
ويمكن إدخال ما يصل إلى 1,000 كيان في طلب batchDelete.
أمثلة
المثال 1: إزالة كيانَين MenuItem
لإزالة عنصري قائمة في استدعاء واجهة برمجة تطبيقات واحد، سيكون طلب HTTP POST كما يلي
التالي:
فكّر في موقف تريد فيه حذف مطعم في الخلاصة المجمّعة.
يجب حذف كيان المطعم فقط. لا تحذف العناصر الفرعية، مثل
والخدمات والقوائم، حيث ستتم إزالتها تلقائيًا.
نموذج طلب لحذف كيان مطعم برقم التعريف
https://www.provider.com/restaurant/12345:
التحقق من الصحة رموز الاستجابة من واجهة برمجة التطبيقات
هناك نوعان من عمليات التحقّق التي يتم إجراؤها على طلبات بيانات من واجهة برمجة التطبيقات للتحديث في الوقت الفعلي:
مستوى الطلب: تتحقّق عمليات التحقّق هذه من أنّ الحمولة تتبع
upert أو 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 للمصادقة باستخدام
ملف مفتاح حساب الخدمة الذي تم إنشاؤه أثناء
إعداد الحساب:
للحصول على حلول بديلة، يمكنك الرجوع إلى
استخدام 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.
const serviceAccountJson = require('./service-account.json');
// ACTION REQUIRED: Change this to your Partner ID received from Google.
// The Partner ID is available on the Partner Portal.
const PARTNER_ID = 1234;
const HOST = {
prod: 'https://mapsbooking.googleapis.com',
sandbox: 'https://partnerdev-mapsbooking.googleapis.com'
};
// ACTION REQUIRED: Change to 'prod' for production
const ENV = 'sandbox';
// Feed name for Order with Google including the version.
const FEED_NAME = 'owg.v2';
// Endpoint url
const url = `${HOST[ENV]}/v1alpha/inventory/partners/${PARTNER_ID}/feeds/${
FEED_NAME}/record:batchPush`;
/**
* Send a Real-time update request to update/insert entities
*/
async function batchUpsert(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
*/
const client = new JWT({
email: serviceAccountJson.client_email,
key: serviceAccountJson.private_key,
scopes: ['https://www.googleapis.com/auth/mapsbooking'],
});
const request = {records: toPushRecords(entities)};
const body = JSON.stringify(request);
try {
const response = await client.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
*/
const toPushRecords = (entities) => {
return entities.map((entity) => {
// Using dateModified to set generation_timestamp. Defaulting to the
// current timestamp for records that do not have dateModified.
const generation_timestamp =
entity.dateModified ? entity.dateModified : new Date().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-auth
import base64
import datetime
import json
from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_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)
def batch_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.html
credentials = 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 object
batch_request = {'records': [create_push_record(x) for x in entities]}
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 '{}'
def create_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.dateModified if 'dateModified' in entity else datetime.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
*/
package rtusamples;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.google.auth.oauth2.AccessToken;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.FileInputStream;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.Charset;
import java.time.Clock;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;
import java.util.Optional;
import java.util.stream.Collectors;
import rtusamples.inventory.MenuItemOffer;
import rtusamples.inventory.MenuItemOfferType;
import rtusamples.inventory.ServiceTypeElement;
import rtusamples.realtime.BatchPushGenericRecordRequest;
import rtusamples.realtime.GenericRecord;
/** Sample code for Real-time update batchPush implementation. */
public final class BasicPush {
// ACTION REQUIRED: Change this to your Partner ID received from Google. The Partner ID is
// available on the Partner Portal.
private static final long PARTNER_ID = 12345678;
// ACTION REQUIRED: Change this to the path of the service account client secret file downloaded
// from the Google Cloud Console.
private static final String JSON_KEY_FULL_PATH =
"<path to your JSON credentials>/credentials.json";
// ACTION REQUIRED: Change this to the endpoint that is needed.
private static final String ENDPOINT =
// "https://partnerdev-mapsbooking.googleapis.com"; // for sandbox
"https://mapsbooking.googleapis.com"; // for prod
// Feed name for Order with Google including the version.
private static final String FEED_NAME = "owg.v2";
private static final ObjectMapper objectMapper = new ObjectMapper();
private static final DateTimeFormatter TIMESTAMP_FORMATTER =
DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'");
private static final Charset UTF_8 = Charset.forName("UTF-8");
public static void main(String[] args) throws Exception {
/**
* 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);
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(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.
MenuItemOffer menuItemOfferPizza = new MenuItemOffer();
menuItemOfferPizza.setID("6680261");
menuItemOfferPizza.setType(MenuItemOfferType.MENU_ITEM_OFFER);
menuItemOfferPizza.setMenuItemID("18931508");
menuItemOfferPizza.setPrice(15.5);
menuItemOfferPizza.setPriceCurrency("USD");
menuItemOfferPizza.setApplicableServiceType(
new ServiceTypeElement[] {ServiceTypeElement.TAKEOUT, ServiceTypeElement.DELIVERY});
menuItemOfferPizza.setInventoryLevel(0.0);
menuItemOfferPizza.setDateModified("2022-10-07T13:00:00.000Z");
MenuItemOffer menuItemOfferSalad = new MenuItemOffer();
menuItemOfferSalad.setID("6680262");
menuItemOfferSalad.setType(MenuItemOfferType.MENU_ITEM_OFFER);
menuItemOfferSalad.setMenuItemID("18931509");
menuItemOfferSalad.setPrice(25.5);
menuItemOfferSalad.setPriceCurrency("USD");
menuItemOfferSalad.setApplicableServiceType(
new ServiceTypeElement[] {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 = new ArrayList<>();
// Add list of menuItemOffer generic records.
recordsToBeUpdated.addAll(menuItemOfferGenericRecords);
// Request object that contains all records.
BatchPushGenericRecordRequest batchPushRequest = new BatchPushGenericRecordRequest();
batchPushRequest.setRecords(recordsToBeUpdated.toArray(new GenericRecord[0]));
// Execute batchPush request.
BasicPush basicPush = new BasicPush();
basicPush.batchPush(batchPushRequest, credentials);
}
public void batchPush(
BatchPushGenericRecordRequest batchPushRequest, GoogleCredentials credentials)
throws IOException {
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
String requestBody = objectMapper.writeValueAsString(batchPushRequest);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request =
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 | InterruptedException e) {
e.printStackTrace();
}
}
public static <T> GenericRecord toBatchPushRecord(T entity, String dateModified) {
GenericRecord genericRecord = new GenericRecord();
try {
String json = 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.
String generationTimestamp =
Optional.ofNullable(dateModified)
.orElse(OffsetDateTime.now(Clock.systemUTC()).format(TIMESTAMP_FORMATTER));
genericRecord.setGenerationTimestamp(generationTimestamp);
} catch (JsonProcessingException e) {
System.out.println(e.getMessage());
}
return genericRecord;
}
}
/* 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.
const serviceAccountJson = require('./service-account.json');
// ACTION REQUIRED: Change this to your Partner ID received from Google.
// The Partner ID is available on the Partner Portal.
const PARTNER_ID = 1234;
const HOST = {
prod: 'https://mapsbooking.googleapis.com',
sandbox: 'https://partnerdev-mapsbooking.googleapis.com'
};
// ACTION REQUIRED: Change to 'prod' for production
const ENV = 'sandbox';
// Feed name for Order with Google including the version.
const FEED_NAME = 'owg.v2';
// Endpoint url
const url = `${HOST[ENV]}/v1alpha/inventory/partners/${PARTNER_ID}/feeds/${
FEED_NAME}/record:batchDelete`;
/**
* Send a Real-time update request to delete entities
*/
async function batchDelete(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
*/
const client = new JWT({
email: serviceAccountJson.client_email,
key: serviceAccountJson.private_key,
scopes: ['https://www.googleapis.com/auth/mapsbooking'],
});
const request = {
records: toDeleteRecords(entities)
};
const body = JSON.stringify(request);
try {
const response = await client.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
*/
const toDeleteRecords = (entities) => {
return entities.map((entity) => {
// Using dateModified to set delete_time. Defaulting to the current
// timestamp for records that do not have dateModified.
const delete_time =
entity.dateModified ? entity.dateModified : new Date().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-auth
import base64
import datetime
import json
from google.auth.transport.requests import AuthorizedSession
from google.oauth2 import service_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)
def batch_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.html
credentials = 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 object
batch_request = {'records': [create_delete_record(x) for x in entities]}
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 '{}'
def create_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.dateModified if 'dateModified' in entity else datetime.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
*/
package rtusamples;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.google.auth.oauth2.AccessToken;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.FileInputStream;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.Charset;
import java.time.Clock;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.List;
import java.util.Optional;
import java.util.stream.Collectors;
import rtusamples.inventory.Menu;
import rtusamples.inventory.MenuType;
import rtusamples.realtime.BatchDeleteGenericRecordsRequest;
import rtusamples.realtime.GenericDeleteRecord;
/** Sample code for the Real-time update batchDelete implementation. */
public final class BasicDelete {
// ACTION REQUIRED: Change this to your Partner ID received from Google. The Partner ID is
// available on the Partner Portal.
private static final long PARTNER_ID = 123456789;
// ACTION REQUIRED: Change this to the path of the service account client secret file downloaded
// from the Google Cloud Console.
private static final String JSON_KEY_FULL_PATH =
"<path to your JSON credentials>/credentials.json";
// ACTION REQUIRED: Change this to the endpoint that is needed.
private static final String ENDPOINT =
"https://partnerdev-mapsbooking.googleapis.com"; // for sandbox
// "https://mapsbooking.googleapis.com" // for prod
// Feed name for Order with Google including the version.
private static final String FEED_NAME = "owg.v2";
private static final ObjectMapper objectMapper = new ObjectMapper();
private static final DateTimeFormatter TIMESTAMP_FORMATTER =
DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z'");
private static final Charset UTF_8 = Charset.forName("UTF-8");
public static void main(String[] args) throws Exception {
/**
* 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);
GoogleCredentials credentials =
GoogleCredentials.fromStream(new FileInputStream(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.
Menu menuLunch = new Menu();
menuLunch.setID("853705");
menuLunch.setType(MenuType.MENU);
menuLunch.setDateModified("2022-09-19T13:10:00.000Z");
Menu menuDinner = new Menu();
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 = new ArrayList<>();
// Add list of menu generic records.
recordsToBeDeleted.addAll(menuGenericDeleteRecords);
// Request object that contains all records.
BatchDeleteGenericRecordsRequest batchDeleteRequest = new BatchDeleteGenericRecordsRequest();
batchDeleteRequest.setRecords(recordsToBeDeleted.toArray(new GenericDeleteRecord[0]));
// Execute batchDelete request.
BasicDelete basicDelete = new BasicDelete();
basicDelete.batchDelete(batchDeleteRequest, credentials);
}
public void batchDelete(
BatchDeleteGenericRecordsRequest batchDeleteRequest, GoogleCredentials credentials)
throws IOException {
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
String requestBody = objectMapper.writeValueAsString(batchDeleteRequest);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request =
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 | InterruptedException e) {
e.printStackTrace();
}
}
public static <T> GenericDeleteRecord toBatchDeleteRecord(T entity, String dateModified) {
GenericDeleteRecord genericRecord = new GenericDeleteRecord();
try {
String json = 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.
String deleteTime =
Optional.ofNullable(dateModified)
.orElse(OffsetDateTime.now(Clock.systemUTC()).format(TIMESTAMP_FORMATTER));
genericRecord.setDeleteTime(deleteTime);
} catch (JsonProcessingException e) {
System.out.println(e.getMessage());
}
return genericRecord;
}
}
حالات الاستخدام
وفي ما يلي أمثلة على التحديثات التي يتم إجراؤها في الوقت الفعلي وتحديثات الخلاصات المجمّعة
والمحتوى على مستوى عالٍ في طلب البيانات من واجهة برمجة التطبيقات:
السيناريو
العنصر المطلوب تعديله
الوصف والتأثيرات
إيقاف خدمة
Service
تحتاج إلى إيقاف خدمة لسبب غير متوقع.
إشعارات في الوقت الفعلي: عدِّل كيان Service في
من خلال ضبط خاصية isDisabled على true،
مع الحفاظ على الخصائص الأخرى نفسها.
الخلاصات الكاملة: احرص على تعديل العنصر من الخلاصات الكاملة.
أن يتم ضبط isDisabled على true قبل
عملية الجلب التالية من Google، وإلا ستتم إعادة تفعيل الكيان.
سلعة معيّنة غير متوفّرة
MenuItemOffer
إشعارات في الوقت الفعلي: أرسِل MenuItemOffer غلافًا.
كيان مع ضبط inventoryLevel على 0
MenuItem وجميع البيانات الأخرى بدون تغيير.
تغيير سعر الصنف في القائمة
MenuItemOffer
إشعارات في الوقت الفعلي: أرسِل MenuItemOffer غلافًا.
كيان price تم ضبط السعر المعدَّل له
MenuItem وجميع البيانات الأخرى بدون تغيير.
إضافة كيان جديد ذي مستوى أعلى
ينطبق فقط على الكيان من الأنواع Menu،
Restaurant وService
Menu وRestaurant وService
على سبيل المثال، تحتاج إلى إضافة قائمة طعام جديدة إلى مطعم.
الخلاصات الكاملة: أضِف الكيان في خلاصات البيانات وانتظِر حتى يتم العرض بشكل مجمّع.
حذف الكيان ذي المستوى الأعلى نهائيًا
ينطبق فقط على الكيان من الأنواع Menu،
Restaurant و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-08-29 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2024-08-29 (حسب التوقيت العالمي المتفَّق عليه)"],[[["The Real-Time Update API enables partners to send time-sensitive inventory updates to Google, reflecting changes in the Google UI within five minutes."],["This API supports upsert and delete operations, handling up to 1,000 entities per API call and processing requests asynchronously in sandbox and production environments."],["While the API can update existing entities or delete them, it should not be used to add new entities; batch ingestion is recommended for that purpose."],["Developers should include real-time update changes in their daily data feeds to maintain data consistency and be aware that deleting an entity does not remove its references from other entities, potentially leading to warnings."],["Partners need to enable the Maps Booking API in GCP, create a service account with editor role, host and ingest data feeds, and install the Google Client library for API authentication as prerequisites."]]],[]]
