Récupération des données

Lire des données avec GET

Nous pouvons lire les données de notre base de données Firebase en émettant une requête GET à son point de terminaison URL. Continuons avec notre exemple de blog de la section précédente et lisons toutes nos données d'articles de blog :

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

Une demande réussie sera indiquée par un code d'état HTTP 200 OK et la réponse contiendra les données que nous récupérons.

Ajout de paramètres d'URI

L'API REST accepte plusieurs paramètres de requête lors de la lecture des données de notre base de données Firebase. Vous trouverez ci-dessous les paramètres les plus couramment utilisés. Pour une liste complète, reportez-vous à la référence de l'API REST .

authentification

Le paramètre de demande auth permet d'accéder aux données protégées par les règles de sécurité de la base de données en temps réel Firebase et est pris en charge par tous les types de requêtes. L'argument peut être soit le secret de votre application Firebase, soit un jeton d'authentification, comme décrit dans Utilisateurs dans les projets Firebase . Dans l'exemple suivant, nous envoyons une requête GET avec un paramètre auth , où CREDENTIAL est soit le secret de votre application Firebase, soit un jeton d'authentification :

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

imprimer

Spécifier print=pretty renvoie les données dans un format lisible par l'homme.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=pretty'

La spécification print=silent renvoie un 204 No Content en cas de succès.

curl 'https://docs-examples.firebaseio.com/fireblog/posts.json?print=silent'

rappeler

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. Par exemple:

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

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. Pour l'utiliser, ajoutezshallow shallow=true comme paramètre. Cela limitera la profondeur des données renvoyées. 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 . Par exemple, en utilisant les données ci-dessous :

{
  "message": {
    "user": {
      "name": "Chris"
    },
    "body": "Hello!"
  }
}

// A request to /message.json?shallow=true
// would return the following:
{
  "user": true,
  "body": true
}

// A request to /message/body.json?shallow=true
// would simply return:
"Hello!"

Essayez-le avec cette requête curl :

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

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. Dans l'exemple suivant, la requête GET inclut un timeout de 10 secondes.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

Filtrage des données

Nous pouvons construire des requêtes pour filtrer les données en fonction de divers facteurs. Pour commencer, vous spécifiez comment vous souhaitez que vos données soient filtrées à l'aide du paramètre orderBy . Ensuite, vous combinez orderBy avec l’un des cinq autres paramètres : limitToFirst , limitToLast , startAt , endAt et equalTo .

Puisque nous tous chez Firebase pensons que les dinosaures sont plutôt cool, nous utiliserons un extrait d'un exemple de base de données de faits sur les dinosaures pour montrer comment filtrer les données :

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

Nous pouvons filtrer les données de trois manières : par clé enfant , par clé ou par valeur . Une requête commence par l'un de ces paramètres, puis doit être combinée avec un ou plusieurs des paramètres suivants : startAt , endAt , limitToFirst , limitToLast ou equalTo .

Filtrage par une clé enfant spécifiée

Nous pouvons filtrer les nœuds par une clé enfant commune en passant cette clé au paramètre orderBy . Par exemple, pour récupérer tous les dinosaures d’une hauteur supérieure à 3, nous pouvons procéder comme suit :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Tout nœud qui n'a pas la clé enfant sur laquelle nous filtrons sera trié avec la valeur null . Pour plus de détails sur la manière dont les données sont ordonnées, consultez Comment les données sont ordonnées .

Firebase prend également en charge les requêtes ordonnées par des enfants profondément imbriqués, plutôt que par des enfants situés uniquement au niveau inférieur. Ceci est utile si vous disposez de données profondément imbriquées comme celle-ci :

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

Pour interroger la hauteur maintenant, nous utilisons le chemin complet vers l'objet plutôt qu'une seule clé :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="dimensions/height"&startAt=3&print=pretty'

Les requêtes ne peuvent filtrer que par une seule clé à la fois. L’utilisation du paramètre orderBy plusieurs fois sur la même requête génère une erreur.

Filtrage par clé

Nous pouvons également filtrer les nœuds par leurs clés en utilisant le paramètre orderBy="$key" . L'exemple suivant récupère tous les dinosaures dont le nom commence par la lettre a à m :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="a"&endAt="m"&print=pretty'

