API REST do banco de dados Firebase

Uso da API

Você pode usar qualquer URL do Firebase Realtime Database como um endpoint REST. Tudo o que você precisa fazer é anexar .json ao final da URL e enviar uma solicitação de seu cliente HTTPS favorito.

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

GET - Dados de leitura

Os dados do Realtime Database podem ser lidos emitindo uma solicitação HTTP GET para um endpoint. O exemplo a seguir demonstra como você pode recuperar o nome de um usuário armazenado anteriormente no 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 caminho na solicitação GET .

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

PUT - Escrevendo dados

Você pode 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 na solicitação PUT .

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

POST - Enviando dados

Para realizar o equivalente ao método push() do JavaScript (consulte Listas de dados ), você pode 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 código de status HTTP 200 OK . A resposta contém o nome filho dos novos dados especificados na solicitação POST .

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

PATCH - Atualizando dados

Você pode atualizar filhos específicos em um local sem sobrescrever os dados existentes usando uma solicitação PATCH . Os filhos nomeados nos dados que estão sendo gravados com PATCH são sobrescritos, mas os filhos omitidos não são excluídos. Isso é equivalente à função update() do JavaScript.

curl -X PATCH -d '{"last":"Jones"}' \
 '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 na solicitação PATCH .

{ "last": "Jones" }

EXCLUIR - Removendo dados

Você pode 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 um código de status HTTP 200 OK com uma resposta contendo JSON null .

Substituição de método

Se você fizer chamadas REST de um navegador que não oferece suporte aos métodos anteriores, poderá substituir o método de solicitação fazendo uma solicitação POST e configurando seu método usando o cabeçalho de 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'

Você também pode 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

As solicitações condicionais, o equivalente REST das operações de transação do SDK, atualizam os dados de acordo com uma determinada condição. Veja uma visão geral do fluxo de trabalho e saiba mais sobre solicitações condicionais para REST em Salvando dados .

Firebase ETag

O Firebase ETag é o identificador exclusivo dos dados atuais em um local especificado. Se os dados forem alterados nesse local, a ETag também será alterada. O Firebase ETag deve ser especificado no cabeçalho da 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 ETag para os dados que você deseja atualizar. Se você usar a condição, o Realtime Database só concluirá as solicitações em que a ETag especificada na solicitação de gravação corresponder à ETag dos dados existentes no banco de dados. Busque a ETag em um local com uma solicitação de ETag do Firebase. Se você deseja 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: verdadeiro' Correspondências de ETag
if_match: <matching etag>
ETag não corresponde
if_match: <no matching etag>
PEGAR Status/conteúdo da resposta 200: "<data_at_path>" 400: "...não suportado.." 400: "...não suportado.."
Cabeçalhos adicionados ETag: <ETag_of_data> N / D N / D
COLOCAR Status/conteúdo da resposta 200: "<put_data>" 200: "<put_data>" 412: "...ETag incompatível.."
Cabeçalhos adicionados ETag: <ETag_of_put_data> N / D ETag: <database_ETag>
PUBLICAR Status/conteúdo da resposta 200: "<post_data>" 400: "...não suportado.." 400: "...não suportado.."
Cabeçalhos adicionados ETag: <ETag_of_post_data> N / D N / D
CORREÇÃO Status/conteúdo da resposta 400: "...não suportado.." 400: "...não suportado.." 400: "...não suportado.."
Cabeçalhos adicionados N / D N / D N / D
EXCLUIR Status/conteúdo da resposta 200: nulo 200: "<data_after_put>" 412: "...ETag incompatível.."
Cabeçalhos adicionados ETag: <ETag_of_null> N / D ETag: <database_ETag>

Parâmetros de consulta

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

access_token

Compatível com todos os tipos de solicitação. Autentica esta solicitação para permitir o acesso aos dados protegidos pelas regras de segurança do Firebase Realtime Database. Consulte a documentação de autenticação REST para obter detalhes.

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

raso

Este é um recurso avançado, projetado para ajudá-lo a trabalhar com grandes conjuntos de dados sem precisar baixar tudo. Defina como true para limitar a profundidade dos dados retornados em um local. Se os dados do local forem uma primitiva 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 .

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

Observe que shallow não pode ser misturado com nenhum outro parâmetro de consulta.

imprimir

Formata os dados retornados na resposta do servidor.

argumentos Métodos REST Descrição
bonito OBTER, COLOCAR, POSTAR, PATCH, EXCLUIR Visualize os dados em um formato legível por humanos.
silencioso OBTER, COLOCAR, POSTAR, 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'

ligar de volta

Suportado apenas por GET . 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 envolva os dados retornados na função de retorno de chamada que você especificar.

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

formatar

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

argumentos Métodos REST Descrição
exportar PEGAR Inclua informações prioritárias na resposta.
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

download

Suportado apenas por GET . Se você deseja acionar um download de arquivo de 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 saibam que devem salvar os dados em um arquivo.

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

tempo esgotado

Use isso para limitar quanto tempo a leitura leva no lado do servidor. Se uma solicitação de leitura não for concluída dentro do tempo alocado, ela será encerrada 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 grande. O tempo de leitura real 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, o timeout limite máximo de 15min será aplicado. 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, você pode especificar o parâmetro de consulta writeSizeLimit como tiny (destino=1s), small (destino=10s), medium (destino=30s), large (destino=60s). O Realtime Database estima o tamanho de cada solicitação de gravação e cancela as solicitações que levarão mais tempo do que o tempo de destino.

