Utiliser l'API REST Firestore

Bien que le moyen le plus simple d'utiliser 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 pour les cas d'utilisation suivants:

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

Si vous utilisez un langage compatible avec gRPC, envisagez d'utiliser l'API RPC plutôt que l'API REST.

Authentification et autorisation

Pour l'authentification, l'API REST Firestore accepte soit un jeton d'ID Firebase Authentication, soit un jeton Google Identity OAuth 2.0. Le jeton que vous fournissez affecte l'autorisation de votre requête:

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

  • Utilisez un jeton OAuth 2.0 Google Identity 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, Firestore utilise Identity and Access Management (IAM) pour déterminer si une requête est autorisée.

Utiliser les jetons d'identification Firebase

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

Récupérer un jeton d'ID Firebase pour effectuer des requêtes au nom de l'utilisateur

Pour les requêtes authentifiées avec un jeton d'ID Firebase et pour les requêtes non authentifiées, Firestore utilise vos règles de sécurité Firestore pour déterminer si une requête est autorisée.

Utiliser les 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 des API Google ou en suivant les étapes décrites dans 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 de Firestore:

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

Si vous authentifiez vos requêtes avec un compte de service et un jeton Google Identity OAuth 2.0, Firestore suppose que vos requêtes agissent pour le compte de votre application plutôt que pour un utilisateur individuel. Firestore autorise ces requêtes à ignorer vos règles de sécurité. Au lieu de cela, Firestore utilise 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 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 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 ayant 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, combinez-le avec l'URL de base de l'API.

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

Le meilleur moyen 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 sur l'API REST ou utilisez API Explorer.

v1.projects.databases.documents

Opérations CRUD sur les documents, semblables à celles décrites dans les guides Ajouter des données ou Obtenir des données.

v1.projects.databases.collectionGroups.indexes

Effectuer des actions sur des index (par exemple, créer d'autres index, désactiver un index existant ou répertorier 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 d'un document, telles que la liste de tous les champs et sous-collections d'un document donné.

Codes d'erreur

Lorsqu'une requête Firestore aboutit, l'API Firestore renvoie un code d'état HTTP 200 OK et les données demandées. Lorsqu'une requête échoue, l'API 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 Firestore. Les SDK et les bibliothèques clientes Firestore peuvent ne pas renvoyer ces mêmes codes d'erreur.

Code d'erreur canonique Description Action recommandée
ABORTED La requête était en conflit avec une autre requête. Pour un commit non transactionnel :
Réessayez la requête ou restructurez votre modèle de données pour réduire les conflits.

Pour les requêtes liées à une transaction :
relancez l'intégralité de la transaction ou restructurez votre modèle de données afin de réduire les conflits.
ALREADY_EXISTS La requête a tenté de créer un document qui existe déjà. N'effectuez pas de nouvelle tentative sans résoudre le problème.
DEADLINE_EXCEEDED Le serveur Firestore qui traite la requête a dépassé un délai. Réessayez avec un intervalle exponentiel entre les tentatives.
FAILED_PRECONDITION La requête ne remplit pas l'une de ses conditions préalables. Par exemple, une requête peut nécessiter un index non défini. Consultez le champ de message dans la réponse d'erreur pour connaître la condition préalable qui a échoué. N'effectuez pas de nouvelle tentative sans résoudre le problème.
INTERNAL Le serveur Firestore a renvoyé une erreur. N'effectuez pas cette nouvelle tentative plusieurs fois.
INVALID_ARGUMENT Un paramètre de requête inclut une valeur non valide. Consultez le champ du message dans la réponse d'erreur pour obtenir la valeur non valide. N'effectuez pas de nouvelle tentative sans résoudre le problème.
NOT_FOUND La requête a tenté de mettre à jour un document qui n'existe pas. N'effectuez pas de nouvelle tentative sans résoudre le problème.
PERMISSION_DENIED L'utilisateur n'est pas autorisé à effectuer cette requête. N'effectuez pas de nouvelle tentative sans résoudre le problème.
RESOURCE_EXHAUSTED Le projet a dépassé son quota ou sa 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 corriger le problème.

Sinon, réessayez avec un intervalle exponentiel entre les tentatives.
UNAUTHENTICATED La requête n'incluait pas d'identifiants valides. N'effectuez pas de nouvelle tentative sans résoudre le problème.
UNAVAILABLE Le serveur Firestore a renvoyé une erreur. Réessayez avec un intervalle exponentiel entre les tentatives.