Distribuisci sul tuo sito utilizzando l'API REST di hosting

L' API REST di Firebase Hosting consente distribuzioni programmatiche e personalizzabili sui tuoi siti ospitati su Firebase. Utilizza questa API REST per distribuire contenuti e configurazioni di hosting nuovi o aggiornati.

In alternativa all'utilizzo della CLI Firebase per le distribuzioni, puoi utilizzare l'API REST di Firebase Hosting per creare a livello di codice una nuova version delle risorse per il tuo sito, caricare i file nella versione, quindi distribuire la versione sul tuo sito.

Ad esempio, con l'API REST di Firebase Hosting, puoi:

  • Pianificazione distribuzioni. Utilizzando l'API REST insieme a un processo cron, puoi modificare i contenuti ospitati da Firebase secondo una pianificazione regolare (ad esempio, per distribuire una versione speciale dei tuoi contenuti correlata a festività o eventi).

  • Integrazione con strumenti per sviluppatori. Puoi creare un'opzione nel tuo strumento per distribuire i tuoi progetti di app Web su Firebase Hosting utilizzando un solo clic (ad esempio, facendo clic su un pulsante di distribuzione all'interno di un IDE).

  • Automatizza le distribuzioni quando viene generato contenuto statico. Quando un processo genera contenuto statico a livello di codice (ad esempio, contenuto generato dall'utente come un wiki o un articolo di notizie), è possibile distribuire il contenuto generato come file statici anziché servirli dinamicamente. Ciò ti consente di risparmiare costosa potenza di elaborazione e di gestire i tuoi file in modo più scalabile.

Questa guida descrive innanzitutto come abilitare, autenticare e autorizzare l'API. Quindi questa guida illustra un esempio per creare una versione di Firebase Hosting, per caricare i file richiesti nella versione e infine per distribuire la versione.

Puoi anche saperne di più su questa API REST nella documentazione di riferimento completa dell'API REST di hosting .

Prima di iniziare: abilita l'API REST

Devi abilitare l'API REST di Firebase Hosting nella console delle API di Google:

  1. Apri la pagina API Firebase Hosting nella console API di Google.

  2. Quando richiesto, seleziona il tuo progetto Firebase.

  3. Fai clic su Abilita nella pagina API di hosting Firebase.

Passaggio 1: ottieni un token di accesso per autenticare e autorizzare le richieste API

I progetti Firebase supportano gli account di servizio Google, che puoi utilizzare per chiamare le API del server Firebase dal server dell'app o dall'ambiente attendibile. Se stai sviluppando codice localmente o distribuendo la tua applicazione in locale, puoi utilizzare le credenziali ottenute tramite questo account di servizio per autorizzare le richieste del server.

Per autenticare un account di servizio e autorizzarlo ad accedere ai servizi Firebase, devi generare un file di chiave privata in formato JSON.

Per generare un file di chiave privata per il tuo account di servizio:

  1. Nella console Firebase, apri Impostazioni > Account di servizio .

  2. Fare clic su Genera nuova chiave privata , quindi confermare facendo clic su Genera chiave .

  3. Archivia in modo sicuro il file JSON contenente la chiave.

Utilizza le tue credenziali Firebase insieme alla libreria Auth di Google per la tua lingua preferita per recuperare un token di accesso OAuth 2.0 di breve durata:

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

In questo esempio, la libreria client dell'API di Google autentica la richiesta con un token Web JSON o JWT. Per ulteriori informazioni, consulta Token Web JSON .

Pitone

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

Giava

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

Dopo la scadenza del token di accesso, il metodo di aggiornamento del token viene chiamato automaticamente per recuperare un token di accesso aggiornato.

Passaggio 2: assicurati che il tuo progetto abbia un sito di hosting predefinito

Prima della prima distribuzione su Firebase Hosting, il tuo progetto Firebase deve avere un SITE di hosting predefinito.

  1. Controlla se il tuo progetto ha già un sito di hosting predefinito chiamando l'endpoint sites.list .

    Per esempio:

    comando cURL

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

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

    Richiesta HTTPS non elaborata

    Host: firebasehosting.googleapis.com

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

    • Se uno dei siti ha "type": "DEFAULT_SITE" , il tuo progetto ha già un sito Hosting predefinito. Salta il resto di questo passaggio e passa al passaggio successivo: crea una nuova versione per il tuo sito .

    • Se ottieni un array vuoto, non hai un sito di hosting predefinito. Completa il resto di questo passaggio.

  2. Decidi il SITE_ID per il tuo sito di hosting predefinito. Tieni presente quanto segue quando decidi questo SITE_ID :

    • Questo SITE_ID viene utilizzato per creare i tuoi sottodomini Firebase predefiniti:
      SITE_ID .web.app e SITE_ID .firebaseapp.com .

    • Un SITE_ID ha i seguenti requisiti:

      • Deve essere un'etichetta del nome host valida, ovvero non può contenere file . , _ , eccetera.
      • Deve contenere 30 caratteri o meno
      • Deve essere univoco a livello globale all'interno di Firebase

    Tieni presente che spesso consigliamo di utilizzare l'ID progetto come SITE_ID per il tuo sito di hosting predefinito. Scopri come trovare questo ID in Comprendere i progetti Firebase .

  3. Crea il tuo sito di hosting predefinito chiamando l'endpoint sites.create utilizzando SITE_ID desiderato come parametro siteId .

    Per esempio:

    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

    Richiesta HTTPS non elaborata

    Host: firebasehosting.googleapis.com

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

    Questa chiamata API a sites.create restituisce il seguente JSON:

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

Passaggio 3: crea una nuova versione per il tuo sito

La tua prima chiamata API è creare una nuova Version per il tuo sito. Più avanti in questa guida caricherai i file in questa versione, quindi la distribuirai sul tuo sito.

  1. Determina il SITE_ID per il sito in cui desideri eseguire la distribuzione.

  2. Chiama l'endpoint versioni.create utilizzando il tuo SITE_ID nella chiamata.

    (Facoltativo) Puoi anche passare un oggetto di configurazione Firebase Hosting nella chiamata, inclusa l'impostazione di un'intestazione che memorizza nella cache tutti i file per un periodo di tempo specificato.

    Per esempio:

    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

    Richiesta HTTPS non elaborata

    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"
      }
    }]
  }
}