Se você especificar unlimited , gravações excepcionalmente grandes (com carga útil de até 256 MB) serão permitidas, possivelmente bloqueando solicitações subsequentes enquanto o banco de dados processa a operação atual. As gravações não podem ser canceladas depois de chegarem 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, você pode definir o defaultWriteSizeLimit para toda a instância do banco de dados usando a Firebase CLI. 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 . Você não pode definir defaultWriteSizeLimit como tiny usando o Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

ordenar por

Consulte a seção no guia sobre dados solicitados para obter mais informações.

limitToFirst, limitToLast, startAt, endAt, equalTo

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

Transmissão da API REST

Os endpoints Firebase REST suportam o protocolo EventSource / Server-Sent Events . Para transmitir alterações para um único local em seu Realtime Database, você precisa fazer algumas coisas:

  • Defina o cabeçalho Accept do cliente como "text/event-stream"
  • Respeite os redirecionamentos HTTP, em particular o código de status HTTP 307
  • Se o local exigir permissão para leitura, você deverá incluir o parâmetro auth

Em troca, o servidor enviará eventos nomeados conforme o estado dos dados nas alterações de URL solicitadas. A estrutura dessas mensagens está de acordo 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 são um objeto com duas chaves: path e data . A chave do caminho aponta para um local relativo ao URL da solicitação. O cliente deve substituir todos os dados naquele local em seu cache por data .

correção

Os dados codificados em JSON são um objeto com duas chaves: path e data . A chave do caminho aponta para um local relativo ao URL da solicitação. Para cada chave em data , o cliente deve substituir a chave correspondente em seu cache pelos dados dessa chave na mensagem.

mantenha vivo

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

cancelar

Alguns erros inesperados podem enviar um evento `cancel` e encerrar a conexão. A causa está descrita nos dados fornecidos para este evento. Algumas possíveis causas são as seguintes: 1. As regras de segurança do Firebase Realtime Database não permitem mais uma leitura no local solicitado. A descrição `dados` para esta causa é "Permissão negada". 2. Uma gravação acionou um streamer de eventos que enviou uma grande árvore JSON que excede nosso limite, 512 MB. Os `dados` para esta causa são "A carga útil especificada é muito grande, solicite um local com menos dados."

auth_revoked

Os dados para este evento são uma string indicando que a credencial expirou. Este evento é enviado quando o parâmetro auth fornecido não é mais válido.

Aqui está 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 um "filho virtual" chamado .priority . Você pode ler prioridades com solicitações GET e escrevê-las com solicitações PUT . Por exemplo, a seguinte solicitação recupera a prioridade do nó users/tom :

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

Para gravar prioridade e dados ao mesmo tempo, você pode adicionar um filho .priority à carga JSON:

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

Para escrever prioridade e um valor primitivo (por exemplo, uma string) ao mesmo tempo, você pode adicionar um filho .priority e colocar 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 na carga JSON.

Valores do 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 do servidor que você deseja definir. Por exemplo, a solicitação a seguir define o valor do nó para o carimbo de data/hora atual do servidor Firebase:

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 caminho "filho virtual" observado acima.

Os valores de servidor suportados incluem:

Valor do servidor
carimbo de data/hora O tempo desde a época do UNIX, em milissegundos.
incremento Forneça um valor delta inteiro ou de ponto flutuante, no formato { ".sv": {"increment": <delta_value> }} , com o qual incrementar atomicamente 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 o valor delta ou os dados existentes forem números de ponto flutuante, ambos os valores serão interpretados como números de ponto flutuante e aplicados no back-end como um valor duplo. A aritmética dupla e a representação de valores duplos seguem a semântica IEEE 754. Se houver estouro de número inteiro positivo/negativo, a soma será calculada como um duplo.

Recuperando e atualizando as regras de segurança do Firebase Realtime Database

A API REST também pode ser usada para recuperar e atualizar as regras de segurança do Firebase Realtime Database para seu projeto Firebase. Você precisará do segredo do seu projeto Firebase, que pode ser encontrado no painel Contas de serviço da configuração do seu projeto Firebase.

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ó serão bem-sucedidas se as Regras do banco de dados em tempo real permitirem acesso público de leitura ou gravação aos dados. Para autenticar sua solicitação, use os parâmetros de consulta access_token= ou auth= .

Saiba mais sobre autenticação por meio da API REST em Autenticar solicitações REST .

Condições de erro

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

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

Uma das seguintes condições de erro:

  • Não é possível analisar os dados PUT ou POST .
  • Dados PUT ou POST ausentes.
  • A solicitação tenta PUT ou POST dados muito grandes.
  • A chamada da API REST contém nomes de filhos inválidos como parte do caminho.
  • O caminho da chamada da API REST é muito longo.
  • A solicitação contém um valor de servidor não reconhecido.
  • O índice da consulta não está definido nas regras de segurança do Firebase Realtime Database .
  • A solicitação não oferece suporte a um dos parâmetros de consulta especificados.
  • A solicitação mistura parâmetros de consulta com uma solicitação GET superficial.
401 não autorizado

Uma das seguintes condições de erro:

404 não encontrado O Realtime Database especificado não foi encontrado.
500 Erro Interno do Servidor O servidor retornou um erro. Consulte a mensagem de erro para obter mais detalhes.
503 Serviço indisponível O Firebase Realtime Database especificado está temporariamente indisponível, o que significa que a solicitação não foi tentada.
412 Pré-condição falhou O valor ETag especificado da solicitação no cabeçalho if-match não corresponde ao valor do servidor.