Uso de la API
Puede usar cualquier URL de la base de datos en tiempo real de Firebase como punto final REST. Todo lo que necesita hacer es agregar .json
al final de la URL y enviar una solicitud desde su cliente HTTPS favorito.
Se requiere HTTPS. Firebase solo responde al tráfico encriptado para que sus datos permanezcan seguros.
GET - Lectura de datos
Los datos de su base de datos en tiempo real se pueden leer emitiendo una solicitud HTTP GET
a un punto final. El siguiente ejemplo demuestra cómo puede recuperar el nombre de un usuario que había almacenado previamente en Realtime Database.
curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK
. La respuesta contiene los datos asociados con la ruta en la solicitud GET
.
{ "first": "Jack", "last": "Sparrow" }
PUT - Escritura de datos
Puede escribir datos con una solicitud PUT
.
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'
Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK
. La respuesta contiene los datos especificados en la solicitud PUT
.
{ "first": "Jack", "last": "Sparrow" }
POST - Envío de datos
Para lograr el equivalente del método JavaScript push()
(consulte Listas de datos ), puede emitir una solicitud POST
.
curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \ 'https://[PROJECT_ID].firebaseio.com/message_list.json'
Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK
. La respuesta contiene el nombre secundario de los nuevos datos especificados en la solicitud POST
.
{ "name": "-INOQPH-aV_psbk3ZXEX" }
PARCHE - Actualización de datos
Puede actualizar elementos secundarios específicos en una ubicación sin sobrescribir los datos existentes mediante una solicitud PATCH
. Los hijos con nombre en los datos que se escriben con PATCH
se sobrescriben, pero los hijos omitidos no se eliminan. Esto es equivalente a la función update()
.
curl -X PATCH -d '{"last":"Jones"}' \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'
Una solicitud exitosa se indica mediante un código de estado HTTP 200 OK
. La respuesta contiene los datos especificados en la solicitud PATCH
.
{ "last": "Jones" }
ELIMINAR - Eliminación de datos
Puede eliminar datos con una solicitud DELETE
:
curl -X DELETE \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
Una solicitud DELETE
exitosa se indica mediante un código de estado HTTP 200 OK
con una respuesta que contiene JSON null
.
Anulación de método
Si realiza llamadas REST desde un navegador que no es compatible con los métodos anteriores, puede anular el método de solicitud realizando una solicitud POST
y configurando su método mediante el encabezado de solicitud X-HTTP-Method-Override
.
curl -X POST -H "X-HTTP-Method-Override: DELETE" \ 'https://[PROJECT_ID].firebaseio.com/users/jack/name/last.json'
También puede usar el 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'
Solicitudes condicionales
Las solicitudes condicionales, el equivalente REST de las operaciones de transacciones SDK, actualizan los datos de acuerdo con una determinada condición. Vea una descripción general del flujo de trabajo y obtenga más información sobre las solicitudes condicionales para REST en Guardar datos .
ETag de Firebase
Firebase ETag es el identificador único de los datos actuales en una ubicación específica. Si los datos cambian en esa ubicación, la ETag también cambia. El ETag de Firebase debe especificarse en el encabezado de la solicitud REST inicial (normalmente, un GET
, pero puede ser cualquier cosa que no sea PATCH
).
curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'
si-coincidencia
La condición if-match
especifica el valor de ETag para los datos que desea actualizar. Si utiliza la condición, Realtime Database solo completa las solicitudes en las que la ETag especificada en la solicitud de escritura coincide con la ETag de los datos existentes en la base de datos. Obtenga la ETag en una ubicación con una solicitud de ETag de Firebase. Si desea sobrescribir cualquier ubicación que sea nula, use null_etag
.
curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'
Respuestas esperadas
La siguiente tabla proporciona una descripción general de las respuestas esperadas para cada tipo de solicitud, según la coincidencia de ETag.
tipo de solicitud | 'X-Firebase-ETag: verdadero' | coincidencias de ETagif_match: <matching etag> | ETag no coincideif_match: <no matching etag> | |
---|---|---|---|---|
CONSEGUIR | Estado/contenido de la respuesta | 200: "<datos_en_ruta>" | 400: "...no compatible..." | 400: "...no compatible..." |
Encabezados agregados | ETag: <ETag_de_datos> | N / A | N / A | |
PONER | Estado/contenido de la respuesta | 200: "<poner_datos>" | 200: "<poner_datos>" | 412: "...Etag no coincide..." |
Encabezados agregados | ETag: <ETag_of_put_data> | N / A | ETag: <database_ETag> | |
CORREO | Estado/contenido de la respuesta | 200: "<datos_post>" | 400: "...no compatible..." | 400: "...no compatible..." |
Encabezados agregados | ETag: <ETag_of_post_data> | N / A | N / A | |
PARCHE | Estado/contenido de la respuesta | 400: "...no compatible..." | 400: "...no compatible..." | 400: "...no compatible..." |
Encabezados agregados | N / A | N / A | N / A | |
BORRAR | Estado/contenido de la respuesta | 200: nulo | 200: "<datos_después_de_colocar>" | 412: "...Etag no coincide..." |
Encabezados agregados | ETag: <ETag_of_null> | N / A | ETag: <database_ETag> |
Parámetros de consulta
La API REST de la base de datos de Firebase acepta los siguientes valores y parámetros de consulta:
token_de_acceso
Compatible con todos los tipos de solicitudes. Autentica esta solicitud para permitir el acceso a los datos protegidos por las reglas de seguridad de la base de datos en tiempo real de Firebase. Consulte la documentación de autenticación REST para obtener más información.
curl 'https://[PROJECT_ID].firebaseio/users/jack/name.json?access_token=CREDENTIAL'
poco profundo
Esta es una característica avanzada, diseñada para ayudarlo a trabajar con grandes conjuntos de datos sin necesidad de descargar todo. Establézcalo en true
para limitar la profundidad de los datos devueltos en una ubicación. Si los datos en la ubicación son una primitiva JSON (cadena, número o booleano), simplemente se devolverá su valor. Si la instantánea de datos en la ubicación es un objeto JSON, los valores de cada clave se truncarán a true
.
Argumentos | Métodos de descanso | Descripción |
---|---|---|
poco profundo | CONSEGUIR | Limite la profundidad de la respuesta. |
curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'
Tenga en cuenta que shallow
no se puede mezclar con ningún otro parámetro de consulta.
imprimir
Da formato a los datos devueltos en la respuesta del servidor.
Argumentos | Métodos de descanso | Descripción |
---|---|---|
bonito | OBTENER, PONER, PUBLICAR, PARCHE, ELIMINAR | Ver los datos en un formato legible por humanos. |
silencioso | OBTENER, PONER, PUBLICAR, PARCHE | Se utiliza para suprimir la salida del servidor al escribir datos. La respuesta resultante estará vacía y se indicará con un código de estado 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'
llamar de vuelta
Compatible solo con GET
. Para realizar llamadas REST desde un navegador web a través de dominios, puede usar JSONP para envolver la respuesta en una función de devolución de llamada de JavaScript. Agregue callback=
para que la API REST envuelva los datos devueltos en la función de devolución de llamada que especifique.
<script> function gotData(data) { console.log(data); } </script> <script src="https://[PROJECT_ID].firebaseio.com/.json?callback=gotData"></script>
formato
Si se configura para export
, el servidor codificará las prioridades en la respuesta.
Argumentos | Métodos de descanso | Descripción |
---|---|---|
exportar | CONSEGUIR | Incluya información prioritaria en la respuesta. |
curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'
descargar
Compatible solo con GET
. Si desea activar la descarga de un archivo de sus datos desde un navegador web, agregue download=
. Esto hace que el servicio REST agregue los encabezados apropiados para que los navegadores sepan guardar los datos en un archivo.
curl 'https://[PROJECT_ID].firebaseio/.json?download=myfilename.txt'
se acabó el tiempo
Use esto para limitar el tiempo que tarda la lectura en el lado del servidor. Si una solicitud de lectura no finaliza dentro del tiempo asignado, finaliza con un error HTTP 400. Esto es particularmente útil cuando espera una pequeña transferencia de datos y no desea esperar demasiado para obtener un subárbol potencialmente enorme. El tiempo de lectura real puede variar según el tamaño de los datos y el almacenamiento en caché.
Especifique timeouts
con el siguiente formato: 3ms
, 3s
o 3min
, con un número y una unidad. Si no se especifica, se aplicará el timeout
máximo de 15min
. Si el timeout
no es positivo o supera el máximo, la solicitud se rechazará con un error HTTP 400.
límite de tamaño de escritura
Para limitar el tamaño de una escritura, puede especificar el parámetro de consulta writeSizeLimit
como tiny
(objetivo = 1 s), small
(objetivo = 10 s), medium
(objetivo = 30 s), large
(objetivo = 60 s). Realtime Database estima el tamaño de cada solicitud de escritura y anula las solicitudes que llevarán más tiempo que el objetivo.
Si especifica unlimited
, se permiten escrituras excepcionalmente grandes (con una carga útil de hasta 256 MB), lo que podría bloquear las solicitudes posteriores mientras la base de datos procesa la operación actual. Las escrituras no se pueden cancelar una vez que llegan al servidor.
curl -X DELETE 'https://docs-examples.firebaseio.com/rest/delete-data.json?writeSizeLimit=medium'
Verá el siguiente mensaje de error si la escritura es demasiado grande:
Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.
Además, puede establecer el defaultWriteSizeLimit
para toda la instancia de la base de datos mediante Firebase CLI. Este límite se aplica a todas las solicitudes, incluidas las de los SDK. Las nuevas bases de datos se crean con defaultWriteSizeLimit
establecido en large
. No puede establecer defaultWriteSizeLimit
en tiny
mediante Firebase CLI.
firebase database:settings:set defaultWriteSizeLimit large
ordenar por
Consulte la sección de la guía sobre datos ordenados para obtener más información.
limitToFirst, limitToLast, startAt, endAt, equalTo
Consulte la sección de la guía sobre filtrado de datos para obtener más información.
Transmisión desde la API REST
Los extremos REST de Firebase admiten el protocolo EventSource/Server-Sent Events . Para transmitir cambios a una sola ubicación en su base de datos en tiempo real, debe hacer algunas cosas:
- Establezca el encabezado Aceptar del cliente en
"text/event-stream"
- Respete los redireccionamientos HTTP, en particular el código de estado HTTP 307
- Si la ubicación requiere permiso para leer, debe incluir el parámetro
auth
A cambio, el servidor enviará eventos con nombre a medida que cambie el estado de los datos en la URL solicitada. La estructura de estos mensajes se ajusta al protocolo EventSource
.
event: event name data: JSON encoded data payload
El servidor puede enviar los siguientes eventos:
poner
Los datos codificados en JSON son un objeto con dos claves: ruta y datos . La clave de ruta apunta a una ubicación relativa a la URL de solicitud. El cliente debe reemplazar todos los datos en esa ubicación en su caché con datos .
parche
Los datos codificados en JSON son un objeto con dos claves: ruta y datos . La clave de ruta apunta a una ubicación relativa a la URL de solicitud. Para cada clave en datos , el cliente debe reemplazar la clave correspondiente en su caché con los datos de esa clave en el mensaje.
mantener viva
Los datos de este evento son null
. No se requiere ninguna acción.
Cancelar
Algunos errores inesperados pueden enviar un evento de "cancelar" y finalizar la conexión. La causa se describe en los datos proporcionados para este evento. Algunas posibles causas son las siguientes: 1. Las reglas de seguridad de la base de datos en tiempo real de Firebase ya no permiten una lectura en la ubicación solicitada. La descripción de `datos` para esta causa es "Permiso denegado". 2. Una escritura desencadenó un transmisor de eventos que envió un gran árbol JSON que supera nuestro límite, 512 MB. Los `datos` para esta causa son "La carga útil especificada es demasiado grande, solicite una ubicación con menos datos".
autenticación_revocada
Los datos de este evento son una cadena que indica que la credencial ha caducado. Este evento se envía cuando el parámetro auth
proporcionado ya no es válido.
Aquí hay un ejemplo de un conjunto de eventos que el servidor puede 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
Se puede hacer referencia a la información de prioridad para una ubicación con un "niño virtual" llamado .priority
. Puede leer prioridades con solicitudes GET
y escribirlas con solicitudes PUT
. Por ejemplo, la siguiente solicitud recupera la prioridad del nodo users/tom
:
curl 'https://[PROJECT_ID].firebaseio/users/tom/.priority.json'
Para escribir prioridad y datos al mismo tiempo, puede agregar un elemento secundario .priority
a la carga útil de JSON:
curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom.json'
Para escribir prioridad y un valor primitivo (por ejemplo, una cadena) al mismo tiempo, puede agregar un elemento .priority
y colocar el valor primitivo en un elemento .value
:
curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \ 'https://[PROJECT_ID].firebaseio/users/tom/name/first.json'
Esto escribe "Tom"
con una prioridad de 1.0
. Las prioridades se pueden incluir en cualquier profundidad en la carga útil de JSON.
Valores del servidor
Puede escribir valores de servidor en una ubicación utilizando un valor de marcador de posición que es un objeto con una única clave .sv
. El valor de esa clave es el tipo de valor de servidor que desea configurar. Por ejemplo, la siguiente solicitud establece el valor del nodo en la marca de tiempo actual del servidor de Firebase:
curl -X PUT -d '{".sv": "timestamp"}' \ 'https://[PROJECT_ID].firebaseio/users/tom/startedAtTime.json'
También puede escribir prioridades usando los valores del servidor, usando la ruta "niño virtual" mencionada anteriormente.
Los valores de servidor admitidos incluyen:
Valor del servidor | |
---|---|
marca de tiempo | El tiempo desde la época de UNIX, en milisegundos. |
incremento | Proporcione un valor delta entero o de coma flotante, en la forma { ".sv": {"increment": <delta_value> }} , con el que incrementar atómicamente el valor actual de la base de datos. Si los datos aún no existen, la actualización establecerá los datos en el valor delta. Si el valor delta o los datos existentes son números de coma flotante, ambos valores se interpretarán como números de coma flotante y se aplicarán en el back-end como un valor doble. La aritmética doble y la representación de valores dobles siguen la semántica IEEE 754. Si hay un desbordamiento de enteros positivos/negativos, la suma se calcula como un doble. |
Recuperar y actualizar las reglas de seguridad de Firebase Realtime Database
La API de REST también se puede usar para recuperar y actualizar las reglas de seguridad de la base de datos en tiempo real de Firebase para su proyecto de Firebase. Necesitará el secreto de su proyecto de Firebase, que puede encontrar en el panel Cuentas de servicio de la configuración de su proyecto de 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 solicitudes
De manera predeterminada, las solicitudes REST se ejecutan sin autenticación y solo tendrán éxito si las reglas de la base de datos en tiempo real permiten el acceso público de lectura o escritura a los datos. Para autenticar su solicitud, use los parámetros de consulta access_token=
o auth=
.
Obtenga más información sobre la autenticación a través de la API REST en Autenticar solicitudes REST .
Condiciones de error
La API REST de Firebase Database puede devolver los siguientes códigos de error.
Códigos de estado HTTP | |
---|---|
400 Solicitud incorrecta | Una de las siguientes condiciones de error:
|
401 no autorizado | Una de las siguientes condiciones de error:
|
404 No encontrado | No se encontró la base de datos en tiempo real especificada. |
500 Error interno del servidor | El servidor devolvió un error. Consulte el mensaje de error para obtener más detalles. |
503 Servicio no disponible | La base de datos en tiempo real de Firebase especificada no está disponible temporalmente, lo que significa que no se intentó realizar la solicitud. |
412 Precondición fallida | El valor de ETag especificado de la solicitud en el encabezado if-match no coincide con el valor del servidor. |
Salvo que se indique lo contrario, el contenido de esta página está sujeto a la licencia Atribución 4.0 de Creative Commons, y los ejemplos de código están sujetos a la licencia Apache 2.0. Para obtener más información, consulta las políticas del sitio de Google Developers. Java es una marca registrada de Oracle o sus afiliados.
Última actualización: 2023-10-31 (UTC)