Bien que la méthode la plus simple pour 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 dans les cas d'utilisation suivants :
- Accéder à 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 de 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, Firestore utilise les règles de sécurité de Firestore 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, 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 :
- Générer un jeton d'identification Firebase à l'aide de l'API REST de Firebase Authentication.
- Extraire le jeton d'identification Firebase d'un utilisateur à partir d'un SDK Firebase Authentication.
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, Firestore utilise vos règles de sécurité Firestore 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 de 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, Firestore suppose que vos requêtes agissent au nom de votre application et non d'un utilisateur individuel. Firestore autorise ces requêtes à ignorer vos règles de sécurité. À la place, 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.
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 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 Firestore aboutit, l'API de Firestore renvoie un code d'état HTTP 200 OK avec les données demandées. Lorsqu'une requête échoue, l'API de 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 REST et RPC de Firestore. Les SDK et les bibliothèques clientes de 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 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 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 Firestore a renvoyé une erreur. | Relancez la requête avec un intervalle exponentiel entre les tentatives. |