API REST do Firebase Database

Uso da API

É possível usar qualquer URL do Firebase Realtime Database como um endpoint REST. Tudo o que você precisa é anexar .json ao final do URL e enviar uma solicitação do seu cliente HTTPS favorito.

HTTPS é obrigatório. O Firebase só responde ao tráfego criptografado para que seus dados permaneçam seguros.

GET: como ler dados

Os dados do Realtime Database podem ser lidos emitindo uma solicitação solicitação GET para um endpoint. O exemplo a seguir demonstra como recuperar as informações de um usuário nome armazenado anteriormente em Realtime Database. 

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Uma solicitação bem-sucedida é indicada por um código de status HTTP 200 OK. A resposta contém os dados associados ao na solicitação GET. 

{ "first": "Jack", "last": "Sparrow" }

PUT: como gravar dados

É possível gravar dados com uma solicitação PUT. 

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

Uma solicitação bem-sucedida é indicada por um código de status HTTP 200 OK. A resposta contém os dados especificados no PUT. 

{ "first": "Jack", "last": "Sparrow" }

POST: envio de dados

Para conseguir o equivalente ao push() do JavaScript (consulte Listas de dados), é possível emitir uma solicitação POST. 

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

Uma solicitação bem-sucedida é indicada por um status HTTP 200 OK o código-fonte. A resposta contém o nome filho dos novos dados especificado na solicitação POST. 

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - Atualizando dados

É possível atualizar filhos específicos em um local sem substituir dados existentes usando uma solicitação PATCH. Filhos nomeados na os dados gravados com PATCH serão substituídos, mas omitidos filhos não são excluídos. Isso é equivalente à interface função update(). 

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

Uma solicitação bem-sucedida é indicada por um status HTTP 200 OK o código-fonte. A resposta contém os dados especificados no PATCH. 

{ "last": "Jones" }

DELETE - Remoção de dados

É possível excluir dados com uma solicitação DELETE: 

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Uma solicitação DELETE bem-sucedida é indicada por uma Código de status HTTP 200 OK com uma resposta contendo JSON null

Substituição do método

Se você fizer chamadas REST de um navegador que não seja compatível com a métodos anteriores, é possível substituir o método de solicitação fazendo uma solicitação POST e configurando o método usando no cabeçalho da solicitação X-HTTP-Method-Override. 

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'

Também é possível usar o parâmetro de consulta x-http-method-override. 

curl -X POST \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json?x-http-method-override=DELETE'

Solicitações condicionais

Solicitações condicionais, o equivalente em REST das operações de transação do SDK, atualizam dados de acordo com a uma determinada condição. Consulte uma visão geral do fluxo de trabalho e saiba mais sobre solicitações condicionais para REST em Como salvar dados.

ETag do Firebase

A ETag do Firebase é o identificador exclusivo dos dados atuais em um local especificado. Se o alterações de dados naquele local, a ETag também é alterada. A ETag do Firebase deve ser especificada no cabeçalho para a solicitação REST inicial (normalmente um GET, mas pode ser qualquer coisa diferente de PATCH). 

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

if-match

A condição if-match especifica o valor da ETag dos dados que você quer atualizar. Se você usar a condição, Realtime Database só concluirá as solicitações em que a ETag especificada no solicitação de gravação corresponde à ETag dos dados existentes no banco de dados. Busque o ETag em um local com uma solicitação de ETag do Firebase. Se você quiser substituir qualquer local nulo, use null_etag.

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

Respostas esperadas

A tabela a seguir fornece uma visão geral das respostas esperadas para cada tipo de solicitação, com base na correspondência de ETag.

Tipo de solicitação "X-Firebase-ETag: true" A ETag corresponde a
if_match: <matching etag>		 A ETag não corresponde a
if_match: <no matching etag>
RECEBER Status/conteúdo da resposta 200: "<data_at_path>" 400: "...indisponível.." 400: "...indisponível.."
Cabeçalhos adicionados ETag: <ETag_dos_dados> N/A N/A
PUT Status/conteúdo da resposta 200: "<put_data>" 200: "<put_data>" 412: "...Incompatibilidade de ETag.."
Cabeçalhos adicionados ETag: <ETag_de_put_data> N/A ETag: <database_ETag>
PÓS Status/conteúdo da resposta 200: "<dados_da_postagem>" 400: "...indisponível.." 400: "...indisponível.."
Cabeçalhos adicionados ETag: <ETag_of_post_data> N/A N/A
PATCH (em inglês) Status/conteúdo da resposta 400: "...indisponível.." 400: "...indisponível.." 400: "...indisponível.."
Cabeçalhos adicionados N/A N/A N/A
EXCLUIR Status/conteúdo da resposta 200: nulo 200: "<dados_após_put>" 412: "...Incompatibilidade de ETag.."
Cabeçalhos adicionados ETag: <ETag_of_null> N/A ETag: <database_ETag>

Query Parameters

A API REST do Firebase Database aceita os seguintes parâmetros de consulta e valores:

access_token

