Recuperando datos

Lectura de datos con GET

Podemos leer datos de nuestra base de datos de Firebase emitiendo una solicitud GET a su punto final URL. Continuemos con nuestro ejemplo de blog de la sección anterior y leamos todos los datos de nuestras publicaciones de blog:

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

Una solicitud exitosa se indicará con un código de estado HTTP 200 OK y la respuesta contendrá los datos que estamos recuperando.

Agregar parámetros de URI

La API REST acepta varios parámetros de consulta al leer datos de nuestra base de datos Firebase. A continuación se enumeran los parámetros más utilizados. Para obtener una lista completa, consulte la Referencia de API REST .

autenticación

El parámetro de solicitud auth permite el acceso a datos protegidos por las reglas de seguridad de Firebase Realtime Database y es compatible con todos los tipos de solicitudes. El argumento puede ser el secreto de su aplicación Firebase o un token de autenticación, como se describe en Usuarios en Proyectos de Firebase . En el siguiente ejemplo, enviamos una solicitud GET con un parámetro auth , donde CREDENTIAL es el secreto de tu aplicación Firebase o un token de autenticación:

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

imprimir

Al especificar print=pretty se devuelven los datos en un formato legible por humanos.

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

Al especificar print=silent se devuelve un 204 No Content en caso de éxito.

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

llamar de vuelta

Para realizar llamadas REST desde un navegador web entre dominios, puede utilizar JSONP para encapsular la respuesta en una función de devolución de llamada de JavaScript. Agregue callback= para que la API REST incluya los datos devueltos en la función de devolución de llamada que especifique. Por ejemplo:

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://docs-examples.firebaseio.com/fireblog/posts.json?callback=gotData">

poco profundo

Esta es una característica avanzada, diseñada para ayudarle a trabajar con grandes conjuntos de datos sin necesidad de descargarlo todo. Para usarlo, agregue shallow=true como parámetro. Esto limitará la profundidad de los datos devueltos. Si los datos en la ubicación son una primitiva JSON (cadena, número o booleano), simplemente se devolverá su valor. Si la instantánea de datos en la ubicación es un objeto JSON, los valores de cada clave se truncarán a verdadero . Por ejemplo, utilizando los siguientes datos:

