API REST de la base de données Firebase

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 ETag
if_match: <matching etag>		 ETag ne correspond pas
if_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 :

  • Impossible d'analyser les données PUT ou POST .
  • Données PUT ou POST manquantes.
  • La requête tente de PUT ou POST des données trop volumineuses.
  • L'appel d'API REST contient des noms d'enfants non valides dans le chemin.
  • Le chemin d'appel de l'API REST est trop long.
  • La requête contient une valeur de serveur non reconnue.
  • L'index de la requête n'est pas défini dans vos règles de sécurité de la base de données en temps réel Firebase .
  • La demande ne prend pas en charge l'un des paramètres de requête spécifiés.
  • La requête mélange les paramètres de requête avec une requête GET superficielle.
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.