Se usó la API de Cloud Translation para traducir esta página.

Actualización en tiempo real

Actualizaciones en tiempo real

Las RTU se diseñaron principalmente para actualizaciones que no puedes prever, como cierres de emergencia o metadatos que cambian periódicamente (como las horas de llegada estimada). Si no es necesario que el cambio se refleje de inmediato, puedes usar la transferencia de feeds por lotes. Las actualizaciones en tiempo real se procesan en no más de cinco minutos.

Configuración de Google Cloud Platform

Configura un proyecto de GCP. Se necesita un proyecto de GCP para acceder a la API de RTU.
- Otorga acceso de editor a food-support@google.com
- Informa a tu PDC de Google el número de proyecto de GCP.El proyecto de GCP debe estar asociado a tu cuenta del Centro de acciones para que las actualizaciones en tiempo real funcionen.
- Habilita la API de Maps Booking:
  - En GCP, ve a APIs y servicios > Biblioteca.
  - Busca "API de Google Maps Booking".
  - Busca la instancia de zona de pruebas ("API de Google Maps Booking (Dev)") y haz clic en Habilitar.
  - Busca la instancia de producción ("API de Google Maps Booking") y haz clic en Habilitar.
  - Crear una cuenta de servicio con un rol de editor para el proyecto de GCP Para obtener más detalles, consulta Configuración de la cuenta de servicio.
  - Asegúrate de subir feeds por lotes al entorno en el que trabajas con actualizaciones en tiempo real.
  - Para la autenticación de la API, recomendamos instalar la biblioteca cliente de Google en el lenguaje que desees. Usa “https://www.googleapis.com/auth/mapsbooking” como alcance de OAuth. Las muestras de código que se incluyen a continuación usan estas bibliotecas. De lo contrario, deberás manejar los intercambios de tokens manualmente como se describe en Cómo usar OAuth 2.0 para acceder a las APIs de Google.

Configuración de la cuenta de servicio

Necesitas una cuenta de servicio para realizar solicitudes HTTPS autenticadas a las APIs de Google, como la API de actualizaciones en tiempo real.

Para configurar una cuenta de servicio, haz lo siguiente:

Accede a Google Cloud Platform Console.
Tu cuenta del Centro de Actions también tiene asociado un proyecto de Google Cloud. Selecciona ese proyecto si todavía no está seleccionado.
Haz clic en Cuentas de servicio en el menú de la izquierda.
Haz clic en Crear cuenta de servicio.
Ingresa un nombre para la cuenta de servicio y haz clic en Crear.
En Selecciona un rol, elige Proyecto > Editor.
Haz clic en Continuar.
Opcional: Agrega usuarios para otorgarles acceso a la cuenta de servicio y haz clic en Listo.
Haz clic en más > Crear clave para la cuenta de servicio que acabas de crear.
Selecciona JSON como el formato y haz clic en Crear.
Una vez que se genere el nuevo par de claves pública/privada, descárgalo en tu máquina.

Trabajar con la API

La API de Actualizaciones en tiempo real admite dos tipos de operaciones: Actualizar y Borrar. No se admite la adición de entidades nuevas a través de la API de actualización en tiempo real. Las actualizaciones en tiempo real se pueden agrupar si incluyes varias actualizaciones en una sola solicitud a la API. Puedes agrupar hasta 1,000 actualizaciones en una sola llamada a la API. Si es posible, recomendamos usar un enfoque basado en activadores para enviar actualizaciones a través de la RTU (es decir, cuando un cambio en los datos de tu sistema active una actualización de Google en tiempo real) en lugar de un enfoque basado en la frecuencia (es decir, cada X minutos que analices tu sistema para detectar cambios).

La API de actualizaciones en tiempo real funciona en entornos de zona de pruebas y producción. El entorno de zona de pruebas se utiliza para probar las solicitudes a la API y el entorno de producción para actualizar el contenido visible para los usuarios de extremo a extremo de pedidos.

Zona de pruebas: partnerdev-mapsbooking.googleapis.com
Producción: mapsbooking.googleapis.com

Extremos

La API de actualizaciones en tiempo real expone dos extremos para controlar las solicitudes entrantes de actualizaciones de inventario:

ACTUALIZACIÓN: /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
BORRAR: /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete

El parámetro PARTNER_ID se puede encontrar en el Centro de acciones, en la página Cuenta y usuarios, como se muestra en la siguiente captura de pantalla.

Tomando 10000001 como el valor de PARTNER_ID como ejemplo de la captura de pantalla anterior, las URLs completas para enviar solicitudes a la API en la zona de pruebas y en producción se verán como en los ejemplos a continuación.

Actualización de la zona de pruebas

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

BORRAR en la zona de pruebas

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

Actualización de producción

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

BORRADO para producción

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

Actualiza entidades

