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 de URL. Continuemos con el ejemplo de nuestro blog de la sección anterior y leamos todos los datos de las publicaciones de nuestro 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.

Adición de parámetros de URI

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

autenticación

El parámetro de solicitud de auth permite el acceso a los datos protegidos por las reglas de base de datos en tiempo real de Firebase y es compatible con todos los tipos de solicitudes. El argumento puede ser el secreto de su aplicación de 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 de auth , donde CREDENTIAL es el secreto de su aplicación Firebase o un token de autenticación:

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

imprimir

Especificar print=pretty devuelve los datos en un formato legible por humanos.

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

Especificar print=silent 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 a través de dominios, puede usar JSONP para envolver la respuesta en una función de devolución de llamada de JavaScript. Agregue callback= para que la API REST envuelva 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 ayudarlo a trabajar con grandes conjuntos de datos sin necesidad de descargar todo. Para utilizarlo, añade " 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), su valor simplemente se devolverá. Si la instantánea de datos en la ubicación es un objeto JSON, los valores de cada clave se truncarán a true . 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 de curl :

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

se acabó el tiempo

Use 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 desea esperar demasiado para obtener 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 los tiempos de timeouts con el siguiente formato: 3ms , 3s o 3min , con un número y una unidad. Si no se especifica, se aplicará el tiempo de timeout máximo de 15min . Si el tiempo de timeout no es positivo o supera el máximo, la solicitud se rechazará con un error HTTP 400. En el siguiente ejemplo, la solicitud GET incluye un tiempo de timeout de 10 segundos.

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

Filtrado de 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 hechos de dinosaurios para demostrar cómo puede 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 debe combinarse con uno o más de los siguientes parámetros: startAt , endAt , limitToFirst , limitToLast o equalTo .

Filtrado por una clave secundaria especificada

Podemos filtrar los nodos por una clave secundaria común pasando esa clave al parámetro orderBy . Por ejemplo, para recuperar todos los dinosaurios con una altura superior 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 elementos secundarios profundamente anidados, en lugar de solo elementos secundarios 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.

Filtrado por clave

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

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

Filtrado por valor

Podemos filtrar los nodos por el valor de sus claves secundarias usando el orderBy="$value" . Digamos que los dinosaurios están teniendo una competencia deportiva de dinosaurios y hacemos 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 petición:

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 elementos secundarios para los que 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 hechos 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ímite con orderBy="$value" . Si queremos crear una tabla de clasificación con los tres competidores deportivos 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 de 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 vienen antes de Pterodactyl lexicográficamente:

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 encuentra 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 necesita paginar sus 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 a 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 al usar cada uno de los tres parámetros de filtrado.

ordenar por

Al usar 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 elementos secundarios con un valor null para la clave secundaria especificada vienen primero.
2. Los elementos secundarios con un valor false para la clave secundaria especificada vienen a continuación. Si varios hijos tienen un valor de false , se ordenan lexicográficamente por clave.
3. Los elementos secundarios con un valor de true para la clave secundaria especificada vienen a continuación. Si varios hijos tienen un valor de 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 elementos secundarios tienen el mismo valor numérico para el nodo secundario especificado, se ordenan por clave.
5. Las cadenas vienen después de los números y se clasifican 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 en último lugar y se ordenan lexicográficamente por clave en orden ascendente.

orderBy="$clave"

Al usar el 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 solo pueden ser cadenas.

1. Los elementos secundarios 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, clasificados lexicográficamente en orden ascendente.

orderBy="$valor"

Al usar el 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 orderBy="$priority" para ordenar los datos, el orden de los elementos secundarios se determina por 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 (por defecto) son los primeros.
2. Los niños con un número como prioridad vienen después. Se ordenan numéricamente por prioridad, de menor a mayor.
3. Los niños con una cuerda como prioridad son los últimos. Están ordenados lexicográficamente por prioridad.
4. Siempre que dos hijos tengan la misma prioridad (incluida la ausencia de 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 la API .

Transmisión desde la API REST

Los puntos finales REST de Firebase admiten el protocolo EventSource/Server-Sent Events , lo que facilita la transmisión de cambios a una sola 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 de 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 usa Go, consulte Firego , un contenedor de terceros para las API REST y Streaming de Firebase.