Récupération des données

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Lire des données avec GET

Nous pouvons lire les données de notre base de données Firebase en envoyant 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 de publication 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 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 requête auth permet d'accéder aux données protégées par les règles de 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 la section Utilisateurs des 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'

Spécifier 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 encapsuler 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 à tout télécharger. Pour l'utiliser, ajoutez 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 libre

Utilisez ceci pour limiter la durée de lecture du côté serveur. Si une demande de lecture ne se termine pas dans le délai imparti, elle se termine par une erreur HTTP 400. Ceci est particulièrement utile lorsque vous attendez un petit transfert de données et que vous ne voulez pas attendre trop longtemps pour récupérer une sous-arborescence potentiellement énorme. Le temps de lecture réel peut varier en fonction de la taille des données et de la mise en cache.

Spécifiez les délais d' timeouts en utilisant le format suivant : 3ms , 3s ou 3min , avec un nombre et une unité. S'il n'est pas spécifié, le timeout maximum de 15min sera appliqué. Si le timeout d'attente n'est pas positif ou dépasse le maximum, la demande sera rejetée avec une erreur HTTP 400. Dans l'exemple suivant, la requête GET inclut un timeout d'attente 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 .

Étant donné que chez Firebase, nous pensons tous que les dinosaures sont plutôt cool, nous allons utiliser un extrait d'une base de données d'exemples de faits sur les dinosaures pour montrer comment vous pouvez 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 transmettant 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 une valeur de null . Pour plus de détails sur la façon dont les données sont triées, voir Comment les données sont triées .

Firebase prend également en charge les requêtes commandées par des enfants profondément imbriqués, plutôt que par des enfants d'un niveau inférieur. Ceci est utile si vous avez des 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 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 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 orderBy="$value" . Disons que les dinosaures organisent une compétition sportive de dino et que nous gardons une trace de 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 avec 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 trié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 des 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 d'informations 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 courts 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 compétiteurs de sports dino avec les meilleurs scores, nous pouvons 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épart et de fin arbitraires pour nos requêtes. Par exemple, si nous voulions trouver tous les dinosaures mesurant au moins trois mètres de haut, 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 Ptérodactyle lexicographiquement :

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 trouve 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 de 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 à celle de notre espèce préférée, le Stegosaurus :

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 trié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 trié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 avec 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 triés lexicographiquement par clé.
  6. Les objets viennent en dernier et sont triés lexicographiquement par clé dans l'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 retour depuis Firebase.

orderBy="$clé"

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

  1. Les enfants avec une clé qui peut être analysée comme un entier 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="$value"

Lorsque vous utilisez le orderBy="$value" pour trier vos données, les enfants seront triés par leur valeur. Les critères de tri sont les mêmes que pour les données trié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 orderBy="$priority" pour trier vos données, l'ordre des enfants est déterminé par leur priorité et leur clé comme suit. N'oubliez pas que les valeurs de priorité ne peuvent être que des nombres ou des chaînes.

  1. Les enfants sans priorité (valeur par défaut) passent en premier.
  2. Les enfants avec un numéro comme priorité viennent ensuite. Ils sont triés numériquement par priorité, du plus petit au plus grand.
  3. Les enfants avec une ficelle comme priorité viennent en dernier. Ils sont trié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 .

Diffusion 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 dans notre base de données Firebase.

Pour commencer avec le streaming, nous devrons faire ce qui 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 au fur et à 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 encodées en JSON seront un objet avec deux clés : path et data
Le chemin pointe vers un emplacement relatif à l'URL de la demande
Le client doit remplacer toutes les données à cet emplacement dans son cache par les données fournies dans le message
correctif Les données encodées en JSON seront un objet avec deux clés : path et data
Le chemin pointe vers un emplacement relatif à l'URL de la demande
Pour chaque clé dans les 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 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

Voici 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.