Utiliser l'API REST de Cloud Firestore

Bien que le moyen le plus simple d'utiliser Cloud Firestore consiste à utiliser l'une des bibliothèques clientes natives, il existe certaines situations dans lesquelles il est utile d'appeler directement l'API REST.

L'API REST peut être utile pour les cas d'utilisation suivants :

Accéder à Cloud Firestore à partir d'un environnement aux ressources limitées, tel qu'un appareil Internet des objets (IoT), où l'exécution d'une bibliothèque client complète n'est pas possible.
Automatisation de l'administration de bases de données ou récupération de métadonnées détaillées de bases de données.

Si vous utilisez un langage pris en charge par gRPC , envisagez d'utiliser l' API RPC plutôt que l'API REST.

Authentification et autorisation

Pour l'authentification, l'API REST Cloud Firestore accepte soit un jeton d'identification d'authentification Firebase , soit un jeton Google Identity OAuth 2.0 . Le jeton que vous fournissez affecte l'autorisation de votre demande :

Utilisez les jetons d'identification Firebase pour authentifier les demandes des utilisateurs de votre application. Pour ces demandes, Cloud Firestore utilise les règles de sécurité Cloud Firestore pour déterminer si une demande est autorisée.
Utilisez un jeton Google Identity OAuth 2.0 et un compte de service pour authentifier les demandes de votre application, telles que les demandes d'administration de base de données. Pour ces demandes, Cloud Firestore utilise la gestion des identités et des accès (IAM) pour déterminer si une demande est autorisée.

Travailler avec des jetons d'identification Firebase

Vous pouvez obtenir un jeton d'identification Firebase de deux manières :

En récupérant le jeton d'identification Firebase d'un utilisateur, vous pouvez effectuer des demandes au nom de l'utilisateur.

Pour les demandes authentifiées avec un jeton d'identification Firebase et pour les demandes non authentifiées, Cloud Firestore utilise vos règles de sécurité Cloud Firestore pour déterminer si une demande est autorisée.

Travailler avec les jetons Google Identity OAuth 2.0

Vous pouvez générer un jeton d'accès en utilisant un compte de service avec une bibliothèque cliente d'API Google ou en suivant les étapes décrites dans Utilisation d'OAuth 2.0 pour les applications serveur à serveur . Vous pouvez également générer un jeton avec l'outil de ligne de commande gcloud et la commande gcloud auth application-default print-access-token .

Ce jeton doit avoir la portée suivante pour envoyer des requêtes à l'API REST Cloud Firestore :

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

Si vous authentifiez vos demandes avec un compte de service et un jeton Google Identity OAuth 2.0, Cloud Firestore suppose que vos demandes agissent au nom de votre application et non d'un utilisateur individuel. Cloud Firestore permet à ces requêtes d'ignorer vos règles de sécurité. Au lieu de cela, Cloud Firestore utilise IAM pour déterminer si une demande est autorisée.

Vous pouvez contrôler les autorisations d'accès des comptes de service en attribuant des rôles IAM Cloud Firestore .

S'authentifier avec un jeton d'accès

Après avoir obtenu un jeton d'identification Firebase ou un jeton Google Identity OAuth 2.0, transmettez-le aux points de terminaison Cloud Firestore en tant qu'en-tête Authorization défini sur Bearer {YOUR_TOKEN} .

Passer des appels REST

Tous les points de terminaison de l'API REST existent sous l'URL de base https://firestore.googleapis.com/v1/ .

Pour créer un chemin vers un document avec l'ID LA dans les cities de collecte sous le projet YOUR_PROJECT_ID vous utiliserez la structure suivante.

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

Pour interagir avec ce chemin, combinez-le avec l'URL de l'API de base.

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

La meilleure façon de commencer à expérimenter l'API REST est d'utiliser l' API Explorer , qui génère automatiquement des jetons Google Identity OAuth 2.0 et vous permet d'examiner l'API.

Méthodes

Vous trouverez ci-dessous de brèves descriptions des deux groupes de méthodes les plus importants. Pour une liste complète, consultez la référence de l'API REST ou utilisez l' API Explorer .

`v1.projects.databases.documents`

Effectuez des opérations CRUD sur les documents, similaires à celles décrites dans les guides d'ajout de données ou d'obtention de données .

`v1.projects.databases.collectionGroups.indexes`

Effectuez des actions sur les index, telles que la création de nouveaux index, la désactivation d'un index existant ou la liste de tous les index actuels. Utile pour automatiser les migrations de structures de données ou synchroniser les index entre les projets.

Permet également de récupérer les métadonnées du document, telles que la liste de tous les champs et sous-collections d'un document donné.

Codes d'erreur

Lorsqu'une requête Cloud Firestore réussit, l'API Cloud Firestore renvoie un code d'état HTTP 200 OK et les données demandées. Lorsqu'une requête échoue, l'API Cloud Firestore renvoie un code d'état HTTP 4xx ou 5xx et une réponse contenant des informations sur l'erreur.

Le tableau suivant répertorie les actions recommandées pour chaque code d'erreur. Ces codes s'appliquent aux API Cloud Firestore REST et RPC. Les SDK Cloud Firestore et les bibliothèques clientes peuvent ne pas renvoyer ces mêmes codes d'erreur.

Code d'erreur canonique	Description	Action recommandée
`ABORTED`	La demande est en conflit avec une autre demande.	Pour un commit non transactionnel : Réessayez la demande ou restructurez votre modèle de données pour réduire les conflits. Pour les demandes dans une transaction : Réessayez l'intégralité de la transaction ou restructurez votre modèle de données pour réduire les conflits.
`ALREADY_EXISTS`	La demande a tenté de créer un document qui existe déjà.	Ne réessayez pas sans résoudre le problème.
`DEADLINE_EXCEEDED`	Le serveur Cloud Firestore traitant la demande a dépassé un délai.	Réessayez en utilisant l'intervalle exponentiel.
`FAILED_PRECONDITION`	La demande ne remplissait pas l'une de ses conditions préalables. Par exemple, une requête de requête peut nécessiter un index non encore défini. Consultez le champ de message dans la réponse d’erreur pour connaître la condition préalable qui a échoué.	Ne réessayez pas sans résoudre le problème.
`INTERNAL`	Le serveur Cloud Firestore a renvoyé une erreur.	Ne réessayez pas cette demande plus d'une fois.
`INVALID_ARGUMENT`	Un paramètre de requête inclut une valeur non valide. Consultez le champ de message dans la réponse d’erreur pour connaître la valeur non valide.	Ne réessayez pas sans résoudre le problème.
`NOT_FOUND`	La demande a tenté de mettre à jour un document qui n'existe pas.	Ne réessayez pas sans résoudre le problème.
`PERMISSION_DENIED`	L'utilisateur n'est pas autorisé à faire cette demande.	Ne réessayez pas sans résoudre le problème.
`RESOURCE_EXHAUSTED`	Le projet a dépassé soit son quota , soit la capacité régionale/multirégionale.	Vérifiez que vous n'avez pas dépassé le quota de votre projet . Si vous avez dépassé le quota d'un projet, ne réessayez pas sans résoudre le problème. Sinon, réessayez avec une interruption exponentielle.
`UNAUTHENTICATED`	La demande n'incluait pas d'informations d'authentification valides.	Ne réessayez pas sans résoudre le problème.
`UNAVAILABLE`	Le serveur Cloud Firestore a renvoyé une erreur.	Réessayez en utilisant l'intervalle exponentiel.