Para actualizar entidades en tu inventario, usa el extremo update en una solicitud HTTP POST. Cada solicitud POST debe incluir el parámetro 10000001 junto con una carga útil JSON que contenga la entidad que deseas actualizar.

Nota: Asegúrate de que tus feeds de datos diarios también contengan los cambios realizados mediante la API de actualizaciones en tiempo real. De lo contrario, es posible que tus datos estén desactualizados o estén inactivos.

Actualiza la carga útil de la solicitud

El cuerpo de la solicitud es un objeto JSON con una lista de registros. Cada registro corresponde a una entidad que se actualiza. Está compuesto por el campo proto_record y el generation_timestamp que indica la hora de la actualización de la entidad:

  {
    "records": [
      {
        "proto_record":"ServiceData PROTO",
        "generation_timestamp":"UPDATE_TIMESTAMP"
      }
    ]
  }

ServiceData PROTO: La traducción proto o JSON de la entidad ServiceData que estás actualizando.
UPDATE_TIMESTAMP: Asegúrate de incluir la marca de tiempo del momento en que se generó la entidad en tus sistemas de backend. Si no se incluye este campo, se establecerá en la hora en que Google reciba la solicitud. Cuando se actualiza una entidad a través de una solicitud batchPush, se usa el campo generation_timestamp para el control de versiones de entidades. Consulta el formato esperado de los valores de tiempo en el esquema del inventario relacional.

El cuerpo de la carga útil no debe superar los 5 MB de tamaño.
Quita los espacios en blanco para reducir el tamaño.
Puede haber hasta 1,000 actualizaciones en una solicitud batchPush.

Ejemplos

Cómo actualizar una hora de llegada estimada

Supongamos que necesitas actualizar con urgencia la hora de llegada estimada de un servicio de entrega de 30 a 60 a 60 a 90 minutos. La actualización debe contener el archivo JSON para toda la entidad de servicio.

Considera una entidad de servicio con el siguiente aspecto:

{
	"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"
	}
}

Tu actualización en tiempo real por HTTP POST es la siguiente (los cuerpos de las solicitudes están impresos para facilitar la lectura):

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"
  }]
}

Actualizar varias entidades

Para actualizar varias entidades de restaurantes en una sola llamada a la API, incluye varios registros en el campo proto_record del cuerpo de la solicitud.

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"
  }]
}

Borrar entidades

Para borrar entidades de tu inventario, usa el extremo DELETE en una solicitud HTTP POST. Cada solicitud POST debe incluir el parámetro PARTNER_ID junto con la carga útil JSON que contiene el identificador de la entidad que quieres borrar.

Nota: Asegúrate de que tus feeds de datos diarios también contengan los cambios que se enviaron con la API de actualización en tiempo real. De lo contrario, la transferencia diaria por lotes reemplazará tus cambios en tiempo real.

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"
  }]
}

Agrega entidades

No uses actualizaciones en tiempo real para agregar entidades nuevas, ya que esto puede generar incoherencias en los datos. En su lugar, usa feeds por lotes.

Validación y códigos de respuesta de la API

Hay dos tipos de validaciones que se realizan en las llamadas a la API de actualización en tiempo real:

Nivel de solicitud: Estas validaciones comprueban que la carga útil siga el esquema y que cada proto_record contenga los campos id y type. Estas verificaciones son síncronas, y los resultados se muestran en el cuerpo de la respuesta de la API. Un código de respuesta 200 y un cuerpo JSON vacío {} significa que estas validaciones se aprobaron y las entidades de esa solicitud se pusieron en cola para su procesamiento. Un código de respuesta que no es 200 significa que una o más de estas validaciones fallaron y se rechaza la solicitud completa (incluidas todas las entidades de la carga útil). Por ejemplo, si a proto_record le falta un @type, se muestra la siguiente respuesta de error:

  {
      "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." 
      }
    ]
  }

Nivel de entidad: Cada entidad (proto_record) en la carga útil se valida según el esquema. Los problemas que se encuentran en esta fase de validación no se informan en la respuesta de la API. Solo se registran en el panel de informes de RTU del Centro de acciones.

Nota: Un código de respuesta 200 no significa que todas las entidades se transfirieron correctamente.

Cuotas de API

Las actualizaciones de la API en tiempo real tienen una cuota de 1,500 solicitudes cada 60 segundos, o 25 solicitudes por segundo en promedio. Cuando se supera una cuota, Google responde con el siguiente mensaje de error:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

Para controlar esto, vuelve a intentar la llamada en intervalos exponencialmente más grandes hasta que funcione. Si agotas la cuota con regularidad, considera incluir más entidades en una solicitud a la API. Puedes incluir hasta 1,000 entidades en una llamada a la API.

Tiempo de procesamiento de actualizaciones en tiempo real

Una entidad que se actualiza a través de una actualización en tiempo real se procesa en 5 minutos.

Seguimiento de conversiones