Usa la API de REST de Firestore

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

La API de REST puede ser útil en los siguientes casos prácticos:

  • Para acceder a Firestore desde un entorno con recursos restringidos, como un dispositivo de la Internet de las cosas (IoT), caso en el que no es posible ejecutar una biblioteca cliente completa
  • Para automatizar la administración de la base de datos o recuperar metadatos detallados de la base de datos

Si estás usando un lenguaje compatible con gRPC, te recomendamos usar la API de RPC en lugar de la de REST.

Autenticación y autorización

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

  • Usa los tokens de ID de Firebase para autenticar solicitudes de los usuarios de la aplicación. Para estas solicitudes, Firestore usa reglas de seguridad de Firestore a fin de determinar si una solicitud está autorizada.

  • Usa un token de Google Identity OAuth 2.0 y una cuenta de servicio para autenticar solicitudes de tu aplicación, como solicitudes de administración de base de datos. Para estas solicitudes, Firestore usa la Administración de identidades y accesos (IAM) a fin de determinar si se autoriza una solicitud.

Trabaja con tokens de ID de Firebase

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

Si recuperas el token de ID de Firebase de un usuario, puedes realizar solicitudes en nombre del usuario.

En los casos de solicitudes autenticadas con un token de ID de Firebase y solicitudes no autenticadas, Firestore usa las reglas de seguridad de Firestore para determinar si se autoriza una solicitud.

Trabaja con tokens de Google Identity OAuth 2.0

Para generar un token de acceso, usa una cuenta de servicio con una biblioteca cliente de la API de Google, o bien sigue los pasos que se indican en Cómo usar OAuth 2.0 para aplicaciones de servidor a servidor. También puedes generar un token con la herramienta de línea de comandos de gcloud y el comando gcloud auth application-default print-access-token.

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

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

Si autenticas las solicitudes con una cuenta de servicio y un token de Google Identity OAuth 2.0, Firestore supone que las solicitudes actúan en nombre de la aplicación y no de un usuario individual. Firestore permite que estas solicitudes pasen por alto las reglas de seguridad. En cambio, Firestore usa IAM para determinar si se autoriza una solicitud.

Puedes controlar los permisos de acceso de las cuentas de servicio si asignas funciones de IAM de Firestore.

Autentica con un token de acceso

Una vez que hayas obtenido un token de ID de Firebase o un token de Google Identity OAuth 2.0, pásalo a los extremos de Firestore como un encabezado de Authorization configurado como Bearer {YOUR_TOKEN}.

Haz llamadas de REST

Todos los extremos de la API de REST existen asociados a la URL base https://firestore.googleapis.com/v1/.

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

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

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

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

La mejor manera de comenzar a experimentar con la API de REST es usar el Explorador de API, que genera automáticamente tokens de Google Identity OAuth 2.0 y te permite examinar la API.

Métodos

A continuación, se describen brevemente los dos grupos de métodos más importantes. Para ver una lista completa, consulta la referencia de la API de REST o usa el Explorador de API.

v1.projects.databases.documents

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

v1.projects.databases.collectionGroups.indexes

Realiza acciones relacionadas con índices, tales como crear índices, inhabilitar índices existentes o mostrar una lista de los índices actuales. Este método es útil para automatizar migraciones de estructuras de datos o para sincronizar índices entre proyectos.

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

Códigos de error

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

En la siguiente tabla, se enumeran las acciones recomendadas para cada código de error. Estos códigos se aplican a las API de REST y RPC de Firestore. Es posible que los SDK y las bibliotecas cliente de Firestore no muestren los mismos códigos de error.

Código de error canónico Descripción Acción recomendada
ABORTED La solicitud entró en conflicto con otra. Para una confirmación no transaccional:
Reintenta la solicitud o estructura tu modelo de datos a fin de reducir la contención.

Para solicitudes de una transacción:
Vuelve a intentar la transacción completa o estructura tu modelo de datos a fin de reducir la contención.
ALREADY_EXISTS La solicitud intentó crear un documento que ya existe. No vuelvas a intentar la operación sin solucionar el problema.
DEADLINE_EXCEEDED El servidor de Firestore a cargo de la solicitud superó una fecha límite. Vuelve a intentarlo mediante una retirada exponencial.
FAILED_PRECONDITION La solicitud no cumplió con una de sus condiciones previas. Por ejemplo, una solicitud de consulta puede requerir un índice aún no definido. Consulta el campo del mensaje en la respuesta del error para ver la condición previa que falló. No vuelvas a intentar la operación sin solucionar el problema.
INTERNAL El servidor de Firestore mostró un error. No vuelvas a intentar esta solicitud más de una vez.
INVALID_ARGUMENT Un parámetro de la solicitud incluye un valor no válido. Consulta el campo de mensaje en la respuesta del error para ver el valor no válido. No vuelvas a intentar la operación sin solucionar el problema.
NOT_FOUND La solicitud intentó actualizar un documento que no existe. No vuelvas a intentar la operación sin solucionar el problema.
PERMISSION_DENIED El usuario no tiene autorización para realizar esta solicitud. No vuelvas a intentar la operación sin solucionar el problema.
RESOURCE_EXHAUSTED El proyecto superó su cuota o la capacidad regional o multirregional. Verifica que no superaste la cuota del proyecto. Si superaste la cuota de un proyecto, no lo intentes de nuevo sin solucionar el problema.

De lo contrario, vuelve a intentarlo con la retirada exponencial.
UNAUTHENTICATED La solicitud no incluía credenciales de autenticación válidas. No vuelvas a intentar la operación sin solucionar el problema.
UNAVAILABLE El servidor de Firestore mostró un error. Vuelve a intentarlo mediante una retirada exponencial.