Implantar no seu site usando a API REST do Hosting

Com a API REST do Firebase Hosting, é possível realizar implantações programáticas e personalizáveis nos seus sites hospedados pelo Firebase. Use essa API REST para implantar arquivos de conteúdo e configurações de hospedagem novas ou atualizadas.

Como alternativa ao uso da interface de linha de comando (CLI) do Firebase para implantações, é possível usar a API REST do Firebase Hosting para criar de maneira programática uma nova version dos recursos para o site, fazer upload de arquivos para a versão e implantar a versão no site.

Por exemplo, com a API REST do Firebase Hosting, é possível realizar estas tarefas:

  • Programar implantações. Usando a API REST em conjunto com um cron job, é possível alterar o conteúdo hospedado pelo Firebase regularmente (por exemplo, para implantar um feriado especial ou uma versão relacionada ao evento do seu conteúdo).

  • Fazer a integração com ferramentas para desenvolvedores. É possível criar uma opção na sua ferramenta para implantar seus projetos de aplicativos da Web no Firebase Hosting usando apenas um clique (por exemplo, clicando em um botão de implantação em um ambiente de desenvolvimento integrado).

  • Automatizar as implantações quando o conteúdo estático é gerado. Quando um processo gera conteúdo estático programaticamente (por exemplo, conteúdo gerado pelo usuário, como wiki ou artigo de notícias), é possível implantar o conteúdo gerado como arquivos estáticos em vez de disponibilizá-los de forma dinâmica. Isso economiza seu caro poder computacional e disponibiliza seus arquivos de maneira mais escalonável.

Primeiro este guia descreve como ativar, autenticar e autorizar a API. Em seguida, mostra um exemplo para criar uma versão do Firebase Hosting, fazer upload dos arquivos necessários para a versão e, por último, implantá-la.

Saiba mais sobre essa API REST na documentação completa de referência da API REST do Hosting.

Antes de começar: ative a API REST

Ative a API REST do Firebase Hosting no Console de APIs do Google:

  1. Abra a página da API Firebase Hosting no Console de APIs do Google.

  2. Quando solicitado, selecione seu projeto do Firebase.

  3. Clique em Ativar na página da API Firebase Hosting.

Etapa 1: receber um token de acesso para autenticar e autorizar solicitações da API

Os projetos do Firebase oferecem suporte a contas de serviço do Google, que você pode usar para chamar APIs do servidor do Firebase do seu servidor de aplicativos ou de um ambiente confiável. Se você estiver desenvolvendo código ou implantando o app localmente, é possível usar credenciais recebidas por meio dessa conta de serviço para autorizar solicitações do servidor.

Para autenticar uma conta de serviço e autorizá-la para acessar os serviços do Firebase, gere um arquivo de chave privada no formato JSON.

Para gerar um arquivo de chave privada da conta de serviço, siga estas etapas:

  1. No Console do Firebase, abra Configurações > Contas de serviço.

  2. Clique em Gerar nova chave privada e selecione Gerar chave para confirmar.

  3. Armazene com segurança o arquivo JSON que contém a chave.

Use suas credenciais do Firebase na Biblioteca de cliente da API Google para sua linguagem preferida e recupere um token de acesso do OAuth 2.0 de curta duração:

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);
    });
  });
}

Neste exemplo, a biblioteca de cliente da API do Google autentica a solicitação com um token JSON da Web ou JWT. Para mais informações, consulte tokens JSON da web.

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();
}

O método de atualização de token é chamado automaticamente para recuperar um token atualizado após o de acesso expirar.

Etapa 2: criar uma nova versão para seu site

Sua primeira chamada de API é criar uma nova Version para seu site. Ainda neste guia, você verá como fazer upload de arquivos para essa versão e, em seguida, implantá-la no seu site.

  1. Determine o nome do site que você quer usar para implantar.

  2. Chame o endpoint versions.createusando o nome do site na chamada.

    (Opcional) É possível também transmitir um objeto de configuração do Firebase Hosting na chamada, incluindo a configuração de um cabeçalho que armazena em cache todos os arquivos por um período especificado de tempo.

    Por exemplo:

    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-name/versions
    

    Solicitação HTTP bruta

    Host: firebasehosting.googleapis.com
    
    POST /v1beta1/sites/site-name/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 chamada de API para versions.create retorna o seguinte JSON:

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

Essa resposta contém um identificador exclusivo para a nova versão, no formato: sites/site-name/versions/version-id. Você precisará deste identificador exclusivo em todo este guia para fazer referência a essa versão específica.

Etapa 3: especificar a lista de arquivos que você quer implantar

Agora que você tem seu novo identificador de versão, precisa informar ao Firebase Hosting quais arquivos quer implantar na nova versão.

Essa API exige que você identifique arquivos por meio de um hash SHA256. Dessa forma, antes de poder fazer a chamada da API, primeiro será preciso calcular um hash para cada arquivo estático, fazendo a compactação com o Gzip dos arquivos e depois pegando o hash SHA256 de cada arquivo recém-compactado.