Questa chiamata API a versions.create restituisce il seguente JSON:

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

Questa risposta contiene un identificatore univoco per la nuova versione, nel formato: sites/ SITE_ID /versions/ VERSION_ID . Avrai bisogno di questo identificatore univoco in tutta questa guida per fare riferimento a questa versione specifica.

Passaggio 4: specifica l'elenco dei file che desideri distribuire

Ora che hai il tuo nuovo identificatore di versione, devi indicare a Firebase Hosting quali file desideri distribuire eventualmente in questa nuova versione.

Tieni presente che l'Hosting ha un limite di dimensione massima di 2 GB per i singoli file.

Questa API richiede l'identificazione dei file tramite un hash SHA256. Pertanto, prima di poter effettuare la chiamata API, dovrai prima calcolare un hash per ogni file statico eseguendo il Gzip dei file e quindi prendendo l'hash SHA256 di ogni file appena compresso.

Continuando il nostro esempio, supponiamo che tu voglia distribuire tre file nella nuova versione: file1 , file2 e file3 .

  1. Comprimi i file:

    gzip file1 && gzip file2 && gzip file3

    Ora hai tre file compressi file1.gz , file2.gz e file3.gz .

  2. Ottieni l'hash SHA256 di ciascun file compresso:

    cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

    cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

    cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

    Ora hai i tre hash SHA256 dei tre file compressi.

  3. Invia questi tre hash in una richiesta API all'endpoint versions.populateFiles . Elenca ciascun hash in base al percorso desiderato per il file caricato (in questo esempio, /file1 , /file2 e /file3 ).

    Per esempio:

    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

    Richiesta HTTPS non elaborata

    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"
  }
}

Questa chiamata API a versions.populateFiles restituisce il seguente JSON:

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

Questa risposta include:

  • L' hash di ogni file che deve essere caricato. Ad esempio, in questo esempio file1 era già stato caricato in una versione precedente, quindi il suo hash non è incluso nell'elenco uploadRequiredHashes .

  • L' uploadUrl specifico della nuova versione.

Nel passaggio successivo per caricare i due nuovi file, avrai bisogno degli hash e uploadURL dalla versions.populateFiles .

Passaggio 5: carica i file richiesti

È necessario caricare individualmente ciascun file richiesto (quei file elencati in uploadRequiredHashes dalla versions.populateFiles nel passaggio precedente). Per questi caricamenti di file, avrai bisogno degli hash dei file e uploadUrl del passaggio precedente.

  1. Aggiungi una barra e l' hash del file a uploadUrl per creare un URL specifico del file nel formato: https://upload-firebasehosting.googleapis.com/upload/sites/ SITE_ID /versions/ VERSION_ID /files/ FILE_HASH .

  2. Carica tutti i file richiesti uno per uno (in questo esempio, solo file2.gz e file3.gz ) nell'URL specifico del file utilizzando una serie di richieste.

    Ad esempio, per caricare il file2.gz compresso2.gz:

    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

    Richiesta HTTPS non elaborata

    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

I caricamenti riusciti restituiscono una risposta HTTPS 200 OK .

Passaggio 6: aggiorna lo stato della versione su FINALIZED

Dopo aver caricato tutti i file elencati nella versions.populateFiles , puoi aggiornare lo stato della tua versione su FINALIZED .

Chiama l'endpoint versions.patch con il campo status nella richiesta API impostato su FINALIZED .

Per esempio:

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

Richiesta HTTPS non elaborata

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"}

Questa chiamata API a versions.patch restituisce il seguente JSON. Verifica che status sia stato aggiornato 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"
}

Passaggio 7: rilasciare la versione per la distribuzione

Ora che disponi di una versione finalizzata, rilasciala per la distribuzione. Per questo passaggio, devi creare una Release della tua versione che contenga la configurazione di hosting e tutti i file di contenuto per la tua nuova versione.

Chiama l'endpoint releases.create per creare la tua versione.

Per esempio:

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

Richiesta HTTPS non elaborata

Host: firebasehosting.googleapis.com

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

Questa chiamata API a releases.create restituisce il seguente 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 configurazione dell'hosting e tutti i file per la nuova versione dovrebbero ora essere distribuiti sul tuo sito e puoi accedere ai tuoi file utilizzando gli URL:

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

Questi file sono accessibili anche sugli URL associati al tuo dominio SITE_ID .firebaseapp.com .

Puoi anche vedere la tua nuova versione elencata nella dashboard di hosting della console Firebase.