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 URL. point de terminaison unique. Poursuivons avec l'exemple de blog de la section précédente et lisons tous nos Données des 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 contenant les données à récupérer.

Ajouter des paramètres d'URI

L'API REST accepte plusieurs paramètres de requête lors de la lecture de données à partir 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 le 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 compatibles avec tous les types de requêtes. L'argument peut être soit le secret de votre application Firebase, un jeton d'authentification unique, comme décrit dans la section Utilisateurs dans les projets Firebase. Dans l'exemple suivant, nous envoyons une requête GET avec un auth. , où CREDENTIAL correspond au secret de votre application Firebase jeton d'authentification:

curl 'https://docs-examples.firebaseio.com/auth-example.json?auth=CREDENTIAL'

Si l'option debug du jeton est définie, les informations de débogage sont disponibles dans la 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 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 le 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">

superficielle

Il s'agit d'une fonctionnalité avancée conçue pour vous aider à travailler avec de grands jeux 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 de l'emplacement sont une primitive JSON (chaîne, nombre, ou booléen) sa valeur est simplement renvoyée. Si l'instantané de données présent à l'emplacement est un fichier JSON , les valeurs de chaque clé seront tronquées à true. Par exemple, si vous utilisez 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 être utilisé avec aucun des "filtres de données". paramètres de requête.

délai avant expiration

Utilisez cette option pour limiter la durée de la lecture côté serveur. Si une lecture ne s'achève pas dans le délai imparti, elle se termine par une requête erreur 400. Ceci est particulièrement utile lorsque vous attendez un petit transfert de données sans attendre trop longtemps pour récupérer une sous-arborescence potentiellement énorme. Valeur réelle le temps de lecture 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, par un nombre et une unité. Si ce n'est pas le cas spécifié, la valeur timeout maximale 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'

Filtrage des données

Nous pouvons construire des requêtes pour filtrer les données en fonction de divers facteurs. Pour commencer, indiquez la manière dont vous souhaitez filtrer vos données à l'aide de l'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éterminé, 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 une fois qu'ils ont été renvoyés par Firebase.

Puisque nous sommes tous chez Firebase pensant que les dinosaures sont plutôt cool, un extrait d'un échantillon 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
  }
}

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

Vous pouvez filtrer les nœuds à l'aide d'une clé enfant commune en transmettant cette clé à 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 ne possède pas la clé enfant sur laquelle nous effectuons le filtrage sera trié avec une valeur de null. Pour savoir comment les données sont consultez l'article Ordre des données.

Firebase prend également en charge les requêtes classées par enfants profondément imbriqués, plutôt que par des enfants de niveau inférieur. 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 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 être filtrées que par une clé à la fois. Si vous utilisez le paramètre orderBy plusieurs fois sur la même requête génère une erreur.

Ajoutez l'indexation à votre Firebase Realtime Database Security Rules: Si vous utilisez orderBy dans votre application, vous devez définir les clés que vous utiliserez l'indexation via la règle .indexOn dans votre Firebase Realtime Database Security Rules. Lisez la documentation sur le .indexOn.

Filtrer par clé

Vous pouvez également filtrer les nœuds en fonction de 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 de orderBy="$value" . Disons que les dinosaures font une compétition sportive avec des dinosaures et que nous maintenons 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 l'article Comment les données sont-elles classées pour plus d'informations sur comment les valeurs null, booléenne, 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 dans l'index approprié. Lisez la documentation sur le .indexOn.

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 permettent de définir un nombre maximal d'enfants pour lesquels vous souhaitez recevoir des données. Si nous définissons une limite de 100, nous ne recevrons que 100 enfants correspondants. Si moins de 100 messages sont stockés dans notre nous recevons chaque enfant. Cependant, si nous avons plus de 100 messages, nous n'afficherons reçoivent des données pour 100 de ces messages. Ce seront les 100 premiers messages ordonnés si nous avec limitToFirst ou les 100 derniers messages ordonnés si nous utilisons limitToLast

Nous pouvons trouver les deux en utilisant notre base de données de faits sur les dinosaures et orderBy. 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 voulons créer classement avec les trois compétitions de dinosaures qui ont le plus marqué, nous pourrions faire suivantes:

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

Requêtes de plage

Utiliser 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 est antérieur au ptérodactyle. lexicographiquement:

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

startAt et endAt sont inclusifs, ce qui signifie "ptérodactyle" correspondront à 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 elle se trouve après la plupart des caractères standards en Unicode, la requête correspond à toutes les valeurs Commencez 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 voulez peut-être pour trouver le nom de tous les dinosaures dont la hauteur est inférieure ou égale à celle du dinosaure 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"

Comment les données sont-elles ordonnées

Cette section explique comment vos données sont classé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 aucun ordre de tri sur l'ensemble de résultats. Bien que orderBy peut être utilisé avec les éléments 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 les la clé enfant sera classée comme suit:

1. Les enfants avec une valeur null pour la clé enfant spécifiée sont placés en premier.
2. Les enfants dont la valeur est false pour la clé enfant spécifiée sont les suivants. Si plusieurs enfants ont la valeur false, ils sont triés d'un point de vue lexicographique par clé.
3. Les enfants dont la valeur est true pour la clé enfant spécifiée sont les suivants. Si plusieurs enfants ont la valeur true, ils sont triés de façon lexicographique en fonction .
4. Les enfants avec une valeur numérique arrivent 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 classés lexicographique par clé.
6. Les objets apparaissent en dernier et sont triés de façon lexicographique par clé et 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 une fois qu'ils ont été renvoyés par Firebase.

orderBy="$clé"

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 avec une clé pouvant être analysée en tant qu'entier 32 bits sont placés en premier, triés par ordre croissant commande.
2. Les enfants dont la clé est une valeur de chaîne viennent ensuite, triés par ordre lexicographique croissant.

orderBy="$valeur"

Lorsque vous utilisez le paramètre orderBy="$value" pour trier vos données, les enfants sont classées par leur valeur. Les critères de tri sont les mêmes que 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 paramètre orderBy="$priority" pour trier vos données, l'ordre des les éléments enfants sont déterminés 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 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 considérées comme numériques que lorsqu'elles peuvent être analysées en tant que un entier de 32 bits.

1. Les enfants sans priorité (par défaut) sont traités en premier.
2. Les enfants dont la priorité est un numéro arrivent ensuite. Elles sont triées numériquement par priorité, petit à grand.
3. Les enfants dont la priorité est une chaîne viennent en dernier. Elles sont triées par ordre lexicographique, par ordre de 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 apparaissent en premier (triées par ordre numérique), suivies des clés restantes (triées). d'un point de vue lexicographique).

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

Traiter des flux à partir de l'API REST

Les points de terminaison REST Firebase sont compatibles avec la classe EventSource / "Événements envoyés par le serveur", qui permet de diffuser facilement les modifications vers un emplacement unique dans notre base de données Firebase.

Pour commencer à diffuser du contenu, procédez comme suit :

1. Définissez l'en-tête "Accepter" 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 autorisation de lecture

En retour, le serveur enverra des événements nommés en tant qu'état des données à l'URL demandée des modifications. 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 en JSON seront 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 de cet emplacement dans son cache par les données fournies dans le message.
patch	Les données encodées en JSON seront 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. Pour chaque clé présente dans les données, le client doit remplacer la clé correspondante dans son cache par les données de cette clé figurant 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_rappelé	Les données pour cet événement sont une chaîne indiquant qu'un identifiant a expiré Cet événement sera 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 pour les API REST et Streaming de Firebase.