Realiza implementaciones en tu sitio con la API de REST de Hosting

La API de REST de Firebase Hosting permite realizar implementaciones programáticas y personalizables en los sitios alojados en Firebase. Usa esta API de REST para implementar contenido y configuración de Hosting nuevos o actualizados.

Puedes usar la API de REST de Firebase Hosting como alternativa a Firebase CLI para realizar implementaciones y crear de manera programática una version nueva de elementos de tu sitio, subir archivos a ella y, luego, implementarla.

Por ejemplo, con la API de REST de Firebase Hosting, puedes hacer lo siguiente:

  • Programar implementaciones: Puedes usar la API de REST junto con un trabajo cron para cambiar el contenido alojado en Firebase periódicamente (por ejemplo, para implementar una versión especial de tu contenido relacionada con la temporada navideña o algún evento especial).

  • Integrar en Herramientas para desarrolladores: En la herramienta, puedes crear una opción para implementar tus proyectos de aplicación web en Firebase Hosting con solo un clic (por ejemplo, mediante un botón de implementación en un IDE).

  • Automatizar las implementaciones cuando se genera contenido estático: Cuando un proceso genera contenido estático de manera programática (por ejemplo, contenido generado por usuarios como una wiki o artículos de noticias), puedes implementar el contenido generado como archivos estáticos en lugar de entregarlos de manera dinámica. Esto te permite ahorrar capacidad de procesamiento y entregar tus archivos de una manera más escalable.

En esta guía, se describe en primer lugar cómo habilitar, autenticar y autorizar la API. Luego, se revisa un ejemplo de cómo crear una versión de Firebase Hosting, cómo subir los archivos necesarios a ella y, por último, cómo implementarla.

Puedes obtener más información sobre esta API de REST en la documentación de referencia de la API de REST de Hosting.

Antes de comenzar: Habilita la API de REST

Sigue estos pasos para habilitar la API de REST de Firebase Hosting en la consola de APIs de Google:

  1. Abre la página de la API de Firebase Hosting en la consola de APIs de Google.

  2. Cuando se te solicite, selecciona tu proyecto de Firebase.

  3. Haz clic en Habilitar en la página de la API de Firebase Hosting.

Paso 1: Obtén un token de acceso para autenticar y autorizar las solicitudes de la API

Los proyectos de Firebase son compatibles con las cuentas de servicio de Google, por lo que puedes llamar a las API del servidor de Firebase desde tu servidor de apps o un entorno de confianza. Si desarrollas código o implementas tu aplicación de manera local, puedes usar las credenciales obtenidas mediante la cuenta de servicio para autorizar las solicitudes del servidor.

Para autenticar una cuenta de servicio y autorizar su acceso a los servicios de Firebase, debes generar un archivo de claves privadas en formato JSON.

Sigue estos pasos a fin de generar un archivo de claves privadas para la cuenta de servicio:

  1. En la consola de Firebase, abre Configuración > Cuentas de servicio.

  2. Haz clic en Generar nueva clave privada y luego en Generar clave para confirmar.

  3. Almacena de forma segura el archivo JSON que contiene la clave.

Para recuperar el token de acceso de OAuth 2.0 de corta duración, usa las credenciales de Firebase y la biblioteca cliente de Google Auth en tu lenguaje preferido, como se muestra a continuación:

node.js

const {google} = require('googleapis');
function getAccessToken() {
  return new Promise(function(resolve, reject) {
    var key = require('./service-account.json');
    var jwtClient = new google.auth.JWT(
      key.client_email,
      null,
      key.private_key,
      SCOPES,
      null
    );
    jwtClient.authorize(function(err, tokens) {
      if (err) {
        reject(err);
        return;
      }
      resolve(tokens.access_token);
    });
  });
}

En este ejemplo, la biblioteca cliente de la API de Google autentica la solicitud con un token web JSON o JWT. Para obtener más información, consulta la sección sobre los tokens web JSON.

Python

def _get_access_token():
  """Retrieve a valid access token that can be used to authorize requests.

  :return: Access token.
  """
  credentials = ServiceAccountCredentials.from_json_keyfile_name(
      'service-account.json', SCOPES)
  access_token_info = credentials.get_access_token()
  return access_token_info.access_token

Java

private static String getAccessToken() throws IOException {
  GoogleCredential googleCredential = GoogleCredential
      .fromStream(new FileInputStream("service-account.json"))
      .createScoped(Arrays.asList(SCOPES));
  googleCredential.refreshToken();
  return googleCredential.getAccessToken();
}

Cuando venza el token de acceso, se llamará al método de actualización automáticamente para obtener un token actualizado.

Paso 2: Asegúrate de que tu proyecto tenga un sitio de Hosting predeterminado

Antes de tu primera implementación en Firebase Hosting, tu proyecto de Firebase debe tener un SITE de Hosting predeterminado.

  1. Llama al extremo sites.list para verificar si tu proyecto ya tiene un sitio de Hosting predeterminado.

    Por ejemplo:

    Comando cURL

    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites

    Solicitud HTTPS sin procesar

    Host: firebasehosting.googleapis.com

