API REST de base de datos de Firebase

Uso de API

Puede utilizar cualquier URL de Firebase Realtime Database 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 cifrado para que sus datos permanezcan seguros.

Puede elegir la región en la que crear una instancia de Realtime Database. La elección de la región afecta la URL de la base de datos. Los ejemplos en esta página son para la región us-central1 , con el esquema de URL <dbname>.firebaseio.com . Para conocer las regiones y los esquemas de URL admitidos actualmente, consulte el tema de las guías sobre cómo seleccionar ubicaciones en proyectos de Firebase .

OBTENER - 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'

En los ejemplos de esta página, reemplazarías [PROJECT_ID] con el identificador de tu proyecto de Firebase.

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 push() de JavaScript (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 niños específicos en una ubicación sin sobrescribir los datos existentes mediante una solicitud PATCH . Los hijos nombrados en los datos que se escriben con PATCH se sobrescriben, pero los hijos omitidos no se eliminan. Esto es equivalente a la función JavaScript 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" }

BORRAR - 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 admite 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 utilizar 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 transacción del 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 de REST en Guardar datos .

Etiqueta ET de base de fuego

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. La ETag de Firebase se debe especificar 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 coincide

La condición if-match especifica el valor de ETag para los datos que desea actualizar. Si usa la condición, Realtime Database solo completa solicitudes donde 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, utilice 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 etiqueta ET if_match: <matching etag>	ETag no coincide if_match: <no matching etag>
CONSEGUIR	Estado/contenido de la respuesta	200: "<datos_en_ruta>"	400: "...no compatible..."	400: "...no compatible..."
	Encabezados agregados	Etiqueta ET: <ETag_of_data>	N / A	N / A
PONER	Estado/contenido de la respuesta	200: "<poner_datos>"	200: "<poner_datos>"	412: "...ETag no coincide..."
	Encabezados agregados	Etiqueta ET: <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	Etiqueta ET: <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_put>"	412: "...ETag no coincide..."
	Encabezados agregados	Etiqueta ET: <ETag_of_null>	N / A	ETag: <database_ETag>

Parámetros de consulta

La API REST de Firebase Database acepta los siguientes parámetros y valores de consulta:

token_acceso

Compatible con todo tipo 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 detalles.

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

poco profundo

Esta es una característica avanzada, diseñada para ayudarle a trabajar con grandes conjuntos de datos sin necesidad de descargarlo todo. Establezca esto 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 combinar con ningún otro parámetro de consulta.

imprimir

Formatea los datos devueltos en la respuesta del servidor.

Argumentos	Métodos de descanso	Descripción
bonito	OBTENER, PONER, PUBLICAR, PARCHEAR, BORRAR	Vea los datos en un formato legible por humanos.
silencioso	OBTENER, PONER, PUBLICAR, PARCHEAR	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 únicamente con GET . Para realizar llamadas REST desde un navegador web entre dominios, puede usar JSONP para encapsular la respuesta en una función de devolución de llamada de JavaScript. Agregue callback= para que la API REST incluya 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 únicamente con GET . Si desea activar una descarga de archivos 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'

Copias de seguridad privadas : no recomendamos utilizar la API REST para realizar copias de seguridad periódicas de su base de datos en tiempo real. En su lugar, configura las copias de seguridad privadas de Firebase .

se acabó el tiempo

Utilice 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 quiere esperar demasiado para recuperar 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 usando 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 excede el máximo, la solicitud será rechazada con un error HTTP 400.

escribirTamañoLimit

Nota: Este parámetro se aplica tanto a operaciones de eliminación como de escritura.

Para limitar el tamaño de una escritura, puede especificar el parámetro de consulta writeSizeLimit como tiny (destino=1s), small (destino=10s), medium (destino=30s), large (destino=60s). Realtime Database estima el tamaño de cada solicitud de escritura y cancela las solicitudes que tardarán más que el tiempo objetivo.

Si especifica unlimited , se permiten escrituras excepcionalmente grandes (con una carga útil de hasta 256 MB), lo que podría bloquear 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 configurar 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 SDK. Las nuevas bases de datos se crean con defaultWriteSizeLimit establecido en large . No puedes configurar defaultWriteSizeLimit en tiny usando Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

Eliminación grande intencional: para eliminar un nodo grande, considere usar Firebase CLI, que realiza eliminaciones fragmentadas de manera elegante. Las eliminaciones grandes a través del cliente o el SDK de administración pueden bloquear su base de datos hasta que se complete la eliminación.

firebase database:remove /large/path/to/delete

Consulte esta publicación de blog para obtener más información.

ordenar por

Consulte la sección de la guía sobre datos ordenados para obtener más información.

límiteParaPrimero, límiteParaÚltimo, inicioEn, finEn, igualA

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 puntos finales REST de Firebase admiten el protocolo EventSource/Eventos enviados por el servidor . Para transmitir cambios a una única 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 de lectura, 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 "cancelación" y finalizar la conexión. La causa se describe en los datos proporcionados para este evento. Algunas causas potenciales 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 los "datos" para esta causa es "Permiso denegado". 2. Una escritura desencadenó un transmisor de eventos que envió un árbol JSON grande que excede 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".

auth_revoked

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.

A continuación se muestra un conjunto de ejemplos 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 de 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 de los 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 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 hijo .priority y poner el valor primitivo en un hijo .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 JSON.

Valores del servidor

Puede escribir valores del 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 del servidor que desea establecer. Por ejemplo, la siguiente solicitud establece el valor del nodo en la marca de tiempo actual del servidor Firebase:

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

También puede escribir prioridades utilizando los valores del servidor, utilizando la ruta "secundaria virtual" indicada anteriormente.

Los valores de servidor admitidos incluyen:

Valor del servidor
marca de tiempo	El tiempo transcurrido desde la época UNIX, en milisegundos.
incremento	Proporcione un valor delta entero o de punto flotante, en el formato { ".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 los establecerá en el valor delta. Si cualquiera de los valores delta o los datos existentes son números de punto flotante, ambos valores se interpretarán como números de punto 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 positivo/negativo, la suma se calcula como un doble.

Recuperar y actualizar las reglas de seguridad de la base de datos en tiempo real de Firebase

La API REST también se puede utilizar 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 forma 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, utilice 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 Petición Incorrecta	Una de las siguientes condiciones de error: No se pueden analizar datos PUT o POST . Faltan datos PUT o POST . La solicitud intenta PUT o POST datos que son demasiado grandes. La llamada a la API REST contiene nombres secundarios no válidos como parte de la ruta. La ruta de llamada de la API REST es demasiado larga. La solicitud contiene un valor de servidor no reconocido. El índice de la consulta no está definido en las reglas de seguridad de la base de datos en tiempo real de Firebase . La solicitud no admite uno de los parámetros de consulta especificados. La solicitud combina parámetros de consulta con una solicitud GET superficial.
401 No autorizado	Una de las siguientes condiciones de error: El token de autenticación ha caducado. El token de autenticación utilizado en la solicitud no es válido. Error al autenticar con un token de acceso. La solicitud viola las reglas de seguridad de la base de datos en tiempo real de Firebase.
404 No encontrado	No se encontró la base de datos en tiempo real especificada.
Error interno de servidor 500	El servidor devolvió un error. Consulte el mensaje de error para obtener más detalles.
503 Servicio no Disponible	La Firebase Realtime Database especificada no está disponible temporalmente, lo que significa que no se intentó realizar la solicitud.
412 Condición previa fallida	El valor ETag especificado de la solicitud en el encabezado if-match no coincidía con el valor del servidor.