Utilisation de l'API
Vous pouvez utiliser n'importe quelle URL de base de données en temps réel Firebase comme point de terminaison REST. Tout ce que vous avez à faire est d'ajouter .json
à la fin de l'URL et d'envoyer une requête depuis votre client HTTPS préféré.
HTTPS est requis. Firebase répond uniquement au trafic chiffré afin que vos données restent en sécurité.
GET - Lecture des données
Les données de votre base de données en temps réel peuvent être lues en envoyant une requête HTTP GET
à un point de terminaison. L'exemple suivant montre comment récupérer le nom d'un utilisateur que vous aviez précédemment stocké dans Realtime Database.
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
Une requête réussie est indiquée par un code d'état HTTP 200 OK
. La réponse contient les données associées au chemin dans la requête GET
.
{ "first": "Jack", "last": "Sparrow" }
PUT - Écriture de données
Vous pouvez écrire des données avec une requête PUT
.
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
Une requête réussie est indiquée par un code d'état HTTP 200 OK
. La réponse contient les données spécifiées dans la requête PUT
.
{ "first": "Jack", "last": "Sparrow" }
POST - Transmission de données
Pour accomplir l'équivalent de la méthode JavaScript push()
(voir Lists of Data ), vous pouvez émettre une requête POST
.
curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \ 'https://[PROJECT_ID].firebaseio.com/message_list.json'
Une requête réussie est indiquée par un code d'état HTTP 200 OK
. La réponse contient le nom enfant des nouvelles données spécifiées dans la requête POST
.
{ "name": "-INOQPH-aV_psbk3ZXEX" }
PATCH - Mise à jour des données
Vous pouvez mettre à jour des enfants spécifiques à un emplacement sans écraser les données existantes à l'aide d'une requête PATCH
. Les enfants nommés dans les données écrites avec PATCH
sont écrasés, mais les enfants omis ne sont pas supprimés. Ceci est équivalent à la fonction JavaScript update()
.
curl -X PATCH -d '{"last":"Jones"}' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'
Une requête réussie est indiquée par un code d'état HTTP 200 OK
. La réponse contient les données spécifiées dans la requête PATCH
.
{ "last": "Jones" }
SUPPRIMER - Suppression de données
Vous pouvez supprimer des données avec une requête DELETE
:
curl -X DELETE \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
Une demande DELETE
réussie est indiquée par un code d'état HTTP 200 OK
avec une réponse contenant JSON null
.
Remplacement de méthode
Si vous effectuez des appels REST à partir d'un navigateur qui ne prend pas en charge les méthodes précédentes, vous pouvez remplacer la méthode de requête en effectuant une requête POST
et en définissant votre méthode à l'aide de l'en-tête de requête X-HTTP-Method-Override
.
curl -X POST -H "X-HTTP-Method-Override: DELETE" \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
Vous pouvez également utiliser le paramètre de requête x-http-method-override
.
curl -X POST \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'
Demandes conditionnelles
Les requêtes conditionnelles, l'équivalent REST des opérations de transaction du SDK, mettent à jour les données selon une certaine condition. Consultez une présentation du flux de travail et apprenez-en plus sur les demandes conditionnelles pour REST dans Sauvegarde des données .
Étiquette ETag Firebase
Le Firebase ETag est l'identifiant unique des données actuelles à un emplacement spécifié. Si les données changent à cet emplacement, l'ETag change également. Le Firebase ETag doit être spécifié dans l'en-tête de la requête REST initiale (généralement un GET
, mais peut être autre chose que PATCH
).
curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
si-match
La condition if-match
spécifie la valeur ETag pour les données que vous souhaitez mettre à jour. Si vous utilisez la condition, Realtime Database termine uniquement les requêtes pour lesquelles l'ETag spécifié dans la demande d'écriture correspond à l'ETag des données existantes dans la base de données. Récupérez l'ETag à un emplacement avec une requête Firebase ETag. Si vous souhaitez écraser un emplacement nul, utilisez null_etag
.
curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'
Réponses attendues
Le tableau suivant donne un aperçu des réponses attendues pour chaque type de demande, en fonction de la correspondance ETag.
type de demande | 'X-Firebase-ETag : vrai' | Correspondances ETagif_match: <matching etag> | ETag ne correspond pasif_match: <no matching etag> | |
---|---|---|---|---|
OBTENIR | Statut/Contenu de la réponse | 200 : "<data_at_path>" | 400 : "...non pris en charge.." | 400 : "...non pris en charge.." |
En-têtes ajoutés | ETag : <ETag_of_data> | N / A | N / A | |
METTRE | Statut/Contenu de la réponse | 200 : "<put_data>" | 200 : "<put_data>" | 412 : "... Incompatibilité ETag.." |
En-têtes ajoutés | ETag : <ETag_of_put_data> | N / A | ETag : <base_de_données_ETag> | |
POSTE | Statut/Contenu de la réponse | 200 : "<données_post>" | 400 : "...non pris en charge.." | 400 : "...non pris en charge.." |
En-têtes ajoutés | ETag : <ETag_of_post_data> | N / A | N / A | |
CORRECTIF | Statut/Contenu de la réponse | 400 : "...non pris en charge.." | 400 : "...non pris en charge.." | 400 : "...non pris en charge.." |
En-têtes ajoutés | N / A | N / A | N / A | |
SUPPRIMER | Statut/Contenu de la réponse | 200 : nul | 200 : "<data_after_put>" | 412 : "... Incompatibilité ETag.." |
En-têtes ajoutés | ETag : <ETag_of_null> | N / A | ETag : <base_de_données_ETag> |
Paramètres de requête
L'API REST de Firebase Database accepte les paramètres et valeurs de requête suivants :
jeton d'accès
Pris en charge par tous les types de requêtes. Authentifie cette demande pour autoriser l'accès aux données protégées par les règles de sécurité de la base de données en temps réel Firebase. Consultez la documentation sur l'authentification REST pour plus de détails.
curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'
peu profond
Il s'agit d'une fonctionnalité avancée, conçue pour vous aider à travailler avec de grands ensembles de données sans avoir besoin de tout télécharger. Définissez ceci sur true
pour limiter la profondeur des données renvoyées à un emplacement. Si les données à l'emplacement sont une primitive JSON (chaîne, nombre ou booléen), sa valeur sera simplement renvoyée. Si l'instantané de données à l'emplacement est un objet JSON, les valeurs de chaque clé seront tronquées à true
.
Arguments | Méthodes REST | Description |
---|---|---|
peu profond | OBTENIR | Limitez la profondeur de la réponse. |
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'
Notez que shallow
ne peut pas être mélangé avec d’autres paramètres de requête.
imprimer
Formate les données renvoyées dans la réponse du serveur.
Arguments | Méthodes REST | Description |
---|---|---|
joli | OBTENIR, METTRE, POSTER, CORRIGER, SUPPRIMER | Affichez les données dans un format lisible par l'homme. |
silencieux | OBTENIR, METTRE, POSTER, CORRIGER | Utilisé pour supprimer la sortie du serveur lors de l'écriture de données. La réponse résultante sera vide et indiquée par un code d'état HTTP 204 No Content . |
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'
rappeler
Pris en charge par GET
uniquement. Pour effectuer des appels REST à partir d'un navigateur Web sur plusieurs domaines, vous pouvez utiliser JSONP pour envelopper la réponse dans une fonction de rappel JavaScript. Ajoutez callback=
pour que l'API REST encapsule les données renvoyées dans la fonction de rappel que vous spécifiez.
<script> function gotData(data) { console.log(data); } </script> <script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>
format
S'il est défini sur export
, le serveur encodera les priorités dans la réponse.
Arguments | Méthodes REST | Description |
---|---|---|
exporter | OBTENIR | Incluez des informations prioritaires dans la réponse. |
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'
télécharger
Pris en charge par GET
uniquement. Si vous souhaitez déclencher un téléchargement de fichier de vos données depuis un navigateur Web, ajoutez download=
. Cela amène le service REST à ajouter les en-têtes appropriés afin que les navigateurs sachent enregistrer les données dans un fichier.
curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'
temps mort
Utilisez-le pour limiter la durée de la lecture côté serveur. Si une demande de lecture ne se termine pas dans le temps imparti, elle se termine par une erreur HTTP 400. Ceci est particulièrement utile lorsque vous prévoyez un petit transfert de données et que vous ne voulez pas attendre trop longtemps pour récupérer un sous-arbre potentiellement volumineux. Le temps de lecture réel peut varier en fonction de la taille des données et de la mise en cache.
Spécifiez timeouts
en utilisant le format suivant : 3ms
, 3s
ou 3min
, avec un nombre et une unité. S’il n’est pas précisé, le timeout
maximum de 15min
sera appliqué. Si le timeout
n'est pas positif ou dépasse le maximum, la requête sera rejetée avec une erreur HTTP 400.
writeSizeLimit
Pour limiter la taille d'une écriture, vous pouvez spécifier le paramètre de requête writeSizeLimit
comme étant tiny
(target=1s), small
(target=10s), medium
(target=30s), large
(target=60s). Realtime Database estime la taille de chaque demande d'écriture et abandonne les demandes qui prendront plus de temps que le temps cible.
Si vous spécifiez unlimited
, des écritures exceptionnellement volumineuses (avec une charge utile allant jusqu'à 256 Mo) sont autorisées, bloquant potentiellement les requêtes ultérieures pendant que la base de données traite l'opération en cours. Les écritures ne peuvent pas être annulées une fois qu'elles atteignent le serveur.
curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'
Vous verrez le message d'erreur suivant si l'écriture est trop volumineuse :
Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.
De plus, vous pouvez définir la defaultWriteSizeLimit
pour l'ensemble de l'instance de base de données à l'aide de la CLI Firebase. Cette limite s'applique à toutes les requêtes, y compris celles provenant des SDK. De nouvelles bases de données sont créées avec defaultWriteSizeLimit
défini sur large
. Vous ne pouvez pas définir defaultWriteSizeLimit
sur tiny
à l'aide de la CLI Firebase.
firebase database:settings:set defaultWriteSizeLimit large
commandé par
Consultez la section du guide sur les données commandées pour plus d'informations.
limitToFirst, limitToLast, startAt, endAt, égal à
Consultez la section du guide sur le filtrage des données pour plus d'informations.
Streaming depuis l'API REST
Les points de terminaison Firebase REST prennent en charge le protocole EventSource/Server-Sent Events . Pour diffuser les modifications vers un seul emplacement de votre base de données en temps réel, vous devez effectuer plusieurs opérations :
- Définissez l'en-tête Accept du client sur
"text/event-stream"
- Respectez les redirections HTTP, en particulier le code d'état HTTP 307
- Si l'emplacement nécessite une autorisation de lecture, vous devez inclure le paramètre
auth
En retour, le serveur enverra des événements nommés à mesure que l'état des données à l'URL demandée change. La structure de ces messages est conforme au protocole EventSource
.
event: event name data: JSON encoded data payload
Le serveur peut envoyer les événements suivants :
mettre
Les données codées en JSON sont un objet avec deux clés : path et data . La clé de chemin pointe vers un emplacement par rapport à l’URL de la demande. Le client doit remplacer toutes les données de cet emplacement dans son cache par data .
correctif
Les données codées en JSON sont un objet avec deux clés : path et data . La clé de chemin pointe vers un emplacement par rapport à l’URL de la demande. Pour chaque clé dans data , le client doit remplacer la clé correspondante dans son cache par les données de cette clé dans le message.
rester en vie
Les données de cet événement sont null
. Aucune action n'est requise.
Annuler
Certaines erreurs inattendues peuvent envoyer un événement « annuler » et mettre fin à la connexion. La cause est décrite dans les données fournies pour cet événement. Certaines causes potentielles sont les suivantes : 1. Les règles de sécurité de la base de données en temps réel Firebase n'autorisent plus la lecture à l'emplacement demandé. La description des « données » pour cette cause est « Autorisation refusée ». 2. Une écriture a déclenché un streamer d'événements qui a envoyé une grande arborescence JSON dépassant notre limite, 512 Mo. Les « données » pour cette cause sont « La charge utile spécifiée est trop volumineuse, veuillez demander un emplacement avec moins de données. »
auth_revoked
Les données de cet événement sont une chaîne indiquant que les informations d'identification ont expiré. Cet événement est envoyé lorsque le paramètre auth
fourni n'est plus valide.
Voici un exemple d'ensemble d'événements que le serveur peut envoyer :
// Set your entire cache to {"a": 1, "b": 2} event: put data: {"path": "/", "data": {"a": 1, "b": 2}} // Put the new data in your cache under the key 'c', so that the complete cache now looks like: // {"a": 1, "b": 2, "c": {"foo": true, "bar": false}} event: put data: {"path": "/c", "data": {"foo": true, "bar": false}} // For each key in the data, update (or add) the corresponding key in your cache at path /c, // for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}} event: patch data: {"path": "/c", "data": {"foo": 3, "baz": 4}}
Priorités
Les informations de priorité pour un emplacement peuvent être référencées avec un « enfant virtuel » nommé .priority
. Vous pouvez lire les priorités avec les requêtes GET
et les écrire avec les requêtes PUT
. Par exemple, la requête suivante récupère la priorité du nœud users/tom
:
curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'
Pour écrire la priorité et les données en même temps, vous pouvez ajouter un enfant .priority
à la charge utile JSON :
curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom.json'
Pour écrire une priorité et une valeur primitive (par exemple une chaîne) en même temps, vous pouvez ajouter un enfant .priority
et mettre la valeur primitive dans un enfant .value
:
curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'
Ceci écrit "Tom"
avec une priorité de 1.0
. Les priorités peuvent être incluses à n’importe quelle profondeur dans la charge utile JSON.
Valeurs du serveur
Vous pouvez écrire des valeurs de serveur à un emplacement à l'aide d'une valeur d'espace réservé qui est un objet avec une seule clé .sv
. La valeur de cette clé correspond au type de valeur de serveur que vous souhaitez définir. Par exemple, la requête suivante définit la valeur du nœud sur l'horodatage actuel du serveur Firebase :
curl -X PUT -d '{".sv": "timestamp"}' \ 'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'
Vous pouvez également écrire des priorités en utilisant les valeurs du serveur, en utilisant le chemin « enfant virtuel » indiqué ci-dessus.
Les valeurs de serveur prises en charge incluent :
Valeur du serveur | |
---|---|
horodatage | Temps écoulé depuis l'époque UNIX, en millisecondes. |
incrément | Fournissez une valeur delta entière ou à virgule flottante, sous la forme { ".sv": {"increment": <delta_value> }} , avec laquelle incrémenter atomiquement la valeur actuelle de la base de données. Si les données n'existent pas encore, la mise à jour définira les données sur la valeur delta. Si la valeur delta ou les données existantes sont des nombres à virgule flottante, les deux valeurs seront interprétées comme des nombres à virgule flottante et appliquées sur le back-end comme une valeur double. L'arithmétique double et la représentation des valeurs doubles suivent la sémantique IEEE 754. En cas de dépassement d'entier positif/négatif, la somme est calculée comme un double. |
Récupération et mise à jour des règles de sécurité de la base de données en temps réel Firebase
L'API REST peut également être utilisée pour récupérer et mettre à jour les règles de sécurité de la base de données en temps réel Firebase pour votre projet Firebase. Vous aurez besoin du secret de votre projet Firebase, que vous pouvez trouver sous le panneau Comptes de service des paramètres de votre projet Firebase.
curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET' curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
Authentifier les demandes
Par défaut, les requêtes REST sont exécutées sans authentification et ne réussiront que si les règles de base de données en temps réel autorisent un accès public en lecture ou en écriture aux données. Pour authentifier votre demande, utilisez les paramètres de requête access_token=
ou auth=
.
Apprenez-en davantage sur l'authentification via l'API REST dans Authentifier les requêtes REST .
Conditions d'erreur
L'API REST de Firebase Database peut renvoyer les codes d'erreur suivants.
Codes d'état HTTP | |
---|---|
400 requêtes incorrectes | L'une des conditions d'erreur suivantes :
|
401 Non autorisé | L'une des conditions d'erreur suivantes :
|
404 introuvable | La base de données en temps réel spécifiée est introuvable. |
500 Erreur de serveur interne | Le serveur a renvoyé une erreur. Voir le message d'erreur pour plus de détails. |
503 Service Indisponible | La base de données Firebase Realtime spécifiée est temporairement indisponible, ce qui signifie que la demande n'a pas été tentée. |
412 Échec de la condition préalable | La valeur ETag spécifiée par la requête dans l'en-tête if-match ne correspondait pas à la valeur du serveur. |
Sauf indication contraire, le contenu de cette page est régi par une licence Creative Commons Attribution 4.0, et les échantillons de code sont régis par une licence Apache 2.0. Pour en savoir plus, consultez les Règles du site Google Developers. Java est une marque déposée d'Oracle et/ou de ses sociétés affiliées.
Dernière mise à jour le 2024/03/20 (UTC).