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:
- Générez un jeton d'identification Firebase à l'aide de l'API REST Firebase Authentication.
- Récupérez un jeton d'ID Firebase pour un utilisateur à partir d'un SDK Firebase Authentication.
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. |