Récupération des données

Lecture de données avec GET

Nous pouvons lire les données de notre base de données Firebase en émettant une GET demande à son critère 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 demande réussie sera indiquée par un 200 OK code d'état HTTP 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 une liste complète, reportez - vous à l' API REST de référence .

authentification

Le auth paramètre de requête permet d' accéder aux données protégées par Firebase en temps réel les règles de base de données , et est pris en charge par tous les types de demande. L'argument peut être votre secret de l' application Firebase ou un jeton d' authentification, tel que décrit dans les utilisateurs des projets Firebase . Dans l'exemple suivant , nous envoyons un GET demande avec un auth paramètre, où CREDENTIAL est soit votre secret de l' application Firebase ou un jeton d' authentification:

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

imprimer

Spécification d' print=pretty renvoie les données dans un format lisible par l' homme.

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

Spécification d' print=silent renvoie un 204 No Content de succès.

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

rappeler

Pour faire des appels REST à partir d' un navigateur Web dans les domaines que vous pouvez utiliser JSONP pour envelopper la réponse dans une fonction de rappel JavaScript. Ajouter callback= avoir l'API REST Envelopper les données renvoyées dans la fonction de rappel que vous spécifiez. Par 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 besoin de tout télécharger. Pour l' utiliser, ajouter shallow=true comme 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 booléen), sa valeur sera simplement renvoyée. Si l'instantané des données à l'emplacement est un objet JSON, les valeurs de chaque clé sera tronquée à 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 curl demande:

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?shallow=true&print=pretty'

temps libre

Utilisez-le pour limiter la durée de la lecture côté serveur. Si une demande de lecture ne se termine pas dans le temps imparti, elle se termine par une erreur HTTP 400. Ceci 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 les timeouts d' 3ms 3s 3min timeouts en utilisant le format suivant: 3ms , 3s ou 3min , avec un nombre et une unité. Si non spécifié, le maximum timeout d' 15min timeout de 15min sera appliquée. Si le timeout d' timeout est pas positif, ou dépasse le maximum, la demande sera rejetée avec une erreur HTTP 400. Dans l'exemple suivant, l' GET demande comprend 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, vous indiquez comment vous voulez que vos données à filtrer à l' aide du orderBy paramètre. Ensuite, vous combinez orderBy avec l' un des cinq autres paramètres: limitToFirst , limitToLast , startAt , endAt et equalTo .

Puisque nous tous à Firebase pensons 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 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 dans l' une des trois façons suivantes : par clé enfant, par clé ou par valeur. Une requête commence par un de ces paramètres, et doit ensuite être combiné 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 noeuds par une clé enfant commune en passant que la clé du 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é de l' enfant nous le filtrage sur sera triée avec une valeur de null . Pour plus de détails sur la façon dont les données est ordonnée, voir comment les données sont Ordonné .

Firebase prend également en charge les requêtes ordonnées par des enfants profondément imbriqués, plutôt que par des enfants d'un niveau inférieur. Ceci est utile si vous avez des 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 complet vers 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 que par une clé à la fois. En utilisant le orderBy paramètre plusieurs fois sur la même requête renvoie une erreur.

Filtrage par clé

Nous pouvons également les nœuds de filtre par leurs clés à l' aide du orderBy="$key" paramètre. L'exemple suivant récupère tous les dinosaures avec un nom commençant par la lettre a par m :

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

Filtrage par valeur

Nous pouvons filtrer les noeuds par la valeur de leurs clés de l' enfant à l' aide de la orderBy="$value" paramètre. Disons que les dinosaures organisent une compétition sportive de dinosaures et que nous suivons leurs scores dans le format suivant :

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

Pour récupérer tous les dinosaures avec un score supérieur à 50, nous pourrions faire la requête suivante :

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

Voir comment les null orderBy="$value" données sont Ordonné pour une explication sur la façon dont null , booléen, chaîne, et les valeurs sont triées objet lors de l' utilisation orderBy="$value" .

Filtrage complexe

Nous pouvons combiner plusieurs paramètres pour construire des requêtes plus complexes.

Limiter les requêtes

Les limitToFirst et limitToLast paramètres sont utilisés pour définir un nombre maximum d'enfants pour lesquels de recevoir des données. Si nous fixons 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 chaque enfant. Cependant, si nous avons plus de 100 messages, nous ne recevrons les données que pour 100 de ces messages. Ceux - ci seront les 100 premiers messages commandés si nous utilisons limitToFirst ou les 100 derniers messages commandés si nous utilisons limitToLast .

En utilisant notre base de faits de dinosaures et orderBy , nous pouvons trouver les deux plus lourds dinosaures:

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

De même, nous pouvons trouver les deux plus courts dinosaures en utilisant limitToFirst :

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

