Обновление в реальном времени

Обновления в режиме реального времени

Обновления в режиме реального времени (RTU) в первую очередь предназначены для непредвиденных изменений, таких как аварийные закрытия или периодически изменяющиеся метаданные (например, предполагаемое время прибытия). Если изменения не требуют немедленного отражения, можно использовать пакетную обработку. Обновления в режиме реального времени обрабатываются не более чем за пять минут.

Настройка платформы Google Cloud

  1. Создайте проект GCP. Проект GCP необходим для доступа к API RTU.
    • Доступ к редактору гранта : food-support@google.com
    • Сообщите своему контактному лицу в Google номер проекта GCP. Для корректной работы обновлений в режиме реального времени ваш проект GCP должен быть связан с вашей учетной записью в Центре действий.
    • Включить API бронирования карт:
      • В GCP перейдите в раздел API и сервисы > Библиотека .
      • Найдите в поиске «Google Maps Booking API».
        Найдите API бронирования Google Maps.
      • Найдите экземпляр песочницы («Google Maps Booking API (Dev)») и нажмите «Включить».
      • Найдите экземпляр Production («Google Maps Booking API») и нажмите «Включить».
        Включить API бронирования Google Maps
      • Создайте учетную запись службы с ролью редактора для вашего проекта GCP. Дополнительные сведения см. в разделе «Настройка учетной записи службы» .
      • Убедитесь, что вы загружаете пакетные потоки данных в среду, в которой работаете над обновлениями в режиме реального времени.
      • Для аутентификации через API мы рекомендуем установить библиотеку Google Client на выбранном вами языке. Используйте «https://www.googleapis.com/auth/mapsbooking» в качестве области действия OAuth. Приведенные ниже примеры кода используют эти библиотеки. В противном случае вам потребуется обрабатывать обмен токенами вручную, как описано в разделе «Использование OAuth 2.0 для доступа к API Google» .

Настройка учетной записи службы

Для выполнения аутентифицированных HTTPS-запросов к API Google, например, к API обновлений в реальном времени, вам потребуется учетная запись службы .

Для настройки служебной учетной записи выполните следующие действия:

  1. Получите доступ к консоли Google Cloud Platform.
  2. В Центре действий к вашей учетной записи также привязан проект Google Cloud. Выберите этот проект, если он еще не выбран.
  3. В левом меню нажмите «Служебные учетные записи» .
  4. Нажмите «Создать учетную запись службы» .
  5. Введите имя для учетной записи службы и нажмите «Создать» .
  6. Для выбора роли выберите Проект > Редактор .
  7. Нажмите «Продолжить» .
  8. Необязательно: добавьте пользователей, предоставив им доступ к учетной записи службы, и нажмите «Готово» .
  9. Нажмите «Подробнее» > «Создать ключ для только что созданной учетной записи службы».
  10. Выберите формат JSON и нажмите «Создать» .
  11. После того, как будет сгенерирована новая пара открытого/закрытого ключей, загрузите её на свой компьютер.

Работа с API

API обновлений в реальном времени поддерживает два типа операций: обновление и удаление. Добавление новых объектов через API обновлений в реальном времени не поддерживается. Обновления в реальном времени можно объединять в пакеты, если вы включаете несколько обновлений в один запрос API. В одном вызове API можно объединить до 1000 обновлений. Мы рекомендуем использовать подход, основанный на триггерах, для отправки обновлений через RTU (т.е. при изменении данных в вашей системе запускать обновление в реальном времени в Google), а не подход, основанный на частоте (т.е. каждые X минут сканировать вашу систему на наличие изменений), если это возможно.

API для обновления данных в реальном времени работает как в тестовой, так и в производственной среде. Тестовая среда используется для проверки запросов API, а производственная — для обновления контента, видимого пользователям системы Ordering 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, равное 10000001, как показано на скриншоте выше, полные 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 запроса batchPush поле generation_timestamp используется для версионирования сущности. См. ожидаемый формат значений времени в схеме реляционного инвентаря.
  • Размер содержимого полезной нагрузки не должен превышать 5 МБ.
  • Удалите пробелы, чтобы уменьшить размер.
  • В одном пакетном запросе batchPush может содержаться до 1000 обновлений.

Примеры

Обновите предполагаемое время прибытия.

Предположим, вам срочно нужно обновить расчетное время прибытия службы доставки с 30-60 минут до 60-90 минут. Ваше обновление должно содержать JSON-данные для всего объекта Service.

Рассмотрим сервисную сущность, которая выглядит следующим образом:

{
	"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 минут.

Назад
Отслеживание конверсий