Si bien la forma más fácil de usar Cloud Firestore es mediante una de las bibliotecas cliente nativas, en algunas situaciones es útil llamar directamente a la API de REST.
La API de REST puede ser útil en los siguientes casos de uso:
- Para acceder a Cloud 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 Cloud 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 tu solicitud:
Usa los tokens de ID de Firebase para autenticar solicitudes de los usuarios de tu aplicación. Para estas solicitudes, Cloud Firestore utiliza reglas de seguridad de Cloud Firestore a fin de determinar si se autoriza una solicitud.
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, Cloud Firestore utiliza Identity and Access Management (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:
- Generar un token de ID de Firebase usando la API de REST de Firebase Authentication.
- Recuperar el token de ID de Firebase de un usuario a partir de un SDK de Firebase Authentication.
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 de solicitudes no autenticadas, Cloud Firestore utiliza tus reglas de seguridad de Cloud Firestore para determinar si se autoriza una solicitud.
Trabajar 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 Cloud 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, Cloud Firestore supone que tus solicitudes actúan en nombre de tu aplicación y no de un usuario individual. Cloud Firestore permite que estas solicitudes pasen por alto tus reglas de seguridad. En cambio, Cloud Firestore usa IAM para determinar si se autoriza una solicitud.
Puedes controlar los permisos de acceso de las cuentas de servicio asignando roles de IAM de Cloud 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 Cloud 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 Cloud Firestore se realiza correctamente, la API de Cloud Firestore muestra un código de estado HTTP 200 OK y los datos solicitados. Cuando una solicitud falla, la API de Cloud 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 APIs de REST y RPC de Cloud Firestore. Es posible que los SDK y las bibliotecas cliente de Cloud 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 Cloud Firestore a cargo de la solicitud superó un límite. | Vuelve a intentarlo con 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 Cloud 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 Cloud Firestore mostró un error. | Vuelve a intentarlo con una retirada exponencial. |