API de REST de Firebase Database

Uso de API

Puedes usar cualquier URL de Firebase Realtime Database como extremo de REST. Todo lo que necesitas agregar .json al final de la URL y enviar una solicitud desde tu cliente HTTPS favorito.

Se requiere HTTPS. Firebase solo responde al tráfico encriptado para que tus datos permanezcan seguros.

Puedes elegir la región en la que deseas crear una instancia de Realtime Database. Elección de la región afecta la URL de la base de datos. Los ejemplos de esta página corresponden a la región us-central1, con Esquema de URL <dbname>.firebaseio.com. Para regiones y URL admitidas actualmente esquemas, consulta el tema de las guías para seleccionar ubicaciones en proyectos de Firebase.

GET: Lectura de datos

Los datos de tu Realtime Database se pueden leer con una emisión HTTP GET a un extremo. El siguiente ejemplo demuestra cómo podrías recuperar el ID de un usuario que habías almacenado en Realtime Database.

curl 'https://[PROJECT_ID].firebaseio.com/users/jack/name.json'

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

Una solicitud correcta se indica mediante un código de estado HTTP 200 OK. La respuesta contiene los datos asociados con el ruta de acceso en la solicitud GET.

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

PUT: escritura de datos

Puedes 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 correcta se indica mediante un código de estado HTTP 200 OK. La respuesta contiene los datos especificados en el PUT solicitud.

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

POST: Envío de datos

Para lograr el equivalente de push() de JavaScript (consulta las Listas de datos) puedes emitir una solicitud POST.

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio.com/message_list.json'

Un estado HTTP 200 OK indica una solicitud correcta código. La respuesta contiene el nombre secundario de los datos nuevos se especifica en la solicitud POST.

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

PATCH: Actualización de datos

Puedes actualizar elementos secundarios específicos en una ubicación sin reemplazarlos datos existentes mediante una solicitud PATCH Hijos nombrados en los datos que se escriben con PATCH se reemplazan, pero se omiten. no se borran los niños. Esto es equivalente a la secuencia de comandos función update().

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio.com/users/jack/name/.json'

Un estado HTTP 200 OK indica una solicitud correcta código. La respuesta contiene los datos especificados en el PATCH solicitud.

{ "last": "Jones" }

DELETE: eliminación de datos

Puedes borrar 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 realizas llamadas REST desde un navegador que no admite las métodos anteriores, puedes anular el método de la solicitud con una POST y la configuración de tu método mediante el encabezado de la 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 puedes 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 de REST de las operaciones de transacción del SDK, actualizan los datos según una condición determinada. Consulta una descripción general del flujo de trabajo y obtén más información sobre las solicitudes condicionales para REST en Cómo guardar datos.

ETag de Firebase

La ETag de Firebase es el identificador único de los datos actuales en una ubicación especificada. Si el botón si los datos cambian en esa ubicación, la ETag también cambia. El ETag de Firebase se debe especificar en el para la solicitud de REST inicial (por lo general, un GET, pero puede ser cualquier otro valor que no sea PATCH).

curl -i 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'X-Firebase-ETag: true'

if-match

La condición if-match especifica el valor de ETag para los datos que deseas actualizar. Si usas la condición, Realtime Database solo completa las solicitudes en las que la ETag especificada en el coincide con la ETag de los datos existentes en la base de datos. Obtén el ETag en una ubicación con una solicitud de ETag de Firebase. Si deseas sobrescribir cualquier ubicación que null, usa null_etag.

curl -iX PUT -d '11' 'https://[PROJECT_ID].firebaseio.com/posts/12345/upvotes.json' -H 'if-match: [ETAG_VALUE]'

Respuestas esperadas

En la siguiente tabla, se 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: true"	La ETag coincide con if_match: <matching etag>	La ETag no coincide con if_match: <no matching etag>
OBTÉN	Estado/contenido de la respuesta	200: “<data_at_path>”	400: "...no compatible..."	400: "...no compatible..."
	Encabezados agregados	ETag: <ETag_of_data>	N/A	N/A
PON	Estado/contenido de la respuesta	200: “<put_data>”	200: “<put_data>”	412: “...ETag no coincide...”
	Encabezados agregados	ETag: <ETag_of_put_data>	N/A	ETag: <database_ETag>
PUBLICAR	Estado/contenido de la respuesta	200: “<post_data>”	400: "...no compatible..."	400: "...no compatible..."
	Encabezados agregados	ETag: <ETag_of_post_data>	N/A	N/A
PATCH	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: “<data_after_put>”	412: “...ETag no coincide...”
	Encabezados agregados	ETag: <ETag_of_null>	N/A	ETag: <database_ETag>

Parámetros de búsqueda

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

access_token

Es compatible con todos los tipos de solicitud. Autentica esta solicitud para permitir acceso a los datos protegidos por Firebase Realtime Database Security Rules. Consulta el Documentación de autenticación de REST para obtener más detalles

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

shallow