Compatível com todos os tipos de solicitação. Autentica essa solicitação para permitir acesso aos dados protegidos por Firebase Realtime Database Security Rules. Consulte o documentação de autenticação REST para mais detalhes. 

curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'

shallow

Esse é um recurso avançado, criado para ajudar você a trabalhar com grandes dos conjuntos de dados sem precisar fazer o download de tudo. Defina como true para limitar a profundidade dos dados retornados. em um local. Se os dados no local forem um primitivo JSON (string, número ou booleano), seu valor será simplesmente retornado. Se o no local é um objeto JSON, o valores para cada chave serão truncados para true.

Argumentos Métodos REST Descrição
superficial GET Limite a profundidade da resposta. 
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Observe que shallow não pode ser misturado com nenhuma outra consulta. parâmetros.

print

Formata os dados retornados na resposta do servidor.

Argumentos Métodos REST Descrição
muito GET, PUT, POST, PATCH, DELETE Veja os dados em um formato legível por humanos.
silencioso GET, PUT, POST, PATCH Usado para suprimir a saída do servidor ao gravar dados. A resposta resultante estará vazia e indicada por um código de status HTTP 204 No Content. 
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=pretty'

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio.com/users/jack/name.json?print=silent'

callback

Compatível apenas com GET. Fazer chamadas REST de um navegador da Web em vários domínios, é possível usar JSONP para encapsular a resposta em um função de callback. Adicione callback= para encapsular a API REST os dados retornados na função de callback especificada. 

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>

formato

Se definido como export, o servidor codificará as prioridades na resposta.

Argumentos Métodos REST Descrição
exportar GET Inclua informações de prioridade na resposta. 
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

download

Compatível apenas com GET. Se você quiser acionar um arquivo download dos seus dados de um navegador da Web, adicione download=. Isso faz com que o serviço REST adicione os cabeçalhos apropriados para que os navegadores sabem salvar os dados em um arquivo. 

curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'

timeout

Use esse parâmetro para limitar o tempo de leitura no lado do servidor. Se uma leitura solicitação não for concluída dentro do tempo alocado, ela será encerrada com um 400. Isso é muito útil quando se espera uma pequena transferência de dados e não quer esperar muito tempo para buscar uma subárvore potencialmente enorme. Real o tempo de leitura pode variar de acordo com o tamanho e o armazenamento em cache dos dados.

Especifique timeouts usando o seguinte formato: 3ms, 3s, ou 3min, com um número e uma unidade. Caso contrário especificado, o timeout máximo de 15min será aplicada. Se o timeout não for positivo ou exceder o máximo, a solicitação será rejeitada com um erro HTTP 400.

writeSizeLimit

Para limitar o tamanho de uma gravação, é possível especificar o parâmetro de consulta writeSizeLimit tiny (meta=1s), small (meta=10s), medium (meta=30 s), large (meta=60 s). O Realtime Database estima o tamanho de cada solicitação de gravação e cancela solicitações que demorarão mais do que o tempo desejado.

Se você especificar unlimited, gravações excepcionalmente grandes (com payload de até 256 MB) são permitidas, possivelmente bloqueando solicitações subsequentes enquanto o banco de dados processa as operação atual. As gravações não podem ser canceladas depois que chegam ao servidor. 

curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'

Você verá a seguinte mensagem de erro se a gravação for muito grande: 

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Além disso, é possível definir o defaultWriteSizeLimit para todo o banco de dados usando a CLI do Firebase. Esse limite se aplica a todas as solicitações, incluindo as de SDKs. Novos bancos de dados são criados com defaultWriteSizeLimit definido como large. Não é possível definir defaultWriteSizeLimit como tiny usando a CLI do Firebase. 

firebase database:settings:set defaultWriteSizeLimit large

orderBy

Consulte a seção do guia sobre dados ordenados para mais informações.

limitToFirst, limitToLast, startAt, endAt, equalTo

Consulte a seção do guia sobre filtrar dados para mais informações.

Como fazer stream da API REST

Os endpoints REST do Firebase são compatíveis com Eventos EventSource / Enviados pelo servidor protocolo. Para transmitir as alterações para um único local no Realtime Database, faça o seguinte: você precisa fazer algumas coisas:

  • Defina o cabeçalho Aceitar do cliente como "text/event-stream"
  • Respeite os redirecionamentos de HTTP, especificamente o código de status HTTP 307.
  • Se o local precisar de permissão para leitura, inclua o Parâmetro auth

Em troca, o servidor enviará eventos nomeados como o estado dos dados em o URL solicitado muda. A estrutura dessas mensagens segue usando o protocolo EventSource. 

event: event name
data: JSON encoded data payload

O servidor pode enviar estes eventos:

put

Os dados codificados em JSON são um objeto com duas chaves: path e dados. Os pontos-chave path para um local relativo ao URL de solicitação. O cliente deve substituir todas os dados naquele local no cache com data.

patch

Os dados codificados em JSON são um objeto com duas chaves: path e dados. Os pontos-chave path para um local relativo ao URL de solicitação. Para cada chave em data, o cliente deve substituir o chave correspondente em seu cache com os dados dessa chave na mensagem.

