Usar la API REST de Cloud Firestore

Si bien la forma más sencilla de utilizar Cloud Firestore es utilizar una de las bibliotecas cliente nativas, hay algunas situaciones en las que resulta útil llamar directamente a la API REST.

La API REST puede resultar útil para los siguientes casos de uso:

  • Acceder a Cloud Firestore desde un entorno con recursos limitados, como un dispositivo de Internet de las cosas (IoT), donde no es posible ejecutar una biblioteca cliente completa.
  • Automatizar la administración de bases de datos o recuperar metadatos detallados de bases de datos.

Si está utilizando un lenguaje compatible con gRPC , considere usar la API RPC en lugar de la API REST.

Autenticacion y autorizacion

Para la autenticación, la API REST de Cloud Firestore acepta un token de ID de autenticación de Firebase o un token de Google Identity OAuth 2.0 . El token que proporciona afecta la autorización de su solicitud:

  • Utilice tokens de ID de Firebase para autenticar las solicitudes de los usuarios de su aplicación. Para estas solicitudes, Cloud Firestore utiliza las reglas de seguridad de Cloud Firestore para determinar si una solicitud está autorizada.

  • Utilice un token de Google Identity OAuth 2.0 y una cuenta de servicio para autenticar solicitudes de su aplicación, como solicitudes de administración de bases de datos. Para estas solicitudes, Cloud Firestore utiliza Gestión de acceso e identidad (IAM) para determinar si una solicitud está autorizada.

Trabajar con tokens de identificación de Firebase

Puedes obtener un token de ID de Firebase de dos maneras:

Al recuperar el token de ID de Firebase de un usuario, puedes realizar solicitudes en nombre del usuario.

Para solicitudes autenticadas con un token de ID de Firebase y para solicitudes no autenticadas, Cloud Firestore usa sus reglas de seguridad de Cloud Firestore para determinar si una solicitud está autorizada.

Trabajar con tokens de Google Identity OAuth 2.0

Puede generar un token de acceso utilizando una cuenta de servicio con una biblioteca cliente API de Google o siguiendo los pasos en Uso de OAuth 2.0 para aplicaciones de servidor a servidor . También puedes generar un token con la herramienta de línea de comandos gcloud y el comando gcloud auth application-default print-access-token .

Este token debe tener el siguiente alcance para enviar solicitudes a la API REST de Cloud Firestore:

  • https://www.googleapis.com/auth/datastore

Si autenticas tus solicitudes con una cuenta de servicio y un token de Google Identity OAuth 2.0, Cloud Firestore asume que tus solicitudes actúan en nombre de tu aplicación en lugar de un usuario individual. Cloud Firestore permite que estas solicitudes ignoren sus reglas de seguridad. En cambio, Cloud Firestore utiliza IAM para determinar si una solicitud está autorizada.

Puedes controlar los permisos de acceso de las cuentas de servicio asignando roles de IAM de Cloud Firestore .

Autenticar con un token de acceso

Después de obtener un token de Firebase ID o un token de Google Identity OAuth 2.0, páselo a los puntos finales de Cloud Firestore como un encabezado Authorization configurado en Bearer {YOUR_TOKEN} .

Realizar llamadas REST

Todos los puntos finales de la API REST existen en la URL base https://firestore.googleapis.com/v1/ .

Para crear una ruta a un documento con el ID LA en las cities de colección bajo el proyecto YOUR_PROJECT_ID , usaría la siguiente estructura.

/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

Para interactuar con esta ruta, combínela con la URL de la API base.

https://firestore.googleapis.com/v1/projects/YOUR_PROJECT_ID/databases/(default)/documents/cities/LA

La mejor manera de comenzar a experimentar con la API REST es utilizar API Explorer , que genera automáticamente tokens de Google Identity OAuth 2.0 y le permite examinar la API.

Métodos

A continuación se presentan breves descripciones de los dos grupos de métodos más importantes. Para obtener una lista completa, consulte la referencia de API REST o utilice API Explorer .

v1.projects.databases.documents

Realice operaciones CRUD en documentos, similares a las descritas en las guías para agregar datos u obtener datos .

v1.projects.databases.collectionGroups.indexes

Realice acciones en índices, como crear nuevos índices, deshabilitar un índice existente o enumerar todos los índices actuales. Útil para automatizar migraciones de estructuras de datos o sincronizar índices entre proyectos.

También permite la recuperación de metadatos de documentos, como la lista de todos los campos y subcolecciones de un documento determinado.

Códigos de error

Cuando una solicitud de Cloud Firestore se realiza correctamente, la API de Cloud Firestore devuelve un código de estado HTTP 200 OK y los datos solicitados. Cuando falla una solicitud, la API de Cloud Firestore devuelve un código de estado HTTP 4xx o 5xx y una respuesta con información sobre el error.

La siguiente tabla enumera las acciones recomendadas para cada código de error. Estos códigos se aplican a las API REST y RPC de Cloud Firestore. Es posible que los SDK de Cloud Firestore y las bibliotecas cliente no devuelvan estos mismos códigos de error.

Código de error canónico Descripción Acción sugerida
ABORTED La solicitud entraba en conflicto con otra solicitud. Para una confirmación no transaccional:
Vuelva a intentar la solicitud o reestructure su modelo de datos para reducir la contención.

Para solicitudes en una transacción:
Vuelva a intentar toda la transacción o reestructure su modelo de datos para reducir la contención.
ALREADY_EXISTS La solicitud intentó crear un documento que ya existe. No vuelva a intentarlo sin solucionar el problema.
DEADLINE_EXCEEDED El servidor de Cloud Firestore que maneja la solicitud excedió la fecha límite. Vuelva a intentar utilizar el retroceso exponencial.
FAILED_PRECONDITION La solicitud no cumplía ninguna de sus condiciones previas. Por ejemplo, una solicitud de consulta podría requerir un índice aún no definido. Consulte el campo de mensaje en la respuesta de error para conocer la condición previa que falló. No vuelva a intentarlo sin solucionar el problema.
INTERNAL El servidor de Cloud Firestore devolvió un error. No vuelva a intentar esta solicitud más de una vez.
INVALID_ARGUMENT Un parámetro de solicitud incluye un valor no válido. Consulte el campo de mensaje en la respuesta de error para conocer el valor no válido. No vuelva a intentarlo sin solucionar el problema.
NOT_FOUND La solicitud intentó actualizar un documento que no existe. No vuelva a intentarlo sin solucionar el problema.
PERMISSION_DENIED El usuario no está autorizado a realizar esta solicitud. No vuelva a intentarlo sin solucionar el problema.
RESOURCE_EXHAUSTED El proyecto superó su cuota o la capacidad regional/multirregional. Verifique que no haya excedido la cuota de su proyecto . Si excedió una cuota del proyecto, no vuelva a intentarlo sin solucionar el problema.

De lo contrario, vuelva a intentarlo con un retroceso exponencial.
UNAUTHENTICATED La solicitud no incluía credenciales de autenticación válidas. No vuelva a intentarlo sin solucionar el problema.
UNAVAILABLE El servidor de Cloud Firestore devolvió un error. Vuelva a intentar utilizar el retroceso exponencial.