Se trata de una función avanzada, diseñada para ayudarte a trabajar con modelos conjuntos de datos sin tener que descargarlo todo. Establecer como true para limitar la profundidad de los datos que se muestran en una ubicación. Si los datos en la ubicación son un primitivo de JSON (cadena, número o booleano), su valor simplemente se devolverá. Si el botón instantánea de datos en la ubicación es un objeto JSON, el los valores de cada clave se truncarán a true.

Argumentos	Métodos REST	Descripción
superficial	GET	Limita la profundidad de la respuesta.

curl 'https://[PROJECT_ID].firebaseio/.json?shallow=true'

Ten en cuenta que shallow no se puede combinar con ninguna otra consulta parámetros.

print

Da formato a los datos que se muestran en la respuesta del servidor.

Argumentos	Métodos REST	Descripción
bonito	GET, PUT, POST, PATCH y DELETE	Visualizar los datos en un formato legible por humanos
silencioso	GET, PUT, POST o PATCH	Se usa para suprimir la salida del servidor cuando se escriben datos. La respuesta resultante estará vacía y se indicará 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'

callback

Solo es compatible con GET. Realizar llamadas de REST desde un navegador web entre dominios, puedes usar JSONP para unir la respuesta en un código función de devolución de llamada. Agrega callback= para unir la API de REST los datos devueltos en la función de devolución de llamada que especifiques.

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

formato

Si se establece en export, el servidor codificará las prioridades en la respuesta.

Argumentos	Métodos REST	Descripción
exportar	GET	Incluye información de prioridad en la respuesta.

curl 'https://[PROJECT_ID].firebaseio.com/.json?format=export'

descarga

Solo es compatible con GET. Si quieres activar un archivo descarga de datos de un navegador web, agrega download=. Esto hace que el servicio de REST agregue los encabezados adecuados para que los navegadores saben que deben guardar los datos en un archivo.

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

Copias de seguridad privadas: No recomendamos usar la API de REST para crear copias de seguridad del Realtime Database En cambio, configúralo con Firebase Copias de seguridad privadas

tiempo de espera agotado

Úsalo para limitar el tiempo que tarda la lectura en el servidor. Si una operación de lectura no finaliza en el tiempo asignado, termina con una solicitud error 400. Esto es muy útil cuando esperas que la transferencia de datos sea pequeña y no queremos esperar demasiado para recuperar un subárbol potencialmente enorme. Real el tiempo de lectura puede variar según el tamaño de los datos y el almacenamiento en caché.

Especifica timeouts con el siguiente formato: 3ms. 3s o 3min, con un número y una unidad. Si no es así especificado, la timeout máxima de 15min será se aplicó. Si el valor de timeout no es positivo o excede el máximo, la solicitud se rechazará con un error HTTP 400.

writeSizeLimit

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

Para limitar el tamaño de una operación de 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 se anula solicitudes que tardarán más que el tiempo objetivo.

Si especificas unlimited, escrituras excepcionalmente grandes (con carga útil de hasta 256 MB) están permitidos, lo que podría bloquear las solicitudes posteriores mientras la base de datos procesa el 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'

Si la escritura es demasiado grande, verás el siguiente mensaje de error:

Error: WRITE_TOO_BIG: Data to write exceeds the maximum size that can be modified with a single request.

Además, puedes configurar el defaultWriteSizeLimit para toda la base de datos. con Firebase CLI. Este límite se aplica a todas las solicitudes, incluidas las que provienen de SDKs. Se crean bases de datos nuevas con defaultWriteSizeLimit establecido en large. No puedes configurar defaultWriteSizeLimit como tiny con Firebase CLI.

firebase database:settings:set defaultWriteSizeLimit large

Eliminación intencional de gran tamaño: Para borrar un nodo grande, considera usar Firebase CLI, que ejecuta eliminaciones fragmentadas con facilidad. Las eliminaciones grandes a través del cliente o del SDK de Admin pueden bloquear tu base de datos hasta que se complete la eliminación.

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

Consulta esta entrada de blog para obtener más información.

orderBy

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

limitToFirst, limitToLast, startAt, endAt, equalTo

Consulta la sección en la guía sobre filtrar datos para más información.

Transmisión desde la API de REST

Los extremos de REST de Firebase admiten la Eventos de EventSource / enviados por el servidor protocolo. Para transmitir los cambios a una sola ubicación de tu Realtime Database, sigue estos pasos: debes hacer lo siguiente:

• Establecer el encabezado Accept del cliente en "text/event-stream"
• Respetar los redireccionamientos HTTP; específicamente, el código de estado HTTP 307.
• Si la ubicación requiere permiso de lectura, debes incluir el Parámetro auth

A cambio, el servidor enviará eventos con nombre como el estado de los datos en los cambios de URL solicitados. La estructura de estos mensajes se ajusta a el protocolo EventSource.

event: event name
data: JSON encoded data payload

El servidor puede enviar los siguientes eventos:

put