{
  "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!"

Pruébelo con esta solicitud curl :

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

se acabó el tiempo

Utilice esto para limitar el tiempo que tarda la lectura en el lado del servidor. Si una solicitud de lectura no finaliza dentro del tiempo asignado, finaliza con un error HTTP 400. Esto es particularmente útil cuando espera una pequeña transferencia de datos y no quiere esperar demasiado para recuperar un subárbol potencialmente enorme. El tiempo de lectura real puede variar según el tamaño de los datos y el almacenamiento en caché.

Especifique timeouts usando el siguiente formato: 3ms , 3s o 3min , con un número y una unidad. Si no se especifica, se aplicará el timeout máximo de 15min . Si el timeout no es positivo o excede el máximo, la solicitud será rechazada con un error HTTP 400. En el siguiente ejemplo, la solicitud GET incluye un timeout de 10 segundos.

curl 'https://docs-examples.firebaseio.com/rest/retrieving-data.json?timeout=10s'

Filtrar datos

Podemos construir consultas para filtrar datos en función de varios factores. Para comenzar, especifica cómo desea que se filtren sus datos utilizando el parámetro orderBy . Luego, combina orderBy con cualquiera de los otros cinco parámetros: limitToFirst , limitToLast , startAt , endAt y equalTo .

Dado que todos nosotros en Firebase pensamos que los dinosaurios son geniales, usaremos un fragmento de una base de datos de muestra de datos sobre dinosaurios para demostrar cómo se pueden filtrar datos:

{
  "lambeosaurus": {
    "height": 2.1,
    "length": 12.5,
    "weight": 5000
  },
  "stegosaurus": {
    "height": 4,
    "length": 9,
    "weight": 2500
  }
}

Podemos filtrar datos de una de tres maneras: por clave secundaria , por clave o por valor . Una consulta comienza con uno de estos parámetros y luego se debe combinar con uno o más de los siguientes parámetros: startAt , endAt , limitToFirst , limitToLast o equalTo .

Filtrar por una clave secundaria especificada

Podemos filtrar nodos por una clave secundaria común pasando esa clave al parámetro orderBy . Por ejemplo, para recuperar todos los dinosaurios con una altura mayor a 3, podemos hacer lo siguiente:

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

Cualquier nodo que no tenga la clave secundaria que estamos filtrando se ordenará con un valor null . Para obtener detalles sobre cómo se ordenan los datos, consulte Cómo se ordenan los datos .

Firebase también admite consultas ordenadas por niños profundamente anidados, en lugar de solo niños de un nivel inferior. Esto es útil si tiene datos profundamente anidados como este:

{
  "lambeosaurus": {
    "dimensions": {
      "height" : 2.1,
      "length" : 12.5,
      "weight": 5000
    }
  },
  "stegosaurus": {
    "dimensions": {
      "height" : 4,
      "length" : 9,
      "weight" : 2500
    }
  }
}

Para consultar la altura ahora, usamos la ruta completa al objeto en lugar de una sola clave:

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

Las consultas solo pueden filtrar por una clave a la vez. El uso del parámetro orderBy varias veces en la misma solicitud genera un error.

Filtrar por clave

También podemos filtrar nodos por sus claves usando el parámetro orderBy="$key" . El siguiente ejemplo recupera todos los dinosaurios con un nombre que comienza con la letra a hasta m :

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

Filtrar por valor

Podemos filtrar nodos por el valor de sus claves secundarias usando el parámetro orderBy="$value" . Digamos que los dinosaurios están teniendo una competencia deportiva de dinosaurios y realizamos un seguimiento de sus puntajes en el siguiente formato:

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

Para recuperar todos los dinosaurios con una puntuación superior a 50, podríamos realizar la siguiente solicitud:

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

Consulte Cómo se ordenan los datos para obtener una explicación sobre cómo se ordenan los valores null , booleanos, de cadena y de objeto cuando se usa orderBy="$value" .

Filtrado complejo

Podemos combinar múltiples parámetros para construir consultas más complejas.

Limitar consultas

Los parámetros limitToFirst y limitToLast se utilizan para establecer un número máximo de hijos para recibir datos. Si establecemos un límite de 100, solo recibiremos hasta 100 niños coincidentes. Si tenemos menos de 100 mensajes almacenados en nuestra base de datos, recibiremos a todos los niños. Sin embargo, si tenemos más de 100 mensajes, solo recibiremos datos de 100 de esos mensajes. Estos serán los primeros 100 mensajes ordenados si usamos limitToFirst o los últimos 100 mensajes ordenados si usamos limitToLast .

Usando nuestra base de datos de datos de dinosaurios y orderBy , podemos encontrar los dos dinosaurios más pesados:

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

De manera similar, podemos encontrar los dos dinosaurios más cortos usando limitToFirst :

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

También podemos realizar consultas de límites con orderBy="$value" . Si queremos crear una tabla de clasificación con los tres competidores de deportes de dinosaurios con mayor puntuación, podríamos hacer lo siguiente:

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

Consultas de rango

El uso startAt , endAt y equalTo nos permite elegir puntos de inicio y finalización arbitrarios para nuestras consultas. Por ejemplo, si quisiéramos encontrar todos los dinosaurios que miden al menos tres metros de altura, podemos combinar orderBy y startAt :

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

Podemos usar endAt para encontrar todos los dinosaurios cuyos nombres aparecen lexicográficamente antes de Pterodactyl:

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

Podemos combinar startAt y endAt para limitar ambos extremos de nuestra consulta. El siguiente ejemplo busca todos los dinosaurios cuyo nombre comienza con la letra "b":

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

Las consultas de rango también son útiles cuando necesitas paginar tus datos.

Poniendolo todo junto

Podemos combinar todas estas técnicas para crear consultas complejas. Por ejemplo, tal vez quieras encontrar el nombre de todos los dinosaurios que son más bajos o iguales en altura que nuestro tipo favorito, Stegosaurus:

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"

Cómo se ordenan los datos

Esta sección explica cómo se ordenan sus datos cuando se utiliza cada uno de los tres parámetros de filtrado.

ordenar por

Cuando se utiliza orderBy con el nombre de una clave secundaria, los datos que contienen la clave secundaria especificada se ordenarán de la siguiente manera:

1. Los niños con un valor null para la clave secundaria especificada son lo primero.
2. Los niños con un valor false para la clave secundaria especificada son los siguientes. Si varios hijos tienen un valor false , se ordenan lexicográficamente por clave.
3. Los niños con un valor true para la clave secundaria especificada son los siguientes. Si varios hijos tienen un valor true , se ordenan lexicográficamente por clave.
4. Los niños con un valor numérico vienen a continuación, ordenados en orden ascendente. Si varios hijos tienen el mismo valor numérico para el nodo hijo especificado, se ordenan por clave.
5. Las cadenas van después de los números y están ordenadas lexicográficamente en orden ascendente. Si varios hijos tienen el mismo valor para el nodo hijo especificado, se ordenan lexicográficamente por clave.
6. Los objetos van al final y se ordenan lexicográficamente por clave en orden ascendente.

ordenBy="$clave"

Cuando utilice el parámetro orderBy="$key" para ordenar sus datos, los datos se devolverán en orden ascendente por clave de la siguiente manera. Tenga en cuenta que las claves sólo pueden ser cadenas.

1. Los niños con una clave que se puede analizar como un entero de 32 bits aparecen primero, ordenados en orden ascendente.
2. Los niños con un valor de cadena como clave vienen a continuación, ordenados lexicográficamente en orden ascendente.

ordenBy="$valor"

Cuando utilice el parámetro orderBy="$value" para ordenar sus datos, los elementos secundarios se ordenarán por su valor. El criterio de ordenación es el mismo que el de los datos ordenados por una clave secundaria, excepto que se utiliza el valor del nodo en lugar del valor de una clave secundaria especificada.

orderBy="$prioridad"

Cuando se utiliza el parámetro orderBy="$priority" para ordenar los datos, el orden de los elementos secundarios se determina según su prioridad y clave de la siguiente manera. Tenga en cuenta que los valores de prioridad solo pueden ser números o cadenas.

1. Los niños sin prioridad (la opción predeterminada) son lo primero.
2. Los niños que tienen un número como prioridad son los siguientes. Están ordenados numéricamente por prioridad, de pequeño a grande.
3. Los niños que tienen como prioridad una cuerda son los últimos. Están ordenados lexicográficamente por prioridad.
4. Siempre que dos niños tienen la misma prioridad (incluso sin prioridad), se ordenan por clave. Las claves numéricas van primero (ordenadas numéricamente), seguidas por las claves restantes (ordenadas lexicográficamente).

Para obtener más información sobre las prioridades, consulte la referencia de API .

Transmisión desde la API REST

Los puntos finales REST de Firebase admiten el protocolo EventSource/Eventos enviados por el servidor , lo que facilita la transmisión de cambios a una única ubicación en nuestra base de datos de Firebase.

Para comenzar con la transmisión, necesitaremos hacer lo siguiente:

1. Establezca el encabezado Aceptar del cliente en text/event-stream
2. Respete los redireccionamientos HTTP, en particular el código de estado HTTP 307
3. Incluya el parámetro de consulta auth si la ubicación de la base de datos de Firebase requiere permiso para leer

A cambio, el servidor enviará eventos con nombre a medida que cambie el estado de los datos en la URL solicitada. La estructura de estos mensajes se ajusta al protocolo EventSource:

event: event name
data: JSON encoded data payload

El servidor puede enviar los siguientes eventos:

A continuación se muestra un ejemplo de un conjunto de eventos que el servidor puede enviar:

// 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 está utilizando Go, consulte Firego , un contenedor de terceros para las API REST y Streaming de Firebase.