Filtrage par valeur

Nous pouvons filtrer les nœuds par la valeur de leurs clés enfants à l'aide du paramètre orderBy="$value" . Disons que les dinosaures organisent une compétition sportive de dinosaures et que nous suivons leurs scores dans le format suivant :

{
  "scores": {
    "bruhathkayosaurus": 55,
    "lambeosaurus": 21,
    "linhenykus": 80,
    "pterodactyl": 93,
    "stegosaurus": 5,
    "triceratops": 22
  }
}

Pour récupérer tous les dinosaures ayant un score supérieur à 50, on pourrait faire la requête suivante :

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&startAt=50&print=pretty'

Voir Comment les données sont ordonnées pour une explication sur la façon dont les valeurs null , boolean, string et object sont triées lors de l'utilisation orderBy="$value" .

Filtrage complexe

Nous pouvons combiner plusieurs paramètres pour construire des requêtes plus complexes.

Limiter les requêtes

Les paramètres limitToFirst et limitToLast sont utilisés pour définir un nombre maximum d'enfants pour lesquels recevoir des données. Si nous fixons une limite de 100, nous ne recevrons que jusqu'à 100 enfants correspondants. Si nous avons moins de 100 messages stockés dans notre base de données, nous recevrons chaque enfant. Cependant, si nous avons plus de 100 messages, nous ne recevrons les données que pour 100 de ces messages. Ce seront les 100 premiers messages ordonnés si nous utilisons limitToFirst ou les 100 derniers messages ordonnés si nous utilisons limitToLast .

En utilisant notre base de données de faits sur les dinosaures et orderBy , nous pouvons trouver les deux dinosaures les plus lourds :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="weight"&limitToLast=2&print=pretty'

De même, nous pouvons trouver les deux dinosaures les plus petits en utilisant limitToFirst :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&limitToFirst=2&print=pretty'

Nous pouvons également effectuer des requêtes de limite avec orderBy="$value" . Si nous voulons créer un classement avec les trois meilleurs concurrents de sports de dinosaures avec les meilleurs scores, nous pourrions procéder comme suit :

curl 'https://dinosaur-facts.firebaseio.com/scores.json?orderBy="$value"&limitToLast=3&print=pretty'

Requêtes de plage

L'utilisation startAt , endAt et equalTo nous permet de choisir des points de début et de fin arbitraires pour nos requêtes. Par exemple, si nous voulons trouver tous les dinosaures mesurant au moins trois mètres, nous pouvons combiner orderBy et startAt :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="height"&startAt=3&print=pretty'

Nous pouvons utiliser endAt pour trouver tous les dinosaures dont les noms précèdent lexicographiquement Ptérodactyle :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&endAt="pterodactyl"&print=pretty'

Nous pouvons combiner startAt et endAt pour limiter les deux extrémités de notre requête. L'exemple suivant recherche tous les dinosaures dont le nom commence par la lettre "b" :

curl 'https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy="$key"&startAt="b"&endAt="b\uf8ff"&print=pretty'

Les requêtes par plage sont également utiles lorsque vous devez paginer vos données.

Mettre tous ensemble

Nous pouvons combiner toutes ces techniques pour créer des requêtes complexes. Par exemple, vous souhaitez peut-être trouver le nom de tous les dinosaures dont la taille est inférieure ou égale à notre espèce préférée, le stégosaure :

MY_FAV_DINO_HEIGHT=`curl "https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus/height.json"`
curl "https://dinosaur-facts.firebaseio.com/dinosaurs.json?orderBy=\"height\"&endAt=${MY_FAV_DINO_HEIGHT}&print=pretty"

Comment les données sont ordonnées

Cette section explique comment vos données sont classées lors de l'utilisation de chacun des trois paramètres de filtrage.

commandé par

