Déployer sur votre site à l'aide de l'API REST Hosting

L'API REST Firebase Hosting permet des déploiements programmatiques et personnalisables sur vos sites hébergés par Firebase. Utilisez cette API REST pour déployer du contenu et une configuration Hosting nouveaux ou mis à jour.

Au lieu d'utiliser la CLI Firebase pour les déploiements, vous pouvez utiliser l'API REST Firebase Hosting pour créer de manière programmatique une version d'assets pour votre site, importer des fichiers dans la version, puis déployer la version sur votre site.

Par exemple, avec l'API REST Firebase Hosting, vous pouvez:

  • Planifier des déploiements En utilisant l'API REST avec une tâche cron, vous pouvez modifier le contenu hébergé par Firebase de manière régulière (par exemple, pour déployer une version spéciale de votre contenu pour les fêtes ou les événements).

  • Intégrez les outils pour les développeurs. Vous pouvez créer une option dans votre outil pour déployer vos projets d'application Web sur Firebase Hosting en un seul clic (par exemple, en cliquant sur un bouton de déploiement dans un IDE).

  • Automatisez les déploiements lorsque du contenu statique est généré. Lorsqu'un processus génère du contenu statique de manière programmatique (par exemple, du contenu généré par l'utilisateur tel qu'un wiki ou un article d'actualité), vous pouvez déployer le contenu généré en tant que fichiers statiques plutôt que de le diffuser de manière dynamique. Vous économisez ainsi une puissance de calcul coûteuse et diffusez vos fichiers de manière plus évolutive.

Ce guide explique d'abord comment activer, authentifier et autoriser l'API. Ce guide présente ensuite un exemple de création d'une version Firebase Hosting, d'importation des fichiers requis dans la version, puis de déploiement de la version.

Pour en savoir plus sur cette API REST, consultez la documentation de référence complète de l'API REST Hosting.

Avant de commencer: Activer l'API REST

Vous devez activer l'API REST Firebase Hosting dans la console Google APIs:

  1. Ouvrez la page API Firebase Hosting dans la console Google APIs.

  2. Lorsque vous y êtes invité, sélectionnez votre projet Firebase.

  3. Cliquez sur Activer sur la page de l'API Firebase Hosting.

Étape 1: Obtenez un jeton d'accès pour authentifier et autoriser les requêtes API

Les projets Firebase sont compatibles avec les comptes de service Google, que vous pouvez utiliser pour appeler les API de serveur Firebase à partir de votre serveur d'application ou de votre environnement approuvé. Si vous développez du code localement ou déployez votre application sur site, vous pouvez utiliser les identifiants obtenus via ce compte de service pour autoriser les requêtes du serveur.

Pour authentifier un compte de service et l'autoriser à accéder aux services Firebase, vous devez générer un fichier de clé privée au format JSON.

Pour générer un fichier de clé privée pour votre compte de service:

  1. Dans la console Firebase, ouvrez Settings > Service Accounts (Paramètres > Comptes de service).

  2. Cliquez sur Générer une nouvelle clé privée, puis confirmez en cliquant sur Générer une clé.

  3. Stockez de manière sécurisée le fichier JSON contenant la clé.

Utilisez vos identifiants Firebase avec la bibliothèque Google Auth dans la langue de votre choix pour récupérer un jeton d'accès OAuth 2.0 de courte durée:

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

Dans cet exemple, la bibliothèque cliente de l'API Google authentifie la requête avec un jeton Web JSON (JWT). Pour en savoir plus, consultez la section Jetons 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();
}

Une fois votre jeton d'accès expiré, la méthode d'actualisation du jeton est appelée automatiquement pour récupérer un jeton d'accès mis à jour.

Étape 2: Assurez-vous que votre projet dispose d'un site Hosting par défaut

Avant votre premier déploiement sur Firebase Hosting, votre projet Firebase doit disposer d'un Hosting SITE par défaut.

  1. Vérifiez si votre projet dispose déjà d'un site Hosting par défaut en appelant le point de terminaison sites.list.

    Exemple :

    Commande cURL

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

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

    Requête HTTPS brute

    Host: firebasehosting.googleapis.com

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

    • Si l'un des sites contient "type": "DEFAULT_SITE", votre projet dispose déjà d'un site Hosting par défaut. Passez la fin de cette étape et passez à l'étape suivante : Créer une version de votre site.

    • Si vous obtenez un tableau vide, vous n'avez pas de site Hosting par défaut. Terminez cette étape.

  2. Déterminez le SITE_ID pour votre site Hosting par défaut. Tenez compte des points suivants lorsque vous choisissez cette SITE_ID:

    • Ce SITE_ID permet de créer vos sous-domaines Firebase par défaut:
      SITE_ID.web.app et SITE_ID.firebaseapp.com.

    • Un SITE_ID présente les exigences suivantes:

      • Doit être un libellé de nom d'hôte valide, ce qui signifie qu'il ne doit pas contenir ., _, etc.
      • 30 caractères maximum
      • Doit être unique dans Firebase

    Notez que nous vous recommandons souvent d'utiliser l'ID de votre projet comme SITE_ID pour votre site Hosting par défaut. Découvrez comment trouver cet ID dans la section Comprendre les projets Firebase.

  3. Créez votre site Hosting par défaut en appelant le point de terminaison sites.create à l'aide de l'SITE_ID souhaité comme paramètre siteId.

    Exemple :

    Commande cURL

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

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

    Requête HTTPS brute

    Host: firebasehosting.googleapis.com

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

    Cet appel d'API à sites.create renvoie le code JSON suivant:

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

