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

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

Au lieu d'utiliser la Firebase CLI 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 effectuer les opérations suivantes :

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

• Intégrer des 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).

• Automatiser 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. Cela vous permet d'économiser de la puissance de calcul coûteuse et de diffuser vos fichiers de manière plus évolutive.

Ce guide explique d'abord comment activer, authentifier et autoriser l'API. Il présente ensuite un exemple de création d'une Firebase Hosting version, 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 Firebase Hosting page de l'API dans la console Google APIs.

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

   Remarque : Chaque projet Firebase possède un projet correspondant dans la console Google APIs console.

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

Étape 1 : Obtenir 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 serveur Firebase à partir de votre serveur d'application ou de votre environnement de confiance. Si vous développez du code localement ou déployez votre application sur site, vous pouvez utiliser les identifiants obtenus à l'aide de ce compte de service pour autoriser les requêtes serveur.

Vous pouvez afficher tous les comptes de service de votre projet Firebase dans les paramètres > Comptes de service tab.

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, accédez aux Paramètres > Comptes de service, sous l'onglet.

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

3. Stockez le fichier JSON contenant la clé en lieu sûr.

Utilisez vos identifiants Firebase avec la bibliothèque Google Auth pour le langage de votre choix afin de récupérer un jeton d'accès OAuth 2.0 éphémère :

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 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.

Remarque : Bien que l'utilisation d'un compte de service soit appropriée pour les tâches automatisées dans les environnements serveur, il existe d'autres moyens d'obtenir une autorisation pour utiliser l' Firebase Hosting API REST. Par exemple, les membres du projet peuvent utiliser l'API s'ils (1) sont affectés au rôle d'administrateur ou d'éditeur pour un projet et (2) fournissent des jetons d'accès avec le champ d'application approprié. Consultez les autres scénarios pour différents flux OAuth qui vous permettront d'obtenir une autorisation pour utiliser l' Firebase Hosting API REST.

Étape 2 : Vérifier 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.

Remarque : Vous pouvez effectuer un déploiement sur un site d'hébergement non par défaut, mais votre projet doit comporter au moins un site par défaut Hosting avant de pouvoir effectuer un déploiement sur Firebase Hosting du tout.

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

   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 comporte "type": "DEFAULT_SITE", votre projet dispose déjà d'un site Hosting par défaut. Ignorez le reste de cette étape, et passez à l'étape suivante : Créer une version pour votre site.

   • Si vous obtenez un tableau vide, vous ne disposez pas d'un site Hosting par défaut. Suivez le reste de cette étape.

2. Décidez du SITE_ID pour votre site Hosting par défaut. Tenez compte des points suivants lorsque vous choisissez ce SITE_ID :

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

   • Un SITE_ID doit répondre aux exigences suivantes :

     • Doit être un libellé de nom d'hôte valide, ce qui signifie qu'il ne peut pas contenir de caractères tels que ., _, etc.
     • Doit comporter 30 caractères ou moins
     • Doit être globalement unique dans Firebase

   Notez que nous recommandons souvent d'utiliser l'ID du projet comme le SITE_ID pour votre site Hosting par défaut. Pour savoir comment trouver cet ID, consultez Comprendre les projets Firebase.

3. Créez votre site Hosting par défaut en appelant le sites.create point de terminaison à l'aide du 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 JSON suivant :

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

   Si vous décidez d'utiliser l'ID de votre projet comme SITE_ID, notez les points suivants :

   Dans de rares cas, l'ID de votre projet a déjà été utilisé par un autre projet pour créer un site Hosting. Dans ce cas, l'appel à sites.create renvoie un message d'erreur 400 indiquant que le fourni SITE_ID est reserved by another project. Pour résoudre cette erreur, essayez d'appeler sites.create à nouveau en utilisant la chaîne suggérée dans le message d'erreur ou une autre chaîne jusqu'à ce que l'appel réussisse.

Étape 3 : Créer une version pour votre site

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

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

   Remarque : Pour votre site Hosting par défaut, le SITE_ID correspond à l'ID de votre projet Firebase (qui est utilisé pour créer vos sous-domaines Firebase SITE_ID.web.app et SITE_ID.firebaseapp.com).
   Si vous avez créé plusieurs sites dans votre projet Firebase, assurez-vous d'utiliser le SITE_ID du site sur lequel vous souhaitez effectuer le déploiement.

2. Appelez le versions.create point de terminaison en utilisant votre SITE_ID dans l'appel.

   (Facultatif) Vous pouvez également transmettre un Firebase Hosting objet de configuration 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 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écifier la liste des fichiers que vous souhaitez déployer

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

Notez que la taille maximale des fichiers individuels est de 2 Go pour Hosting.

Cette API vous oblige à identifier 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 compressant les fichiers au format Gzip, puis en prenant le hachage SHA256 de chaque fichier nouvellement compressé.

Important: Dans cet appel, vous devez lister tous les fichiers que vous souhaitez inclure dans la nouvelle version, y compris les nouveaux fichiers et tous les fichiers existants des versions précédentes (modifiés et non modifiés).

Vous pouvez envoyer un maximum de 1 000 hachages de fichiers dans chaque requête API. Par conséquent, pour lister tous les fichiers de la version, vous pouvez appeler ce point de terminaison plusieurs fois. Les fichiers de chaque appel seront ajoutés à la version.

Pour poursuivre notre exemple, supposons que vous souhaitez déployer trois fichiers dans la nouvelle version : file1, file2 et file3.

1. Compressez les fichiers au format Gzip :

   gzip file1 && gzip file2 && gzip file3

   Vous disposez maintenant 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 versions.populateFiles point de terminaison. Répertoriez chaque hachage par le 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 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.

  Remarque : Certains fichiers de votre nouvelle version n'ont pas besoin d'être importés, par exemple, si le fichier se trouvait déjà dans une version précédente et n'a pas été modifié pour la nouvelle version.

• L'uploadUrl, qui est spécifique à la nouvelle version.

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

Étape 5 : Importer 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 une barre oblique et le hachage du fichier à l'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) vers l'URL spécifique au fichier à l'aide d'une série de requêtes.

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

   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éfinir l'état de la version sur FINALIZED

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 versions.patch point de terminaison 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 JSON suivant. Vérifiez que status a été mis à jour sur 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": "[e-mail]"
  },
  "fileCount": "5",
  "versionBytes": "114951"
}

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

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

Appelez le releases.create point de terminaison 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 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 doivent maintenant être déployés sur votre site, et 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 SITE_ID.firebaseapp.com domaine.

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