keep-alive

Os dados deste evento são null. Nenhuma ação é necessária.

cancel

Alguns erros inesperados podem enviar um evento "cancel" e encerrar a conexão. A causa está descrita nos dados fornecidos para esse evento. Algumas possíveis causas são como da seguinte forma: 1: O Firebase Realtime Database Security Rules não permite mais uma leitura no local solicitado. A A descrição de `data` para essa causa é "Permissão negada". 2. Uma gravação acionou um streamer de eventos que enviou uma grande árvore JSON que excede nosso limite. 512MB. O `data` para esta causa é "O payload especificado é muito grande. Solicite um local com menos dados".

auth_revoked

Os dados desse evento são uma string que indica que o token expirou. Este evento é enviado quando o auth fornecido não é mais válido.

Veja um exemplo de 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}}

Prioridades

As informações de prioridade para um local podem ser referenciadas com uma "criança virtual" chamado .priority. Você pode ler as prioridades com Solicitações GET e gravá-las com solicitações PUT. Por exemplo, a solicitação a seguir recupera a prioridade do Nó users/tom: 

curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'

Para gravar prioridade e dados ao mesmo tempo, adicione uma .priority filho para o payload JSON: 

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom.json'

Para gravar a prioridade e um valor primitivo (por exemplo, uma string) ao mesmo tempo, adicione um filho .priority e coloque o valor primitivo em um filho .value: 

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'

Isso grava "Tom" com uma prioridade de 1.0. As prioridades podem ser incluídas em qualquer profundidade no payload JSON.

Valores de servidor

Você pode gravar valores de servidor em um local usando um valor de espaço reservado que é um objeto com uma única chave .sv. O valor dessa chave é o tipo de valor de servidor que você quer definir. Por exemplo, os seguintes define o valor do nó como o valor atual do servidor do Firebase carimbo de data/hora: 

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'

Você também pode escrever prioridades usando valores de servidor, usando o "criança virtual" o caminho observado acima.

Os valores de servidor aceitos incluem:

Valor do servidor
timestamp Tempo desde a época do UNIX, em milissegundos.
incremento Forneça um número inteiro ou um valor delta de ponto flutuante, no formato { ".sv": {"increment": <delta_value> }}, com que será possível atomicamente incrementar o valor atual do banco de dados. Se os dados ainda não existirem, a atualização definirá os dados para o valor delta. Se um dos valores delta ou os dados existentes estiverem flutuando números de ponto, ambos os valores serão interpretados como números de ponto flutuante e aplicados ao back-end como um valor duplo. Aritmética dupla e representação de valores duplos seguem Semântica IEEE 754. Se houver estouro de números inteiros positivos/negativos, a soma será calculada como um duplo.

Recuperando e atualizando Firebase Realtime Database Security Rules

A API REST também pode ser usada para recuperar e atualizar os Firebase Realtime Database Security Rules para seu projeto do Firebase. Você vai precisar da chave secreta do seu projeto do Firebase, que que você encontra na Contas de serviço da conta do do ambiente. 

curl 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio/.settings/rules.json?auth=FIREBASE_SECRET'

Autenticar solicitações

Por padrão, as solicitações REST são executadas sem autenticação e só terão êxito se o As regras Realtime Database permitem acesso público de leitura ou gravação a os dados. Para autenticar sua solicitação, use o Parâmetros de consulta access_token= ou auth=.

Saiba mais sobre a autenticação pela API REST em Autentique as solicitações REST.

Condições de erro

A API REST do Firebase Database pode retornar os códigos de erro a seguir.

Códigos de status HTTP
400 Solicitação inválida

Uma das seguintes condições de erro:

  • Não é possível analisar dados do PUT ou do POST.
  • Os dados do PUT ou do POST estão ausentes.
  • A solicitação tenta PUT ou POST os dados muito grande.
  • A chamada de API REST contém nomes de filhos inválidos como parte do caminho.
  • O caminho da chamada à REST API é muito longo.
  • A solicitação contém um valor de servidor não reconhecido.
  • O índice para a consulta não está definido no seu Firebase Realtime Database Security Rules
  • A solicitação é incompatível com um dos parâmetros de consulta especificados.
  • A solicitação combina parâmetros de consulta com uma solicitação GET superficial.
401 Não autorizado

Uma das seguintes condições de erro:

  • O token de autenticação expirou.
  • O token de autenticação usado na solicitação é inválido.
  • Falha na autenticação com um access_token.
  • A solicitação viola sua Firebase Realtime Database Security Rules.
404 Não encontrado O Realtime Database especificado não foi encontrado.
500 Erro interno do servidor O servidor retornou um erro. Veja a mensagem de erro para mais detalhes.
503 Serviço não disponível O Firebase Realtime Database especificado está temporariamente indisponível, ou seja, não houve tentativa de solicitação.
412 Falha na pré-condição O valor da ETag especificado da solicitação no cabeçalho if-match não corresponde ao valor do servidor.