Étape 3: Créez une version de votre site

Votre premier appel d'API consiste à créer un Version pour votre site. Plus loin dans ce guide, vous importerez des fichiers dans cette version, puis la déploierez sur votre site.

  1. Déterminez le SITE_ID du site sur lequel vous souhaitez effectuer le déploiement.

  2. Appelez le point de terminaison versions.create à l'aide de votre SITE_ID dans l'appel.

    (Facultatif) Vous pouvez également transmettre un objet de configuration Firebase Hosting dans l'appel, y compris en définissant un en-tête qui met en cache tous les fichiers pendant une durée spécifiée.

    Exemple :

    Commande 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

    Requête HTTPS brute

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

Cet appel d'API à versions.create renvoie le code JSON suivant:

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

Cette réponse contient un identifiant unique pour la nouvelle version, au format : sites/SITE_ID/versions/VERSION_ID. Vous aurez besoin de cet identifiant unique tout au long de ce guide pour faire référence à cette version spécifique.

Étape 4: Spécifiez la liste des fichiers que vous souhaitez déployer

Maintenant que vous disposez de l'identifiant de la nouvelle version, vous devez indiquer à Firebase Hosting les fichiers que vous souhaitez éventuellement déployer dans cette nouvelle version.

Notez que la taille maximale de Hosting est limitée à 2 Go pour les fichiers individuels.

Cette API nécessite que vous identifiiez les fichiers par un hachage SHA256. Par conséquent, avant de pouvoir effectuer l'appel d'API, vous devez d'abord calculer un hachage pour chaque fichier statique en le compressant avec Gzip, puis en prenant le hachage SHA256 de chaque fichier nouvellement compressé.

Poursuivons notre exemple. Supposons que vous souhaitiez déployer trois fichiers dans la nouvelle version: file1, file2 et file3.

  1. Gzippez les fichiers:

    gzip file1 && gzip file2 && gzip file3

    Vous disposez désormais de trois fichiers compressés : file1.gz, file2.gz et file3.gz.

  2. Obtenez le hachage SHA256 de chaque fichier compressé:

    cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

    cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

    cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

    Vous disposez maintenant des trois hachages SHA256 des trois fichiers compressés.

  3. Envoyez ces trois hachages dans une requête API au point de terminaison versions.populateFiles. Indiquez chaque hachage en fonction du chemin d'accès souhaité pour le fichier importé (dans cet exemple, /file1, /file2 et /file3).

    Exemple :

    Commande 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

    Requête HTTPS brute

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

Cet appel d'API à versions.populateFiles renvoie le code JSON suivant:

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

Cette réponse inclut les éléments suivants :

  • Le hachage de chaque fichier à importer. Par exemple, dans cet exemple, file1 avait déjà été importé dans une version précédente. Son hachage n'est donc pas inclus dans la liste uploadRequiredHashes.

  • uploadUrl spécifique à la nouvelle version.

À l'étape suivante, pour mettre en ligne les deux nouveaux fichiers, vous aurez besoin des hachages et de l'uploadURL de la réponse versions.populateFiles.

Étape 5: Importez les fichiers requis

Vous devez importer individuellement chaque fichier requis (ceux qui sont listés dans uploadRequiredHashes à partir de la réponse versions.populateFiles de l'étape précédente). Pour ces importations de fichiers, vous aurez besoin des hachages de fichiers et de l'uploadUrl de l'étape précédente.

  1. Ajoutez un slash et le hachage du fichier à uploadUrl pour créer une URL spécifique au fichier au format : https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH.

  2. Importez tous les fichiers requis un par un (dans cet exemple, uniquement file2.gz et file3.gz) sur l'URL spécifique au fichier à l'aide d'une série de requêtes.

    Par exemple, pour importer le file2.gz compressé:

    Commande 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

    Requête HTTPS brute

    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

Les importations réussies renvoient une réponse HTTPS 200 OK.

Étape 6: Définissez l'état de la version sur "FINALISÉ".

Une fois que vous avez importé tous les fichiers listés dans la réponse versions.populateFiles, vous pouvez définir l'état de votre version sur FINALIZED.

Appelez le point de terminaison versions.patch avec le champ status de votre requête API défini sur FINALIZED.

Exemple :

Commande 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

Requête HTTPS brute

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

Cet appel d'API à versions.patch renvoie le code JSON suivant. Vérifiez que status a été remplacé par 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"
}

Étape 7: Publier la version pour le déploiement

Maintenant que vous avez une version finalisée, publiez-la pour le déploiement. Pour cette étape, vous devez créer un Release de votre version contenant la configuration d'hébergement et tous les fichiers de contenu de votre nouvelle version.

Appelez le point de terminaison releases.create pour créer votre version.

Exemple :

Commande 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

Requête HTTPS brute

Host: firebasehosting.googleapis.com

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

Cet appel d'API à releases.create renvoie le code JSON suivant:

{
  "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 configuration d'hébergement et tous les fichiers de la nouvelle version devraient maintenant être déployés sur votre site. Vous pouvez accéder à vos fichiers à l'aide des URL suivantes:

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

Ces fichiers sont également accessibles sur les URL associées à votre domaine SITE_ID.firebaseapp.com.

Vous pouvez également voir votre nouvelle version listée dans le tableau de bord Hosting de la console Firebase.