Usar la API REST de Firestore

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

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

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

Si usas un lenguaje compatible con gRPC, te recomendamos que uses la API RPC en lugar de la API REST.

Autenticación y autorización

Para la autenticación, la API REST de Firestore acepta un token de ID de Firebase Authentication o un token de OAuth 2.0 de Identidad de Google. El token que proporciones afecta a la autorización de tu solicitud:

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

  • Usa un token de OAuth 2.0 de identidad de Google y una cuenta de servicio para autenticar las solicitudes de tu aplicación, como las solicitudes de administración de bases de datos. En estas solicitudes, Firestore usa Gestión de Identidades y Accesos (IAM) para determinar si una solicitud está autorizada.

Trabajar con tokens de ID de Firebase

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

Si obtienes el token de ID de Firebase de un usuario, puedes hacer solicitudes en su nombre.

En el caso de las solicitudes autenticadas con un token de ID de Firebase y de las solicitudes no autenticadas, Firestore usa tus reglas de seguridad de Firestore para determinar si una solicitud está autorizada.

Trabajar con tokens de OAuth 2.0 de identidad de Google

Puedes generar un token de acceso mediante una cuenta de servicio con una biblioteca de cliente de la API de Google o siguiendo los pasos que se indican en el artículo Usar 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 ámbito para enviar solicitudes a la API REST de Firestore:

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

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

Puedes controlar los permisos de acceso de las cuentas de servicio asignando roles de gestión de identidades y accesos de Firestore.

Autenticarse con un token de acceso

Una vez que hayas obtenido un token de ID de Firebase o un token de OAuth 2.0 de identidad de Google, envíalo a los endpoints de Firestore como un encabezado Authorization definido como Bearer {YOUR_TOKEN}.

Hacer llamadas REST

Todos los endpoints de la API REST se encuentran en 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, usarías 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 forma de empezar a experimentar con la API REST es usar el Explorador de APIs, que genera automáticamente tokens de Google Identity OAuth 2.0 y te permite examinar la API.

Métodos

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

v1.projects.databases.documents

Realizar operaciones CRUD en documentos, similares a las que se describen en las guías para añadir datos o obtener datos.

v1.projects.databases.collectionGroups.indexes

Realizar acciones en los índices, como crear índices, inhabilitar un índice o mostrar todos los índices actuales. Útil para automatizar migraciones de estructuras de datos o sincronizar índices entre proyectos.

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

Códigos de error

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

En la siguiente tabla se indican las acciones recomendadas para cada código de error. Estos códigos se aplican a las APIs REST y RPC de Firestore. Es posible que los SDKs y las bibliotecas de cliente de Firestore no devuelvan estos mismos códigos de error.

Código de error canónico Descripción Acción recomendada
ABORTED La solicitud entraba en conflicto con otra. En el caso de una confirmación no transaccional:
vuelve a intentar la solicitud o reestructura tu modelo de datos para reducir la contención.

En el caso de las solicitudes de una transacción:
vuelve a intentar toda la transacción o reestructura tu modelo de datos para reducir la contención.
ALREADY_EXISTS La solicitud ha intentado crear un documento que ya existe. No vuelvas a intentarlo sin solucionar el problema.
DEADLINE_EXCEEDED El servidor de Firestore que gestiona la solicitud ha superado el plazo. Vuelve a intentarlo con un tiempo de espera exponencial.
FAILED_PRECONDITION La solicitud no ha cumplido una de sus condiciones previas. Por ejemplo, una solicitud de consulta puede requerir un índice que aún no se ha definido. Consulta el campo message de la respuesta de error para ver la condición previa que no se ha cumplido. No vuelvas a intentarlo sin solucionar el problema.
INTERNAL El servidor de Firestore ha devuelto un error. No vuelva a intentar enviar esta solicitud más de una vez.
INVALID_ARGUMENT Un parámetro de solicitud incluye un valor no válido. Consulta el campo de mensaje de la respuesta de error para ver el valor no válido. No vuelvas a intentarlo sin solucionar el problema.
NOT_FOUND La solicitud ha intentado actualizar un documento que no existe. No vuelvas a intentarlo sin solucionar el problema.
PERMISSION_DENIED El usuario no tiene autorización para hacer esta solicitud. No vuelvas a intentarlo sin solucionar el problema.
RESOURCE_EXHAUSTED El proyecto ha superado su cuota o la capacidad de la región o multirregión. Comprueba que no hayas superado la cuota de tu proyecto. Si has superado la cuota de un proyecto, no vuelvas a intentarlo sin solucionar el problema.

De lo contrario, vuelve a intentarlo con un tiempo de espera exponencial.
UNAUTHENTICATED La solicitud no incluía credenciales de autenticación válidas. No vuelvas a intentarlo sin solucionar el problema.
UNAVAILABLE El servidor de Firestore ha devuelto un error. Vuelve a intentarlo con un tiempo de espera exponencial.