RTU в первую очередь предназначены для обновлений, которые вы не можете предвидеть, например аварийного закрытия или метаданных, которые периодически меняются (например, ETA). Если изменение не требуется немедленно отражать, вместо этого можно использовать пакетную загрузку ленты. Обновления в режиме реального времени обрабатываются не более чем за пять минут.
Настройка облачной платформы Google
- Настройте проект GCP. Для доступа к API RTU необходим проект GCP.
- Предоставить редактору доступ food-support@google.com
- Сообщите своему POC Google номер проекта GCP. Ваш проект GCP должен быть связан с вашей учетной записью Центра действий, чтобы обновления в реальном времени работали.
- Включите API бронирования карт:
- В GCP перейдите в раздел API и сервисы > Библиотека .
- Найдите «API бронирования Карт Google».
- Найдите экземпляр песочницы («Google Maps Booking API (Dev)») и нажмите «Включить».
- Найдите рабочий экземпляр («Google Maps Booking API») и нажмите «Включить».
- Создайте сервисную учетную запись с ролью редактора для вашего проекта GCP. Подробнее см. в разделе Настройка учетной записи службы .
- Обязательно загружайте пакетные каналы в среду, в которой вы работаете над обновлениями в режиме реального времени.
- Для аутентификации API мы рекомендуем установить клиентскую библиотеку Google на выбранном вами языке. Используйте https://www.googleapis.com/auth/mapsbooking в качестве области действия OAuth. В приведенных ниже примерах кода используются эти библиотеки. В противном случае вам придется обрабатывать обмен токенами вручную, как описано в разделе Использование OAuth 2.0 для доступа к API Google .
Настройка учетной записи службы
Вам понадобится учетная запись службы для отправки аутентифицированных HTTPS-запросов к API Google, например к API обновлений в реальном времени.
Чтобы настроить учетную запись службы, выполните следующие действия:
- Откройте консоль Google Cloud Platform.
- С вашей учетной записью в Центре действий также связан проект Google Cloud. Выберите этот проект, если он еще не выбран.
- Нажмите «Учетные записи служб» в меню слева.
- Нажмите Создать учетную запись службы .
- Введите имя сервисной учетной записи и нажмите «Создать» .
- Для параметра «Выберите роль» выберите «Проект» > «Редактор» .
- Нажмите Продолжить .
- Необязательно: добавьте пользователей, чтобы предоставить им доступ к учетной записи службы, и нажмите «Готово» .
- Нажмите «Еще» > «Создать ключ» для только что созданной учетной записи службы.
- Выберите JSON в качестве формата и нажмите «Создать» .
- После создания новой пары открытого и закрытого ключей загрузите ее на свой компьютер.
Работа с API
API обновлений в реальном времени поддерживает два типа операций: обновление и удаление. Добавление новых сущностей через API обновления в реальном времени не поддерживается. Обновления в реальном времени можно группировать, если вы включаете несколько обновлений в один запрос API. Вы можете пакетировать до 1000 обновлений за один вызов API. Мы рекомендуем использовать триггерный подход для отправки обновлений через RTU (т. е. при изменении данных в вашей системе запускать обновление в реальном времени в Google), а не частотный подход (т. е. каждые X минут сканировать вашу систему на наличие изменений), если возможный.
API обновлений в реальном времени работает как в песочнице, так и в производственной среде. Среда «песочница» используется для тестирования запросов API и производственной среды для обновления контента, видимого для сквозных пользователей заказа.
- Песочница -
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 можно найти в Центре действий на странице «Учетная запись и пользователи» , как показано на скриншоте ниже.
Если взять 10000001 в качестве значения PARTNER_ID в качестве примера на скриншоте выше, полные URL-адреса для отправки запросов API в песочнице и производстве будут выглядеть так, как показано в примерах ниже.
Обновление песочницы
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: обязательно укажите временную метку создания объекта в ваших серверных системах. Если это поле не включено, в нем будет указано время, когда Google получит запрос. При обновлении сущности с помощью запросаbatchPushполеgeneration_timestampиспользуется для управления версиями сущности. См. ожидаемый формат значений времени в схеме реляционной инвентаризации.
- Размер тела полезной нагрузки не должен превышать 5 МБ.
- Удалите пробелы, чтобы уменьшить размер.
- В
batchPushзапросе может быть до 1000 обновлений.
Примеры
Обновить расчетное время прибытия
Предположим, вам срочно нужно обновить расчетное время доставки службы доставки с 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 обновления в реальном времени:
- Уровень запроса . Эти проверки проверяют, соответствует ли полезная нагрузка схеме, и каждая
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."
}
]
}
- Уровень объекта : каждый объект (proto_record) в полезных данных проверяется на соответствие схеме. О проблемах, возникших на этом этапе проверки, не сообщается в ответе 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 минут.