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 ETagif_match: <matching etag> | ETag não correspondeif_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:
|
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. |
Exceto em caso de indicação contrária, o conteúdo desta página é licenciado de acordo com a Licença de atribuição 4.0 do Creative Commons, e as amostras de código são licenciadas de acordo com a Licença Apache 2.0. Para mais detalhes, consulte as políticas do site do Google Developers. Java é uma marca registrada da Oracle e/ou afiliadas.
Última atualização 2023-10-31 UTC.