Los datos con codificación JSON son un objeto con dos claves: path y datos. La clave path apunta a una en relación con la URL de la solicitud. El cliente debe reemplazar todos los datos que se encuentran en esa ubicación en su caché con data.

patch

Los datos con codificación JSON son un objeto con dos claves: path y datos. La clave path apunta a una en relación con la URL de la solicitud. Para cada clave en data, el cliente debe reemplazar el correspondiente en su caché con los datos de esa clave en el mensaje.

keep-alive

Los datos de este evento son null. No es necesario que realices ninguna acción.

cancelar

Algunos errores inesperados pueden enviar un evento "cancel" y finalizar la conexión. La causa se describe en los datos proporcionados para este evento. Algunas causas potenciales son las siguientes: sigue: 1) Firebase Realtime Database Security Rules ya no permite una lectura en la ubicación solicitada. El La descripción "data" de esta causa es "Permiso denegado". 2. Una operación de escritura activó un transmisor de eventos que envió un gran árbol JSON que supera nuestro límite. 512MB. El `data` para esta causa es "La carga útil especificada es demasiado grande. Solicita una 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 elemento auth proporcionado ya no es válido.

Este es un ejemplo de 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 prioritaria de una ubicación con una "hijo virtual" con el nombre .priority. Puedes leer las prioridades con GET y las escribe 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 prioridades y datos al mismo tiempo, puedes agregar una .priority secundario 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 una prioridad y un valor primitivo (p.ej., una cadena) al mismo tiempo, puedes agregar un elemento secundario .priority y colocar el valor primitivo En un elemento secundario .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

Puedes escribir valores de servidor en una ubicación usando un valor de marcador de posición que es un objeto con una sola clave .sv. El valor de esa clave es el tipo de valor de servidor que deseas establecer. Por ejemplo, el siguiente request establece el valor del nodo en el valor actual marca de tiempo:

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

También puedes escribir prioridades usando valores de servidor mediante el "hijo virtual" de la ruta que se indica arriba.

Entre los valores de servidor admitidos, se incluyen los siguientes:

Valor del servidor
timestamp	Indica el tiempo transcurrido desde la época UNIX, en milisegundos.
incremento	Proporciona un número entero o un valor delta de punto flotante { ".sv": {"increment": <delta_value> }}, con el que se usará incrementar el valor actual de la base de datos. Si los datos aún no existen, se establecerá la actualización los datos al valor delta. Si el valor delta o los datos existentes están flotantes números de punto, ambos valores se interpretarán como números de punto flotante y se aplicarán en el el backend como un valor doble. La aritmética doble y la representación de los valores dobles siguen Semántica de IEEE 754. Si hay un desbordamiento de números enteros positivos o negativos, la suma se calcula como un doble.

Recuperando y actualizando Firebase Realtime Database Security Rules

La API de REST también se puede usar para recuperar y actualizar el Firebase Realtime Database Security Rules para tu proyecto de Firebase. Necesitarás el secreto de tu proyecto de Firebase, que que puedes encontrar en la Panel Cuentas de servicio del directorio de tu proyecto de Firebase del lugar.

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'

Autentica solicitudes

De forma predeterminada, las solicitudes de REST se ejecutan sin autenticación y solo tendrán éxito si la Las reglas Realtime Database permiten el acceso público de lectura o escritura a los datos. Para autenticar tu solicitud, usa el Parámetros de consulta access_token= o auth=.

Obtén más información sobre la autenticación a través de la API de REST en Autentica solicitudes de REST.

Condiciones de error

La API de REST de Firebase Database puede mostrar los siguientes códigos de error.

Códigos de estado de HTTP
400 Solicitud incorrecta	Una de las siguientes condiciones de error: No se pueden analizar los datos de PUT o POST. Faltan datos de PUT o POST. La solicitud intenta ingresar datos de PUT o POST es demasiado grande. La llamada a la API de REST contiene nombres secundarios no válidos como parte de la ruta de acceso. La ruta de acceso de la llamada de la API de REST es demasiado larga. La solicitud contiene un valor de servidor no reconocido. El índice de la consulta no está definido en tu Firebase Realtime Database Security Rules La solicitud no admite uno de los parámetros de consulta que se especificó. La solicitud mezcla parámetros de consulta con una solicitud GET superficial.
401 Sin autorización	Una de las siguientes condiciones de error: El token de autenticación caducó. El token de autenticación que se usó en la solicitud no es válido. Error en autenticación con access_token. La solicitud infringe tu Firebase Realtime Database Security Rules
404 No se encuentra	No se encontró el Realtime Database especificado.
500 Error interno del servidor	El servidor mostró un error. Consulta el mensaje de error para obtener más información más detalles.
503 Servicio no disponible	La Firebase Realtime Database especificada no está disponible temporalmente. lo que significa que la solicitud no se intentó.
412 Error de condición previa	El valor de ETag especificado de la solicitud en el encabezado if-match no coincide con el valor del servidor.