Récupérer des données

Lecture de 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. Reprenons l'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 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 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 GET requête avec un auth paramètre, 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, les 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 par un humain.

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

Si vous spécifiez print=silent, la réponse 204 No Content est renvoyée 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 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">

shallow

Il s'agit d'une fonctionnalité avancée conçue pour vous aider à utiliser 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 un élément primitif JSON (chaîne, nombre, ou valeur booléenne), leur valeur sera simplement renvoyée. Si l'instantané des 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 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 l'un des paramètres de requête "filtering data" (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 par 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 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 au format suivant : 3ms, 3s ou 3min, avec un nombre et une unité. Si aucune valeur n'est spécifiée, le timeout maximal de 15min est appliqué. Si le 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'

Filtrage des données

Nous pouvons créer des requêtes pour filtrer les données en fonction de différents facteurs. Pour commencer, spécifiez comment vous souhaitez filtrer vos données à l'aide du orderBy paramètre. Ensuite, combinez 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 non défini, car les interprètes 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 depuis Firebase.

Comme nous pensons tous chez Firebase que les dinosaures sont plutôt cool, nous allons utiliser un extrait d'un exemple de base de données 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 orderBy paramètre. 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 ne possède pas la clé enfant sur laquelle nous filtrons sera trié avec une valeur null. Pour en savoir plus sur l'ordre des données, consultez la section Ordre des données.

Firebase est également compatible avec les requêtes triées par des enfants profondément imbriqués, plutôt que par des enfants d'un seul niveau. Cela est utile si vous avez des données profondément 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 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.

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

Filtrage 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 à 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" paramètre. Supposons que les dinosaures participent à 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 effectuer la requête suivante :

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

Consultez la section Ordre des données pour obtenir une explication sur la façon dont les valeurs null, booléennes, de chaîne et d'objet sont triées lorsque vous utilisez orderBy="$value".

Ajoutez l'indexation à vos 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 jusqu'à 100 enfants correspondants. 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 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 des trois meilleurs concurrents de compétitions sportives 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ébut et de fin arbitraires pour nos requêtes. Par exemple, si nous voulons trouver tous les dinosaures d'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 de manière lexicographique :

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

`startAt` et `endAt` sont inclusifs, ce qui signifie que "pterodactyl" 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 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'

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 en 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 hauteur 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 ordonné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'appliquent aucun ordre à 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 est spécifiée pour la clé enfant sont affichés en premier.
2. Les enfants dont la valeur false est spécifiée pour la clé enfant sont affichés ensuite. Si plusieurs enfants ont la valeur false, ils sont triés de manière lexicographique par clé.
3. Les enfants dont la valeur true est spécifiée pour la clé enfant sont affichés ensuite. Si plusieurs enfants ont la valeur true, ils sont triés de manière lexicographique par clé.
4. Les enfants avec une valeur numérique sont affichés 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 de manière lexicographique par ordre croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont triés de manière lexicographique par clé.
6. Les objets sont affiché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. Si l'ordre de vos données est important, vous devez trier les résultats dans votre application après leur renvoi depuis Firebase.

orderBy="$key"

Lorsque vous utilisez le paramètre orderBy="$key" pour trier vos données, celles-ci sont renvoyées par 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 de 32 bits sont affichés en premier, triés par ordre croissant ordre.
2. Les enfants dont la clé est une valeur de chaîne sont affichés ensuite, triés de manière lexicographique par ordre croissant.

orderBy="$value"

Lorsque vous utilisez le paramètre orderBy="$value" pour trier vos données, les enfants sont ordonnés par leur valeur. Les critères de tri sont les mêmes que pour les données ordonné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="$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 ordonnées en tant que 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 que 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 sont affichés ensuite. Ils sont triés numériquement par priorité, du plus petit au plus grand.
3. Les enfants dont la priorité est une chaîne sont affichés en dernier. Ils sont triés de manière lexicographique par priorité.
4. Chaque fois que deux enfants ont la même priorité (y compris aucune priorité), ils sont triés par clé. Les clés numériques sont affichées en premier (triées numériquement), suivies des clés restantes (triées de manière 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 EventSource / Server-Sent Events protocole, ce qui facilite la diffusion des modifications vers un seul emplacement de notre base de données Firebase.

Pour commencer à diffuser des données, nous devons 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 auth paramètre de requête 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 seront un objet avec deux clés : path et data 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
patch	Les données encodées au format JSON seront un objet avec deux clés : path et data 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
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 les Firebase Realtime Database Security Rules empêchent 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.