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 est indiquée par un code d'état HTTP 200 OK, et la réponse contient 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'

Si l'indicateur debug du jeton est défini, des informations de débogage sont disponibles dans l'en-tête X-Firebase-Auth-Debug de la réponse.

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 entre des 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 comme paramètre. Cela limite 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 à 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'

shallow ne peut pas être utilisé avec les paramètres de requête "filtrage des données".

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.

Les données filtrées sont renvoyées sans ordre : lorsque vous utilisez l'API REST, les résultats filtrés sont renvoyés dans un ordre indéfini, car les interpréteurs JSON n'appliquent aucun 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.

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.

Ajouter l'indexation à votre Firebase Realtime Database Security Rules : si vous utilisez orderBy dans votre application, vous devez définir les clés sur lesquelles vous allez indexer via la règle .indexOn dans votre Firebase Realtime Database Security Rules. Pour en savoir plus, consultez la documentation sur la règle .indexOn.

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

Ajouter l'indexation à votre Firebase Realtime Database Security Rules : si vous utilisez orderBy="$value" dans votre application, vous devez ajouter .value à vos règles à l'index approprié. Pour en savoir plus, consultez la documentation sur la règle .indexOn.

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'

startAt et endAt sont inclusifs, ce qui signifie que "pterodactyl" correspond à la requête ci-dessus.

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'

Le caractère \uf8ff utilisé dans la requête ci-dessus est un point de code très élevé dans la plage Unicode. Étant donné qu'il se trouve après la plupart des caractères standards en Unicode, la requête correspond à toutes les valeurs commençant par un b.

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.

L'API REST renvoie des résultats non triés : les interpréteurs JSON n'appliquent aucune tri sur l'ensemble de résultats. Bien que orderBy puisse être utilisé avec startAt, endAt, limitToFirst ou limitToLast pour renvoyer un sous-ensemble de données, les résultats renvoyés ne seront pas triés. Par conséquent, il peut être nécessaire de trier manuellement les résultats si l'ordre est important.

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 associés à 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é.

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="$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.

Les priorités numériques sont stockées et triées sous forme de nombres à virgule flottante à double précision IEEE 754. Les clés sont toujours stockées sous forme de chaînes et ne sont traitées comme des valeurs numériques que lorsqu'elles peuvent être analysées en tant qu'entier de 32 bits.

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:

put	Les données encodées au format JSON sont un objet avec deux clés : "path" et "data". Le chemin d'accès pointe vers un emplacement par rapport à l'URL de la requête. Le client doit remplacer toutes les données à cet emplacement dans son cache par les données indiquées dans le message.
patch	Les données encodées au format JSON sont un objet comportant deux clés : "path" et "data". Le chemin d'accès 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.
message keep-alive	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 est envoyé si Firebase Realtime Database Security Rules empêche la lecture à l'emplacement demandé.
auth_revoked	Les données de cet événement sont une chaîne indiquant qu'un identifiant a expiré. Cet événement est envoyé lorsque le paramètre d'authentification fourni n'est plus valide.

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.