API REST do banco de dados Firebase

Uso de API

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

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

GET - Lendo dados

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 - Gravação de 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 - Envio de 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 substituir os dados existentes usando uma solicitação PATCH . Os filhos nomeados nos dados que estão sendo gravados com PATCH são substituídos, mas os filhos omitidos não são excluídos. Isso é equivalente à função JavaScript update() .

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" }

DELETE - 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 suporta os métodos anteriores, poderá substituir o método de solicitação fazendo uma solicitação POST e definindo 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

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 .

ETag do Firebase

A ETag do Firebase é o identificador exclusivo dos dados atuais em um local especificado. Se os dados mudarem nesse local, a ETag também mudará. A ETag do Firebase deve ser especificada 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'

se-corresponder

A condição if-match especifica o valor ETag dos dados que você deseja atualizar. Se você usar a condição, o Realtime Database concluirá apenas 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ê 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: 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_de_dados> N / D N / D
COLOCAR Status/conteúdo da resposta 200: "<dados_colocados>" 200: "<dados_colocados>" 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_dados>" 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: "<dados_após_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:

token de acesso

Suportado por todos os tipos de solicitação. Autentica esta solicitação para permitir acesso a 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 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 .

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 agrupe 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 desejar 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 como salvar os dados em um arquivo.

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

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.

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 anula solicitações que levarão mais tempo que o tempo previsto.

Se você especificar unlimited , serão permitidas gravações excepcionalmente grandes (com carga útil de até 256 MB), potencialmente bloqueando solicitações subsequentes enquanto o banco de dados processa a operação atual. As gravações não podem ser canceladas quando 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, você pode definir o defaultWriteSizeLimit para toda a instância do banco de dados usando a CLI do Firebase. Esse limite se aplica a todas as solicitações, inclusive aquelas de SDKs. Novos bancos de dados são criados com defaultWriteSizeLimit definido como large . Você não pode definir defaultWriteSizeLimit como tiny usando a CLI do Firebase.

firebase database:settings:set defaultWriteSizeLimit large

ordenar por

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

limiteToFirst, limitToLast, startAt, endAt, equalTo

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

Streaming da API REST

Os endpoints REST do Firebase são compatíveis com o protocolo EventSource/Server-Sent Events . Para transmitir alterações para um único local no 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 de leitura, você deverá incluir o parâmetro auth

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 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 daquele 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 deste evento são null . Nenhuma ação é necessária.

cancelar

Alguns erros inesperados podem enviar um evento `cancelar` 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 de `dados` para esta causa é "Permissão negada". 2. Uma gravação acionou um streamer de evento que enviou uma grande árvore JSON que excede nosso limite, 512 MB. Os `dados` para esta causa são "A carga especificada é muito grande, solicite um local com menos dados."

auth_revoked

Os dados deste evento são uma string que indica 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 prioritárias de 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 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, 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'

Isto escreve "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 de 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" mencionado 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 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 do Firebase. Você precisará do segredo do seu projeto do Firebase, que pode ser encontrado no painel Contas de serviço da configuração do seu projeto do 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 Realtime Database 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 incorreta

Uma das seguintes condições de erro:

  • Não é possível analisar dados PUT ou POST .
  • Dados PUT ou POST ausentes.
  • A solicitação tenta PUT ou POST dados que são muito grandes.
  • A chamada da API REST contém nomes filho inválidos como parte do caminho.
  • O caminho de 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 suporta 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 Falha na pré-condição O valor ETag especificado da solicitação no cabeçalho if-match não correspondia ao valor do servidor.