Recuperando dados

Lendo dados com GET

Podemos ler dados de nosso banco de dados Firebase emitindo uma solicitação GET para seu endpoint de URL. Vamos continuar com nosso exemplo de blog da seção anterior e ler todos os dados de postagem do blog:

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

Uma solicitação bem-sucedida será indicada por um código de status HTTP 200 OK e a resposta conterá os dados que estamos recuperando.

Adicionando parâmetros de URI

A API REST aceita vários parâmetros de consulta ao ler dados do nosso banco de dados Firebase. Listados abaixo estão os parâmetros mais comumente usados. Para obter uma lista completa, consulte a Referência da API REST .

autenticação

O parâmetro de solicitação auth permite acesso a dados protegidos pelas regras de segurança do Firebase Realtime Database e é compatível com todos os tipos de solicitação. O argumento pode ser o segredo do seu aplicativo Firebase ou um token de autenticação, conforme descrito em Usuários em projetos do Firebase . No exemplo a seguir, enviamos uma solicitação GET com um parâmetro auth , onde CREDENTIAL é o segredo do seu aplicativo Firebase ou um token de autenticação:

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

Se o sinalizador debug do token estiver definido, as informações de depuração poderão ser encontradas no cabeçalho X-Firebase-Auth-Debug da resposta.

imprimir

Especificar print=pretty retorna os dados em um formato legível por humanos.

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

Especificar print=silent retorna 204 No Content em caso de sucesso.

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

ligar de volta

Para fazer chamadas REST de um navegador da web entre domínios, você pode usar JSONP para agrupar a resposta em uma função de retorno de chamada JavaScript. Adicione callback= para que a API REST agrupe os dados retornados na função de retorno de chamada que você especificar. Por exemplo:

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

raso

Este é um recurso avançado, projetado para ajudá-lo a trabalhar com grandes conjuntos de dados sem precisar baixar tudo. Para usá-lo, adicione shallow=true como parâmetro. Isso limitará a profundidade dos dados retornados. Se os dados no local forem primitivos JSON (string, número ou booleano), seu valor será simplesmente retornado. Se o instantâneo de dados no local for um objeto JSON, os valores de cada chave serão truncados para true . Por exemplo, usando os dados abaixo:

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

Experimente com esta solicitação curl :

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

shallow não pode ser usado com nenhum dos parâmetros de consulta de "dados de filtragem".

tempo esgotado

Use isso para limitar quanto tempo leva a leitura no lado do servidor. Se uma solicitação de leitura não terminar dentro do tempo estipulado, ela terminará com um erro HTTP 400. Isso é particularmente útil quando você espera uma pequena transferência de dados e não quer esperar muito para buscar uma subárvore potencialmente enorme. O tempo real de leitura pode variar com base no tamanho dos dados e no cache.

Especifique timeouts usando o seguinte formato: 3ms , 3s ou 3min , com um número e uma unidade. Se não for especificado, será aplicado o timeout limite máximo de 15min . Se o timeout não for positivo ou exceder o máximo, a solicitação será rejeitada com um erro HTTP 400. No exemplo a seguir, a solicitação GET inclui um timeout de 10 segundos.

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

Filtrando Dados

Podemos construir consultas para filtrar dados com base em vários fatores. Para começar, você especifica como deseja que seus dados sejam filtrados usando o parâmetro orderBy . Em seguida, você combina orderBy com qualquer um dos outros cinco parâmetros: limitToFirst , limitToLast , startAt , endAt e equalTo .

Os dados filtrados são retornados desordenados : ao usar a API REST, os resultados filtrados são retornados em uma ordem indefinida, pois os interpretadores JSON não impõem nenhuma ordem. Se a ordem dos seus dados for importante, você deverá classificar os resultados no seu aplicativo depois que eles forem retornados do Firebase.

Como todos nós do Firebase achamos que os dinossauros são muito legais, usaremos um snippet de um banco de dados de amostra de fatos sobre dinossauros para demonstrar como você pode filtrar dados:

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

Podemos filtrar dados de três maneiras: por chave filha , por chave ou por valor . Uma consulta começa com um desses parâmetros e deve ser combinada com um ou mais dos seguintes parâmetros: startAt , endAt , limitToFirst , limitToLast ou equalTo .

Filtrando por uma chave filha especificada

Podemos filtrar nós por uma chave filha comum, passando essa chave para o parâmetro orderBy . Por exemplo, para recuperar todos os dinossauros com altura superior a 3, podemos fazer o seguinte:

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

Qualquer nó que não tenha a chave filha que estamos filtrando será classificado com um valor null . Para obter detalhes sobre como os dados são ordenados, consulte Como os dados são ordenados .