Para esse exemplo, digamos que você queira implantar três arquivos na nova versão: file1, file2 e file3.

  1. Compacte os arquivos usando o Gzip:

    gzip file1 && gzip file2 && gzip file3

    Agora você tem três arquivos compactados file1.gz, file2.gz e file3.gz.

  2. Acesse o hash SHA256 de cada arquivo compactado:

    cat file1.gz | openssl dgst -sha256
    
    66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4
    
    cat file2.gz | openssl dgst -sha256
    
    490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083
    
    cat file3.gz | openssl dgst -sha256
    
    59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315
    

    Agora você tem os três hashes SHA256 dos três arquivos compactados.

  3. Envie esses três hashes em uma solicitação da API para o endpoint versions.populateFiles. Liste cada hash pelo caminho escolhido para o arquivo carregado (neste exemplo, /file1, /file2 e /file3).

    Por exemplo:

    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-name/versions/version-id:populateFiles
    

    Solicitação HTTP bruta

    Host: firebasehosting.googleapis.com
    
    POST /v1beta1/sites/site-name/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 chamada de API para versions.populateFiles retorna o seguinte JSON:

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

Essa resposta inclui:

  • O hash de cada arquivo que precisa ser carregado. Por exemplo, neste exemplo, o file1 já foi carregado em uma versão anterior. Dessa forma, seu hash não está incluído na lista uploadRequiredHashes.

  • O uploadUrl que é específico para a nova versão.

Na próxima etapa, para fazer upload dos dois novos arquivos, você precisará dos hashes e do uploadURL da resposta versions.populateFiles.

Etapa 4: fazer o upload dos arquivos necessários

Você precisa carregar de maneira individual cada arquivo necessário (os arquivos listados em uploadRequiredHashes da resposta versions.populateFiles na etapa anterior). Para esses uploads de arquivo, você precisará dos hashes do arquivo e do uploadUrl da etapa anterior.

  1. Anexe uma barra e o hash do arquivo ao uploadUrlpara criar um URL específico do arquivo no formato: https://upload-firebasehosting.googleapis.com/upload/sites/site-name/versions/version-id/files/file-hash.

  2. Faça o upload de todos os arquivos necessários um por um (neste exemplo, apenas file2.gz e file3.gz) para o URL específico do arquivo usando uma série de solicitações.

    Por exemplo, para carregar o file2.gz compactado:

    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-name/versions/version-id/files/file-hash
    

    Solicitação HTTP bruta

    Host: upload-firebasehosting.googleapis.com
    
    POST /upload/sites/site-name/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
    

Uploads bem-sucedidos retornam uma resposta HTTP 200 OK.

Etapa 5: atualizar o status da versão para FINALIZED

Depois de carregar todos os arquivos listados na resposta versions.populateFiles, é possível atualizar o status da sua versão para FINALIZED.

Chame o endpoint versions.patch com o campo status na sua solicitação de API definida como FINALIZED.

Por exemplo:

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-name/versions/version-id?update_mask=status

Solicitação HTTP bruta

Host: firebasehosting.googleapis.com

PATCH /v1beta1/sites/site-name/versions/version-id?update_mask=status HTTP/1.1
Authorization: Bearer access-token
Content-Type: application/json
Content-Length: 23

{"status": "FINALIZED"}

Esta chamada de API para versions.patch retorna o seguinte JSON. Verifique se status foi atualizado para FINALIZED.

{
  "name": "sites/site-name/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-name.iam.gserviceaccount.com"
  },
  "finalizeTime": "2018-12-02T14:56:13.047423Z",
  "finalizeUser": {
    "email": "your-email@domain.tld"
  },
  "fileCount": "5",
  "versionBytes": "114951"
}

Etapa 6: liberar a versão para implantação

Agora que você tem uma versão finalizada, libere-a para implantação. Para esta etapa, é necessário criar um Release da sua versão que contenha a configuração de hospedagem e todos os arquivos de conteúdo para a nova versão.

Chame o endpoint releases.create para criar sua versão.

Por exemplo:

Comando cURL

curl -H "Authorization: Bearer access-token" \
       -X POST
https://firebasehosting.googleapis.com/v1beta1/sites/site-name/releases?versionName=sites/site-name/versions/version-id

Solicitação HTTP bruta

Host: firebasehosting.googleapis.com

POST /v1beta1/sites/site-name/releases?versionName=sites/site-name/versions/version-id HTTP/1.1
Authorization: Bearer access-token

Esta chamada de API para releases.create retorna o seguinte JSON:

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

A configuração de hospedagem e todos os arquivos da nova versão devem agora ser implantados no seu site e você pode acessar seus arquivos usando os URLs:

  • https://site-name.web.app/file1
  • https://site-name.web.app/file2
  • https://site-name.web.app/file3

Esses arquivos também podem ser acessados nos URLs associados ao domínio site-name.firebaseapp.com.

Veja também sua nova versão listada no Console do Firebase na página do Hosting.