POST /v1beta1/projects/PROJECT_ID/sites HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

    • Si uno de los sitios tiene "type": "DEFAULT_SITE", significa que tu proyecto ya tiene un sitio de Hosting predeterminado. Omite el resto de este paso y continúa con el siguiente paso: Crea una versión nueva para tu sitio.

    • Si obtienes un array vacío, no tienes un sitio de Hosting predeterminado. Completa el resto de este paso.

  2. Elige el SITE_ID de tu sitio de Hosting predeterminado. Ten en cuenta lo siguiente cuando elijas este SITE_ID:

    • Este SITE_ID se usa para crear tus subdominios de Firebase predeterminados:
      SITE_ID.web.app y SITE_ID.firebaseapp.com.

    • Un SITE_ID tiene los siguientes requisitos:

      • Debe ser una etiqueta de nombre de host válida, por lo que no puede contener ., _, etcétera.
      • Debe tener un máximo de 30 caracteres.
      • Debe ser único a nivel global en Firebase.

    Ten en cuenta que, en general, recomendamos usar el ID del proyecto como el SITE_ID del sitio de Hosting predeterminado. Descubre cómo encontrar este ID en Información sobre los proyectos de Firebase.

  3. Llama al extremo sites.create para crear el sitio de Hosting predeterminado y usa el SITE_ID que quieras como parámetro siteId.

    Por ejemplo:

    Comando cURL

    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

https://firebasehosting.googleapis.com/v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID

    Solicitud HTTPS sin procesar

    Host: firebasehosting.googleapis.com

POST /v1beta1/projects/PROJECT_ID/sites?siteId=SITE_ID
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

    Esta llamada a la API a sites.create muestra el siguiente código JSON:

    {
  "name": "projects/PROJECT_ID/sites/SITE_ID",
  "defaultUrl": "https://SITE_ID.web.app",
  "type": "DEFAULT_SITE"
}

Paso 3: Crea una versión nueva para tu sitio

Tu primera llamada a la API será con el fin de crear una Version nueva para el sitio. Más adelante en esta guía, aprenderás a subir archivos a la versión y la implementarás en el sitio.

  1. Determina el SITE_ID del sitio en el que quieres realizar la implementación.

  2. Llama al extremo versions.create con el SITE_ID.

    También puedes pasar un objeto de configuración de Firebase Hosting en la llamada, incluida la configuración de un encabezado que almacene en caché todos los archivos durante un período determinado (opcional).

    Por ejemplo:

    Comando cURL

    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       -d '{
             "config": {
               "headers": [{
                 "glob": "**",
                 "headers": {
                   "Cache-Control": "max-age=1800"
                 }
               }]
             }
           }' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions

    Solicitud HTTPS sin procesar

    Host: firebasehosting.googleapis.com

POST /v1beta1/sites/SITE_ID/versions HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Content-Length: 134

{
  "config": {
    "headers": [{
      "glob": "**",
      "headers": {
        "Cache-Control": "max-age=1800"
      }
    }]
  }
}

Esta llamada a la API a versions.create muestra el siguiente código JSON:

{
  "name": "sites/SITE_ID/versions/VERSION_ID",
  "status": "CREATED",
  "config": {
    "headers": [{
      "glob": "**",
      "headers": {
        "Cache-Control": "max-age=1800"
      }
    }]
  }
}

Esta respuesta contiene un identificador único para la versión nueva en el siguiente formato: sites/SITE_ID/versions/VERSION_ID. En esta guía, necesitarás el identificador único para hacer referencia a la versión específica.

Paso 4: Especifica la lista de archivos que quieres implementar

Ahora que tienes el identificador de la versión nueva, deberás indicarle a Firebase Hosting qué archivos finalmente querrás implementar en ella.

Ten en cuenta que Hosting tiene un límite de tamaño máximo de 2 GB para archivos individuales.

Esta API exige que identifiques los archivos mediante un hash SHA256. Por lo tanto, antes de realizar la llamada a la API, debes calcular un hash para cada archivo estático. Puedes hacerlo si aplicas compresión gzip a los archivos y, luego, tomas el hash SHA256 de cada archivo recién comprimido.

Para continuar con nuestro ejemplo, supongamos que quieres implementar tres archivos en la versión nueva: file1, file2 y file3.

  1. Aplica compresión gzip a los archivos:

    gzip file1 && gzip file2 && gzip file3

    Ahora tienes tres archivos comprimidos: file1.gz, file2.gz y file3.gz.

  2. Obtén el hash SHA256 de cada archivo comprimido:

    cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

    cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

    cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

    Ahora tienes tres hash SHA256 correspondientes a los tres archivos comprimidos.

  3. Envía los tres hash en una solicitud a la API al extremo versions.populateFiles. Enumera cada hash según la ruta deseada para cada archivo que se suba (en este ejemplo, /file1, /file2 y /file3).

    Por ejemplo:

    Comando cURL

    $ curl -H "Content-Type: application/json" \
         -H "Authorization: Bearer ACCESS_TOKEN" \
         -d '{
               "files": {
                 "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4",
                 "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",
                 "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"
               }
             }' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles

    Solicitud HTTPS sin procesar

    Host: firebasehosting.googleapis.com