O Firebase também oferece suporte a consultas ordenadas por filhos profundamente aninhados, em vez de apenas filhos um nível abaixo. Isso é útil se você tiver dados profundamente aninhados como estes:

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

Para consultar a altura agora, usamos o caminho completo para o objeto em vez de uma única chave:

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

As consultas só podem ser filtradas por uma chave por vez. Usar o parâmetro orderBy várias vezes na mesma solicitação gera um erro.

Adicione indexação às regras de segurança do Firebase Realtime Database : se estiver usando orderBy em seu aplicativo, você precisará definir as chaves que indexará por meio da regra .indexOn nas regras de segurança do Firebase Realtime Database. Leia a documentação sobre a regra .indexOn para obter mais informações.

Filtrando por chave

Também podemos filtrar nós por suas chaves usando o parâmetro orderBy="$key" . O exemplo a seguir recupera todos os dinossauros com um nome começando com a letra a até m :

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

Filtrando por valor

Podemos filtrar nós pelo valor de suas chaves filhas usando o parâmetro orderBy="$value" . Digamos que os dinossauros estejam realizando uma competição esportiva de dinossauros e estejamos acompanhando suas pontuações no seguinte formato:

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

Para recuperar todos os dinossauros com pontuação superior a 50, poderíamos fazer o seguinte pedido:

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

Consulte Como os dados são ordenados para obter uma explicação sobre como os valores null , boolean, string e object são classificados ao usar orderBy="$value" .

Adicione indexação às regras de segurança do Firebase Realtime Database : se estiver usando orderBy="$value" em seu aplicativo, você precisará adicionar .value às suas regras no índice apropriado. Leia a documentação sobre a regra .indexOn para obter mais informações.

Filtragem Complexa

Podemos combinar vários parâmetros para construir consultas mais complexas.

Limitar consultas

Os parâmetros limitToFirst e limitToLast são usados ​​para definir um número máximo de filhos para os quais receber dados. Se definirmos um limite de 100, receberemos apenas até 100 filhos correspondentes. Se tivermos menos de 100 mensagens armazenadas em nosso banco de dados, receberemos todas as crianças. No entanto, se tivermos mais de 100 mensagens, receberemos dados apenas de 100 dessas mensagens. Estas serão as primeiras 100 mensagens ordenadas se estivermos usando limitToFirst ou as últimas 100 mensagens ordenadas se estivermos usando limitToLast .

Usando nosso banco de dados de fatos sobre dinossauros e orderBy , podemos encontrar os dois dinossauros mais pesados:

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

Da mesma forma, podemos encontrar os dois dinossauros mais curtos usando limitToFirst :

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

Também podemos realizar consultas de limite com orderBy="$value" . Se quisermos criar uma tabela de classificação com os três competidores de esportes dinossauros com maior pontuação, poderíamos fazer o seguinte:

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

Consultas de intervalo

Usar startAt , endAt e equalTo nos permite escolher pontos iniciais e finais arbitrários para nossas consultas. Por exemplo, se quisermos encontrar todos os dinossauros com pelo menos três metros de altura, podemos combinar orderBy e startAt :

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

Podemos usar endAt para encontrar todos os dinossauros cujos nomes vêm antes do Pterodáctilo lexicograficamente:

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

startAt e endAt são inclusivos, o que significa que "pterodáctilo" corresponderá à consulta acima.

Podemos combinar startAt e endAt para limitar ambas as extremidades da nossa consulta. O exemplo a seguir encontra todos os dinossauros cujo nome começa com a letra “b”:

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

O caractere \uf8ff usado na consulta acima é um ponto de código muito alto no intervalo Unicode. Como vem depois da maioria dos caracteres regulares em Unicode, a consulta corresponde a todos os valores que começam com b.

Consultas de intervalo também são úteis quando você precisa paginar seus dados.

Juntando tudo

Podemos combinar todas essas técnicas para criar consultas complexas. Por exemplo, talvez você queira encontrar o nome de todos os dinossauros que são menores ou iguais em altura ao nosso tipo favorito, o Estegossauro:

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"

Como os dados são ordenados

Esta seção explica como seus dados são ordenados ao usar cada um dos três parâmetros de filtragem.

A API REST retorna resultados não classificados : os intérpretes JSON não impõem nenhuma ordem no conjunto de resultados. Embora orderBy possa ser usado em combinação com startAt , endAt , limitToFirst ou limitToLast para retornar um subconjunto de dados, os resultados retornados não serão classificados. Portanto, pode ser necessário classificar manualmente os resultados se a ordenação for importante.

ordenar por

Ao usar orderBy com o nome de uma chave filha, os dados que contêm a chave filha especificada serão ordenados da seguinte forma:

1. Os filhos com um valor null para a chave filha especificada vêm primeiro.
2. Os filhos com um valor false para a chave filha especificada vêm em seguida. Se vários filhos tiverem um valor false , eles serão classificados lexicograficamente por chave.
3. Os filhos com um valor true para a chave filha especificada vêm em seguida. Se vários filhos tiverem um valor true , eles serão classificados lexicograficamente por chave.
4. Os filhos com valor numérico vêm em seguida, classificados em ordem crescente. Se vários filhos tiverem o mesmo valor numérico para o nó filho especificado, eles serão classificados por chave.
5. As strings vêm depois dos números e são classificadas lexicograficamente em ordem crescente. Se vários filhos tiverem o mesmo valor para o nó filho especificado, eles serão ordenados lexicograficamente por chave.
6. Os objetos vêm por último e são classificados lexicograficamente por chave em ordem crescente.

Os resultados filtrados são retornados desordenados. Se a ordem dos seus dados for importante, você deverá classificar os resultados no seu aplicativo depois que eles forem retornados do Firebase.

orderBy="$chave"

Ao usar o parâmetro orderBy="$key" para classificar seus dados, os dados serão retornados em ordem crescente por chave, como segue. Lembre-se de que as chaves só podem ser strings.

1. Os filhos com uma chave que pode ser analisada como um número inteiro de 32 bits vêm primeiro, classificados em ordem crescente.
2. Os filhos com um valor de string como chave vêm em seguida, classificados lexicograficamente em ordem crescente.

orderBy="$valor"

Ao usar o parâmetro orderBy="$value" para classificar seus dados, os filhos serão ordenados por seu valor. Os critérios de ordenação são os mesmos dos dados ordenados por uma chave filha, exceto que o valor do nó é usado em vez do valor de uma chave filha especificada.

orderBy="$prioridade"

Ao usar o parâmetro orderBy="$priority" para classificar seus dados, a ordem dos filhos é determinada pela prioridade e chave da seguinte maneira. Tenha em mente que os valores de prioridade só podem ser números ou strings.

As prioridades numéricas são armazenadas e ordenadas como números de ponto flutuante de precisão dupla IEEE 754. As chaves são sempre armazenadas como strings e tratadas como numéricas somente quando podem ser analisadas como um número inteiro de 32 bits.

1. As crianças sem prioridade (o padrão) vêm em primeiro lugar.
2. As crianças com um número como prioridade vêm em seguida. Eles são classificados numericamente por prioridade, de pequeno a grande porte.
3. As crianças que têm um barbante como prioridade vêm em último lugar. Eles são classificados lexicograficamente por prioridade.
4. Sempre que dois filhos têm a mesma prioridade (incluindo nenhuma prioridade), eles são classificados por chave. As chaves numéricas vêm primeiro (classificadas numericamente), seguidas pelas chaves restantes (classificadas lexicograficamente).

Para obter mais informações sobre prioridades, consulte a referência da API .

Streaming da API REST

Os endpoints REST do Firebase oferecem suporte ao protocolo EventSource/Server-Sent Events , facilitando o streaming de alterações para um único local em nosso banco de dados Firebase.

Para começar com o streaming, precisaremos fazer o seguinte:

1. Defina o cabeçalho Accept do cliente como text/event-stream
2. Respeite os redirecionamentos HTTP, em particular o código de status HTTP 307
3. Inclua o parâmetro de consulta auth se o local do banco de dados do Firebase exigir permissão de leitura

Em troca, o servidor enviará eventos nomeados à medida que o estado dos dados na URL solicitada for alterado. A estrutura dessas mensagens está em conformidade com o protocolo EventSource:

event: event name
data: JSON encoded data payload

O servidor pode enviar os seguintes eventos:

colocar	Os dados codificados em JSON serão um objeto com duas chaves: caminho e dados O caminho aponta para um local relativo ao URL da solicitação O cliente deve substituir todos os dados daquele local em seu cache pelos dados fornecidos na mensagem
correção	Os dados codificados em JSON serão um objeto com duas chaves: caminho e dados O caminho aponta para um local relativo ao URL da solicitação Para cada chave nos dados, o cliente deve substituir a chave correspondente em seu cache pelos dados dessa chave na mensagem
mantenha vivo	Os dados deste evento são nulos, nenhuma ação é necessária
cancelar	Os dados deste evento são nulos Este evento será enviado se as regras de segurança do Firebase Realtime Database fizerem com que uma leitura no local solicitado não seja mais permitida
auth_revoked	Os dados deste evento são uma string que indica que a credencial expirou Este evento será enviado quando o parâmetro de autenticação fornecido não for mais válido

Abaixo está um exemplo de um conjunto de eventos que o servidor pode 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}}

Se você estiver usando Go, confira Firego , um wrapper de terceiros em torno das APIs REST e Streaming do Firebase.