Récupérer des données

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 d'URL. Poursuivez avec l'exemple de blog de la section précédente et lisez toutes les données de vos articles de blog:

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

Une requête 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.

Ajouter des 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 obtenir la liste complète, consultez la documentation de référence de l'API REST.

auth

Le paramètre de requête auth permet d'accéder aux données protégées par Firebase Realtime Database Security Rules et est compatible avec tous les types de requêtes. L'argument peut être le secret de votre application Firebase ou un jeton d'authentification, comme décrit dans la section Utilisateurs dans les projets Firebase. Dans l'exemple suivant, nous envoyons une requête GET avec un paramètre auth, où CREDENTIAL est le secret de votre application Firebase ou 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.

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

Spécifier print=silent renvoie un 204 No Content en cas de réussite.

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

rappel

Pour effectuer des appels REST à partir d'un navigateur Web dans différents 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. 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 en tant que 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 valeur booléenne), leur valeur est simplement renvoyée. Si l'instantané des données à l'emplacement est un objet JSON, les valeurs de chaque clé sont tronquées en 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'

délai avant expiration

Utilisez-le pour limiter la durée de la lecture côté serveur. Si une requête de lecture ne se termine pas dans le délai imparti, elle se termine avec une erreur HTTP 400. Cela est particulièrement utile lorsque vous attendez un petit transfert de données et que vous ne voulez pas attendre trop longtemps pour extraire un sous-arbre potentiellement énorme. La durée de lecture réelle peut varier en fonction de la taille des données et de la mise en cache.

Spécifiez timeouts au format suivant: 3ms, 3s ou 3min, avec un nombre et une unité. Si cette option n'est pas spécifiée, la valeur timeout maximale de 15min est appliquée. Si timeout n'est pas positif ou dépasse la valeur maximale, la requête est 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'

Filtrer les données

Nous pouvons créer des requêtes pour filtrer les données en fonction de différents facteurs. Pour commencer, vous devez spécifier comment vous souhaitez filtrer vos données à l'aide du paramètre orderBy. Vous combinez ensuite orderBy avec l'un des cinq autres paramètres : limitToFirst, limitToLast, startAt, endAt et equalTo.

Comme nous pensons tous chez Firebase que les dinosaures sont vraiment cool, nous allons utiliser un extrait d'un exemple de base de données sur les dinosaures pour vous montrer comment filtrer les données:

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

Vous pouvez 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 à un ou plusieurs des paramètres suivants: startAt, endAt, limitToFirst, limitToLast ou equalTo.

Filtrage par clé enfant spécifiée

Nous pouvons filtrer les nœuds en fonction d'une clé enfant commune en transmettant cette clé au paramètre orderBy. Par exemple, pour récupérer tous les dinosaures dont la taille est supérieure à 3, procédez comme suit:

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

Tout nœud qui ne possède pas la clé enfant sur laquelle nous effectuons le filtrage sera trié avec une valeur de null. Pour en savoir plus sur l'ordre des données, consultez Ordre des données.

Firebase prend également en charge les requêtes triées par enfants profondément imbriqués, et non seulement par enfants d'un niveau inférieur. Cette fonctionnalité est utile si vous disposez de données profondément imbriquées, comme ceci:

{
  "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 d'accès complet de 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 qu'une seule clé à la fois. L'utilisation du paramètre orderBy plusieurs fois dans la même requête génère une erreur.

Filtrer par clé

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

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

Filtrer par valeur

Nous pouvons filtrer les nœuds en fonction de la valeur de leurs clés enfants à l'aide du paramètre orderBy="$value". Supposons que les dinosaures participent à une compétition sportive et que nous tenions le score au format suivant:

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

Pour récupérer tous les dinosaures dont le score est supérieur à 50, nous pouvons envoyer la requête suivante:

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

Consultez Comment les données sont triées pour en savoir plus sur le tri des valeurs null, booléennes, de chaîne et d'objet lorsque vous utilisez orderBy="$value".

Filtrage complexe

Nous pouvons combiner plusieurs paramètres pour créer des requêtes plus complexes.

Limiter les requêtes

Les paramètres limitToFirst et limitToLast permettent de définir un nombre maximal d'enfants pour lesquels recevoir des données. Si nous définissons une limite de 100, nous ne recevrons que 100 enfants correspondants. Si nous avons moins de 100 messages stockés dans notre base de données, nous recevrons tous les enfants. Toutefois, si nous avons plus de 100 messages, nous ne recevons que les données de 100 d'entre eux. Il s'agit des 100 premiers messages triés si vous utilisez limitToFirst ou des 100 derniers messages triés si vous utilisez limitToLast.

À l'aide de notre base de données sur les dinosaures et de 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 à l'aide de limitToFirst:

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

Nous pouvons également effectuer des requêtes limitées avec orderBy="$value". Si nous souhaitons créer un classement des trois meilleurs athlètes de sports de dinosaures, 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 de startAt, endAt et equalTo nous permet de choisir des points de départ et d'arrivée arbitraires pour nos requêtes. Par exemple, si nous souhaitons 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 le nom vient avant Pterodactyl 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 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 de plage sont également utiles lorsque vous devez paginer vos données.

Synthèse

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 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"

Ordre des données

Cette section explique comment vos données sont triées lorsque vous utilisez chacun des trois paramètres de filtrage.

orderBy

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

1. Les enfants dont la valeur de la clé enfant spécifiée est null sont affichés en premier.
2. Les enfants dont la valeur de la clé enfant spécifiée est false viennent ensuite. Si plusieurs enfants ont une valeur de false, ils sont triés lexicographiquement par clé.
3. Les enfants dont la valeur de la clé enfant spécifiée est true viennent ensuite. Si plusieurs enfants ont une valeur de true, ils sont triés par clé de façon lexicographique.
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 par ordre lexicographique croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont triés par clé de manière lexicographique.
6. Les objets sont placés en dernier et triés par ordre croissant, de manière lexicographique, en fonction de la clé.

orderBy="$key"

Lorsque vous utilisez le paramètre orderBy="$key" pour trier vos données, elles sont renvoyées dans l'ordre croissant par clé, comme suit. N'oubliez pas que les clés ne peuvent être que des chaînes.

1. Les enfants dont la clé peut être analysée en tant qu'entier 32 bits sont les premiers, triés par ordre croissant.
2. Les enfants dont la clé est une valeur de chaîne viennent ensuite, triés par ordre lexicographique croissant.

orderBy="$value"

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

orderBy="$priority"

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. N'oubliez pas que les valeurs de priorité ne peuvent être que des nombres ou des chaînes.

1. Les enfants sans priorité (par défaut) sont traités en premier.
2. Viennent ensuite les enfants dont la priorité est un nombre. Ils sont triés numériquement par priorité, de la plus petite à la plus grande.
3. Les enfants dont la priorité est une chaîne sont les derniers. Elles sont triées par ordre lexicographique, par ordre de priorité.
4. Lorsque deux enfants ont la même priorité (y compris sans priorité), ils sont triés par clé. Les clés numériques viennent en premier (triées par ordre numérique), suivies des autres clés (triées par ordre alphabétique).

Pour en savoir plus sur les priorités, consultez la documentation de référence de l'API.

Streaming à partir de l'API REST

Les points de terminaison REST Firebase sont compatibles avec le protocole EventSource/Événements envoyés par le serveur, ce qui permet de diffuser facilement des modifications vers un seul emplacement dans notre base de données Firebase.

Pour commencer à diffuser du contenu, procédez 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 envoie des événements nommés lorsque 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:

Vous trouverez ci-dessous 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}}

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