POST /v1beta1/sites/SITE_ID/versions/VERSION_ID:populateFiles HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Content-Length: 181

{
  "files": {
    "/file1": "66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4",
    "/file2": "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",
    "/file3": "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"
  }
}

Esta llamada a la API a versions.populateFiles muestra el siguiente código JSON:

{
  "uploadRequiredHashes": [
    "490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083",
    "59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315"
  ],
  "uploadUrl": "https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files"
}

La respuesta incluye los siguientes elementos:

  • El hash de cada archivo que se debe subir. En este ejemplo, file1 ya se subió en una versión anterior, por lo que su hash no se incluye en la lista uploadRequiredHashes.

  • La uploadUrl específica de la versión nueva.

En el próximo paso para subir los dos archivos nuevos, necesitarás los hash y la uploadURL de la respuesta versions.populateFiles.

Paso 5: Sube los archivos requeridos

Deberás subir por separado cada archivo requerido (los que se enumeraron en uploadRequiredHashes de la respuesta versions.populateFiles en el paso anterior). Para ello, necesitarás los hash de los archivos y la uploadUrl del paso anterior.

  1. Agrega una barra diagonal y el hash del archivo a la uploadUrl para crear una URL específica del archivo con el siguiente formato: https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH.

  2. Sube uno por uno todos los archivos necesarios (en este ejemplo, solo file2.gz y file3.gz) a la URL específica del archivo con varias solicitudes.

    Por ejemplo, para subir el archivo comprimido file2.gz, haz lo siguiente:

    Comando cURL

    curl -H "Authorization: Bearer ACCESS_TOKEN" \
       -H "Content-Type: application/octet-stream" \
       --data-binary @./file2.gz \
https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH

    Solicitud HTTPS sin procesar

    Host: upload-firebasehosting.googleapis.com

POST /upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/octet-stream
Content-Length: 500

content-of-file2.gz

Cuando las cargas se completan correctamente, se muestra una respuesta HTTPS 200 OK.

Paso 6: Actualiza el estado de la versión a FINALIZADO

Después de subir todos los archivos que se indican en la respuesta versions.populateFiles, puedes actualizar el estado de la versión a FINALIZED.

Llama al extremo versions.patch. Para ello, el campo status se debe configurar como FINALIZED en la solicitud a la API.

Por ejemplo:

Comando cURL

curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       -X PATCH \
       -d '{"status": "FINALIZED"}' \
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status

Solicitud HTTPS sin procesar

Host: firebasehosting.googleapis.com

PATCH /v1beta1/sites/SITE_ID/versions/VERSION_ID?update_mask=status HTTP/1.1
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
Content-Length: 23

{"status": "FINALIZED"}

Esta llamada a la API a versions.patch muestra el siguiente código JSON: Comprueba que status se haya actualizado a FINALIZED.

{
  "name": "sites/SITE_ID/versions/VERSION_ID",
  "status": "FINALIZED",
  "config": {
    "headers": [{
      "glob": "**",
      "headers": {"Cache-Control": "max-age=1800"}
    }]
  },
  "createTime": "2018-12-02T13:41:56.905743Z",
  "createUser": {
    "email": "SERVICE_ACCOUNT_EMAIL@SITE_ID.iam.gserviceaccount.com"
  },
  "finalizeTime": "2018-12-02T14:56:13.047423Z",
  "finalizeUser": {
    "email": "USER_EMAIL@DOMAIN.tld"
  },
  "fileCount": "5",
  "versionBytes": "114951"
}

Paso 7: Actualiza la versión para implementarla

Ahora que tienes una versión finalizada, actualízala para su implementación. En este paso, deberás crear una Release de tu versión que contenga la configuración del hosting y todos los archivos de contenido de la versión nueva.

Llama al extremo releases.create para crear la versión.

Por ejemplo:

Comando cURL

curl -H "Authorization: Bearer ACCESS_TOKEN" \
       -X POST
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID

Solicitud HTTPS sin procesar

Host: firebasehosting.googleapis.com

POST /v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID HTTP/1.1
Authorization: Bearer ACCESS_TOKEN

Esta llamada a la API a releases.create muestra el siguiente código JSON:

{
  "name": "sites/SITE_ID/releases/RELEASE_ID",
  "version": {
    "name": "sites/SITE_ID/versions/VERSION_ID",
    "status": "FINALIZED",
    "config": {
    "headers": [{
      "glob": "**",
      "headers": {"Cache-Control": "max-age=1800"}
    }]
  }
  },
  "type": "DEPLOY",
  "releaseTime": "2018-12-02T15:14:37Z"
}

La configuración del hosting y todos los archivos de la versión nueva deberían estar implementados en tu sitio, y deberías poder acceder a ellos con las siguientes URL:

  • https://SITE_ID.web.app/file1
  • https://SITE_ID.web.app/file2
  • https://SITE_ID.web.app/file3

También se puede acceder a estos archivos en las direcciones de URL asociadas al dominio SITE_ID.firebaseapp.com.

Además, puedes ver la actualización nueva en el panel de Hosting de Firebase console.