Lorsque vous utilisez orderBy avec le nom d'une clé enfant, les données contenant la clé enfant spécifiée seront classées comme suit :

  1. Les enfants avec une valeur null pour la clé enfant spécifiée viennent en premier.
  2. Les enfants avec une valeur false pour la clé enfant spécifiée viennent ensuite. Si plusieurs enfants ont la valeur false , ils sont triés lexicographiquement par clé.
  3. Les enfants avec une valeur true pour la clé enfant spécifiée viennent ensuite. Si plusieurs enfants ont la valeur true , ils sont triés lexicographiquement par clé.
  4. Les enfants ayant une valeur numérique viennent ensuite, triés par ordre croissant. Si plusieurs enfants ont la même valeur numérique pour le nœud enfant spécifié, ils sont triés par clé.
  5. Les chaînes viennent après les nombres et sont triées lexicographiquement par ordre croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont classés lexicographiquement par clé.
  6. Les objets viennent en dernier et sont triés lexicographiquement par clé et par ordre croissant.
Les résultats filtrés sont renvoyés sans ordre. Si l'ordre de vos données est important, vous devez trier les résultats dans votre application après leur renvoi par Firebase.

orderBy="$clé"

Lorsque vous utilisez le paramètre orderBy="$key" pour trier vos données, les données seront renvoyées par ordre croissant par clé comme suit. Gardez à l’esprit que les clés ne peuvent être que des chaînes.

  1. Les enfants possédant une clé pouvant être analysée comme un entier de 32 bits viennent en premier, triés par ordre croissant.
  2. Les enfants avec une valeur de chaîne comme clé viennent ensuite, triés lexicographiquement par ordre croissant.

orderBy="$valeur"

Lorsque vous utilisez le paramètre orderBy="$value" pour trier vos données, les enfants seront classés selon leur valeur. Les critères de classement sont les mêmes que pour les données classées par une clé enfant, sauf que la valeur du nœud est utilisée à la place de la valeur d'une clé enfant spécifiée.

orderBy="$priorité"

Lorsque vous utilisez le paramètre orderBy="$priority" pour trier vos données, l'ordre des enfants est déterminé par leur priorité et leur clé comme suit. Gardez à l'esprit que les valeurs de priorité ne peuvent être que des nombres ou des chaînes.

  1. Les enfants sans priorité (par défaut) passent en premier.
  2. Les enfants ayant un numéro comme priorité viennent ensuite. Ils sont triés numériquement par priorité, petite à grande.
  3. Les enfants ayant une ficelle en priorité viennent en dernier. Ils sont classés lexicographiquement par priorité.
  4. Chaque fois que deux enfants ont la même priorité (y compris aucune priorité), ils sont triés par clé. Les touches numériques viennent en premier (triées numériquement), suivies des touches restantes (triées lexicographiquement).

Pour plus d'informations sur les priorités, consultez la référence API .

Streaming depuis l'API REST

Les points de terminaison Firebase REST prennent en charge le protocole EventSource / Server-Sent Events , ce qui facilite la diffusion des modifications vers un seul emplacement de notre base de données Firebase.

Pour commencer avec le streaming, nous devrons procéder comme suit :

  1. Définissez l'en-tête Accept du client sur text/event-stream
  2. Respectez les redirections HTTP, en particulier le code d'état HTTP 307
  3. Incluez le paramètre de requête auth si l'emplacement de la base de données Firebase nécessite une autorisation de lecture

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 seront un objet avec deux clés : chemin et données
Le chemin pointe vers un emplacement par rapport à l'URL de la requête
Le client doit remplacer toutes les données de cet emplacement dans son cache par les données fournies dans le message.
correctif Les données codées en JSON seront un objet avec deux clés : chemin et données
Le chemin pointe vers un emplacement par rapport à l'URL de la requête
Pour chaque clé des données, 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 nulles, aucune action n'est requise
Annuler Les données de cet événement sont nulles
Cet événement sera envoyé si les règles de sécurité de la base de données en temps réel Firebase empêchent la lecture à l'emplacement demandé.
auth_revoked Les données de cet événement sont une chaîne indiquant que les informations d'identification ont expiré.
Cet événement sera envoyé lorsque le paramètre d'authentification fourni n'est plus valide

Vous trouverez ci-dessous un exemple d'un 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}}

Si vous utilisez Go, consultez Firego , un wrapper tiers autour des API Firebase REST et Streaming.