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 est parfois utile d'appeler directement l'API REST.

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

  • Accéder à Cloud Firestore à partir d'un environnement à ressources limitées, tel qu'un appareil IoT (Internet of Things), où l'exécution d'une bibliothèque cliente complète n'est pas possible.
  • Automatiser l'administration de la base de données ou récupérer des métadonnées de base de données détaillées.

Si vous utilisez un langage compatible avec gRPC, pensez à 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 Firebase Authentication, soit un jeton Google Identity OAuth 2.0. Le jeton que vous fournissez a une incidence sur l'autorisation de votre requête :

  • Utilisez des jetons d'identification Firebase pour authentifier les requêtes des utilisateurs de votre application. Pour ces requêtes, Cloud Firestore utilise Cloud Firestore Security Rules pour déterminer si une requête est autorisée.

  • Utilisez un jeton Google Identity OAuth 2.0 et un compte de service pour authentifier les requêtes de votre application, telles que les requêtes d'administration de base de données. Pour ces requêtes, Cloud Firestore utilise Identity and Access Management (IAM) pour déterminer si une requête est autorisée.

Utilisation des jetons d'identification Firebase

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

En extrayant le jeton d'identification Firebase d'un utilisateur, vous pouvez effectuer des requêtes au nom de l'utilisateur.

Pour les requêtes authentifiées avec un jeton d'identification Firebase et pour les requêtes non authentifiées, Cloud Firestore utilise votre Cloud Firestore Security Rules pour déterminer si une requête est autorisée.

Utilisation des jetons Google Identity OAuth 2.0

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

Ce jeton doit avoir le champ d'application suivant pour envoyer des requêtes à l'API REST Cloud Firestore :

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

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

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

Authentification 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}.

Effectuer 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 d'accès à un document avec l'ID LA dans la collection cities sous le projet YOUR_PROJECT_ID, utilisez la structure suivante.

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

Pour interagir avec ce chemin, associez-le à l'URL d'API de base.

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

La meilleure façon de commencer à tester l'API REST consiste à utiliser 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 une brève description des deux groupes de méthodes les plus importants. Pour obtenir la liste complète, consultez la documentation de référence de l'API REST ou utilisez API Explorer.

v1.projects.databases.documents

Cette méthode permet d'exécuter des opérations CRUD sur des documents, similaires à celles décrites dans les guides add data ou get data.

v1.projects.databases.collectionGroups.indexes

Cette méthode permet d'effectuer des actions sur les index, telles que la création de nouveaux index, la désactivation d'un index existant ou l'affichage de tous les index actuels. Elle est utile pour automatiser les migrations de structure de données ou synchroniser des index entre projets.

Elle permet également de récupérer des métadonnées de 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 aboutit, l'API Cloud Firestore renvoie un code d'état HTTP 200 OK avec les données demandées. En cas d'échec d'une requête, l'API Cloud Firestore renvoie un code d'état HTTP 4xx ou 5xx, ainsi qu'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 REST et RPC de Cloud Firestore. Les SDK et bibliothèques clientes Cloud Firestore risquent de ne pas renvoyer ces mêmes codes d'erreur.

Code d'erreur canonique Description Action recommandée
ABORTED La requête est en conflit avec une autre requête. Pour une validation non transactionnelle :
réessayez la requête ou restructurez votre modèle de données pour réduire la contention.

Pour les requêtes dans une transaction :
réessayez l'intégralité de la transaction ou restructurez votre modèle de données afin de réduire la contention.
ALREADY_EXISTS La requête a tenté de créer un document qui existe déjà. Ne relancez pas la requête avant d'avoir résolu le problème.
DEADLINE_EXCEEDED Le serveur Cloud Firestore qui traite la requête a dépassé un délai. Relancez la requête avec un intervalle exponentiel entre les tentatives.
FAILED_PRECONDITION La requête ne remplissait pas l'une de ses conditions préalables. Par exemple, une requête peut nécessiter un index qui n'est pas encore défini. Reportez-vous au champ de message dans la réponse d'erreur pour afficher la précondition qui a échoué. Ne relancez pas la requête avant d'avoir résolu le problème.
INTERNAL Le serveur Cloud Firestore a renvoyé une erreur. Ne relancez pas cette requête plus d'une fois.
INVALID_ARGUMENT Un paramètre de requête inclut une valeur non valide. Reportez-vous au champ de message dans la réponse d'erreur pour afficher la valeur non valide. Ne relancez pas la requête avant d'avoir résolu le problème.
NOT_FOUND La demande a tenté de mettre à jour un document qui n'existe pas. Ne relancez pas la requête avant d'avoir résolu le problème.
PERMISSION_DENIED L'utilisateur n'est pas autorisé à effectuer cette requête. Ne relancez pas la requête avant d'avoir résolu le problème.
RESOURCE_EXHAUSTED Le projet a dépassé son quota ou la capacité régionale/multi-ré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 relancez pas la requête avant d'avoir résolu le problème.

Sinon, relancez la requête avec un intervalle exponentiel entre les tentatives.
UNAUTHENTICATED La requête n'inclut pas d'identifiants d'authentification valides. Ne relancez pas la requête avant d'avoir résolu le problème.
UNAVAILABLE Le serveur Cloud Firestore a renvoyé une erreur. Relancez la requête avec un intervalle exponentiel entre les tentatives.