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. Continuons avec notre exemple de blog de la section précédente et lisons toutes les données de nos 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. 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 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

Si vous spécifiez print=pretty, les données sont renvoyées dans un format lisible.

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

Si vous spécifiez print=silent, un 204 No Content est renvoyé en cas de réussite.

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

callback

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

superficiel

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 sera simplement renvoyée. Si l'instantané de données à l'emplacement est un objet JSON, les valeurs de chaque clé seront tronquées sur 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 de filtrage des données.

délai avant expiration

Utilisez cette option 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 vous attendez à un petit transfert de données et que vous ne voulez pas attendre trop longtemps pour récupérer un sous-arbre 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 timeouts au format suivant : 3ms, 3s ou 3min, avec un nombre et une unité. Si aucune valeur n'est spécifiée, la valeur maximale timeout de 15min sera 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 filtrer vos donné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.

Les données filtrées sont renvoyées dans le désordre : Lorsque vous utilisez l'API REST, les résultats filtrés sont renvoyés dans un ordre indéfini, car les interprètes JSON n'imposent aucun ordre. Si l'ordre de vos données est important, vous devez trier les résultats dans votre application après qu'ils ont été renvoyés par Firebase.

Comme nous trouvons tous les dinosaures plutôt cool chez Firebase, nous allons utiliser un extrait d'une base de données d'informations 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
  }
}

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.

Filtrer par clé enfant spécifiée

Nous pouvons filtrer les nœuds par 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, nous pouvons procéder comme suit :

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

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

Firebase accepte également les requêtes ordonnées par des enfants profondément imbriqués, et pas seulement par des enfants d'un niveau inférieur. Cela peut être utile si vous avez des données imbriquées comme celles-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 d'accès complet à 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 les données qu'en fonction d'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 clé à l'aide du 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'

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". Imaginons que les dinosaures organisent une compétition sportive et que nous suivons leurs scores 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 Ordre des données pour savoir comment les valeurs null, booléennes, de chaîne et d'objet sont triées lorsque vous utilisez orderBy="$value".

Ajoutez 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 au maximum. Si nous avons moins de 100 messages stockés dans notre base de données, nous recevrons chaque enfant. Toutefois, si nous avons plus de 100 messages, nous ne recevrons des données que pour 100 d'entre eux. Il s'agira des 100 premiers messages triés si nous utilisons limitToFirst ou des 100 derniers messages triés si nous utilisons limitToLast.

En utilisant notre base de données 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 plus petits dinosaures à 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 de limites avec orderBy="$value". Si nous voulons créer un classement des trois meilleurs compétiteurs 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 voulons trouver tous les dinosaures qui mesurent 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 précède "Pterodactyl" dans l'ordre lexicographique :

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

startAt et endAt sont inclusifs, ce qui signifie que "ptérodactyle" correspondra à 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. Comme il se trouve après la plupart des caractères standards dans Unicode, la requête correspond à toutes les valeurs qui commencent 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 pouvez rechercher 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ètes JSON n'imposent aucun ordre sur l'ensemble de résultats. Bien que orderBy puisse être utilisé en combinaison avec startAt, endAt, limitToFirst ou limitToLast pour renvoyer un sous-ensemble des 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 ordonnées comme suit :

1. Les enfants dont la valeur null correspond à la clé enfant spécifiée sont affichés en premier.
2. Viennent ensuite les enfants dont la valeur est false pour la clé enfant spécifiée. Si plusieurs enfants ont une valeur de false, ils sont triés lexicographiquement par clé.
3. Viennent ensuite les enfants dont la valeur est true pour la clé enfant spécifiée. Si plusieurs enfants ont une valeur de true, ils sont triés de façon lexicographique par clé.
4. Les enfants avec une valeur numérique suivent, 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 de façon lexicographique par clé.
6. Les objets sont placés en dernier et triés de manière lexicographique par clé, dans l'ordre croissant.

Les résultats filtrés sont renvoyés sans ordre particulier. Si l'ordre de vos données est important, vous devez trier les résultats dans votre application après qu'ils ont été renvoyés par Firebase.

orderBy="$key"

Lorsque vous utilisez le paramètre orderBy="$key" pour trier vos données, celles-ci sont renvoyées par clé dans l'ordre croissant, 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 de 32 bits sont affichés en premier, 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 classés par valeur. Les critères de tri sont les mêmes que pour les données triées par 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="$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 classé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 nombres que lorsqu'elles peuvent être analysées en tant qu'entier de 32 bits.

1. Les enfants sans priorité (par défaut) sont affichés en premier.
2. Les enfants dont la priorité est un nombre viennent ensuite. Elles sont triées par ordre numérique de priorité, de la plus faible à la plus élevée.
3. Les enfants dont la priorité est une chaîne de caractères sont listés en dernier. Elles sont triées de manière lexicographique par priorité.
4. Lorsque deux enfants ont la même priorité (y compris aucune priorité), ils sont triés par clé. Les clés numériques apparaissent en premier (triées par ordre numérique), suivies des clés restantes (triées par ordre lexicographique).

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

Streaming depuis l'API REST

Les points de terminaison REST Firebase sont compatibles avec le protocole EventSource/Server-Sent Events, ce qui facilite la diffusion en flux continu des modifications apportées à un emplacement unique dans notre base de données Firebase.

Pour commencer à diffuser des données, nous devons effectuer les opérations suivantes :

1. Définissez l'en-tête Accept du client sur text/event-stream
2. Respecter 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 lorsque l'état des données à l'URL demandée changera. 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 seront un objet avec deux clés : "path" et "data". Le chemin d'accès pointe vers un emplacement relatif à l'URL de la requête. Le client doit remplacer toutes les données à cet emplacement dans son cache par les données fournies dans le message.
patch	Les données encodées au format JSON seront un objet comportant deux clés : path et data Le chemin d'accès pointe vers un emplacement relatif à l'URL de la requête 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.
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 la cause Firebase Realtime Database Security Rules n'autorise plus 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 pour les API REST et de streaming Firebase.