Nous pouvons également effectuer des requêtes limites avec orderBy="$value" . Si nous voulons créer un classement avec les trois meilleurs concurrents sportifs 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

En utilisant startAt , endAt et equalTo nous permet de choisir les points de départ et de fin arbitraire pour nos requêtes. Par exemple, si nous voulions trouver tous les dinosaures qui sont 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 les noms viennent avant ptérodactyle lexicographique:

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

Les requêtes de plage sont également utiles lorsque vous devez paginer vos données.

Mettre tous ensemble

Nous pouvons combiner toutes ces techniques pour créer des requêtes complexes. Par exemple, vous voulez peut-être trouver le nom de tous les dinosaures dont la hauteur est inférieure ou égale à 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"

Comment les données sont ordonnées

Cette section explique comment vos données sont classées lors de l'utilisation de chacun des trois paramètres de filtrage.

commandé par

Lorsque vous utilisez orderBy avec le nom d'une clé enfant, les données qui contient la clé de l' enfant spécifié sera ordonné comme suit:

  1. Les enfants ayant une null valeur de la clé de l' enfant spécifié viennent en premier.
  2. Les enfants ayant une valeur de false pour la clé de l' enfant spécifié viennent ensuite. Si plusieurs enfants ont une valeur de false , ils sont triés lexicographique par clé.
  3. Les enfants ayant une valeur de true pour la clé de l' enfant spécifié viennent ensuite. Si plusieurs enfants ont une valeur de true , ils sont classés par ordre lexicographique clé.
  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 lexicographiquement par ordre croissant. Si plusieurs enfants ont la même valeur pour le nœud enfant spécifié, ils sont classés lexicographiquement par clé.
  6. Les objets arrivent en dernier et sont triés lexicographiquement 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 retour de Firebase.

orderBy="$key"

Lorsque vous utilisez la orderBy="$key" paramètre pour trier vos données, les données seront retournées dans l' ordre croissant par clé comme suit. Gardez à l'esprit que les clés ne peuvent être que des chaînes.

  1. Les enfants avec une clé qui peut être analysée comme un entier de 32 bits viennent en premier, triés par ordre croissant.
  2. Les enfants avec une valeur de chaîne comme clé viennent ensuite, triés lexicographiquement par ordre croissant.

orderBy="$valeur"

Lorsque vous utilisez la orderBy="$value" paramètre pour trier vos données, les enfants seront classés par leur valeur. Les critères de classement sont les mêmes que les données classé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 la orderBy="$priority" paramètre pour trier vos données, l'ordre des enfants est déterminée par leur priorité et la clé comme suit. Gardez à l'esprit que les valeurs prioritaires ne peuvent être que des nombres ou des chaînes.

  1. Les enfants sans priorité (par défaut) passent en premier.
  2. Les enfants avec un numéro comme priorité viennent ensuite. Ils sont triés numériquement par priorité, de petit à grand.
  3. Les enfants avec une ficelle comme priorité arrivent en dernier. Ils sont triés lexicographiquement par priorité.
  4. Chaque fois que deux enfants ont la même priorité (y compris aucune priorité), ils sont triés par clé. Les touches numériques viennent en premier (triées numériquement), suivies des autres touches (triées lexicographiquement).

Pour plus d' informations sur les priorités, consultez la référence API .

Diffusion à partir de l'API REST

Points d' extrémité Firebase REST prennent en charge le EventSource / Events Server Sent protocole, le rendant facile à des changements de flux à un seul endroit dans notre base de données Firebase.

Pour commencer le streaming, nous devrons procéder comme suit :

  1. Définissez le client est en- tête Accept au text/event-stream
  2. Respectez les redirections HTTP, en particulier le code d'état HTTP 307
  3. Inclure le auth paramètre de requête si l'emplacement de la base de données Firebase nécessite l' autorisation de lire

En retour, le serveur enverra 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 :

mettre Les données encodées JSON seront un objet avec deux clés : chemin et données
Le chemin pointe vers un emplacement relatif à l'URL de la demande
Le client doit remplacer toutes les données à cet emplacement dans son cache par les données fournies dans le message
pièce Les données encodées JSON seront un objet avec deux clés : chemin et données
Le chemin pointe vers un emplacement relatif à l'URL de la demande
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
rester en vie 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 sera envoyé si les règles de base de données en temps réel Firebase empêchent la lecture à l'emplacement demandé
auth_revoked Les données de cet événement sont une chaîne indiquant que les informations d'identification ont expiré
Cet événement sera envoyé lorsque le paramètre d'authentification fourni n'est plus valide

Voici un exemple d'un 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 emballage tiers autour du Firebase REST et les API en streaming.