使用 Hosting REST API 部署至您的網站

Firebase Hosting REST API 可讓您將程式輔助和可自訂的部署作業，部署至 Firebase 代管的網站。使用這個 REST API 部署新的或已更新的 Hosting 內容和設定。

除了使用 Firebase CLI 進行部署，您也可以使用 Firebase Hosting REST API，以程式輔助方式為網站建立新的資產 version、將檔案上傳至版本，然後將版本部署至網站。

舉例來說，您可以使用 Firebase Hosting REST API 執行以下操作：

  • 排定部署作業將 REST API 與 Cron 工作搭配使用，即可定期變更 Firebase 託管的內容 (例如部署特殊節日或事件相關的內容版本)。

  • 整合開發人員工具。您可以在工具中建立選項，只要按一下即可將網路應用程式專案部署至 Firebase Hosting (例如按一下 IDE 中的部署按鈕)。

  • 產生靜態內容時自動部署。當程序以程式輔助方式產生靜態內容 (例如使用者原創內容，例如 Wiki 或新聞文章) 時，您可以將產生的內容部署為靜態檔案，而非以動態方式提供。這樣一來，您就能節省昂貴的運算能力，並以更具擴充性的做法提供檔案。

本指南首先說明如何啟用、驗證及授權 API。然後本指南會逐步舉例說明如何建立 Firebase Hosting 版本，將必要檔案上傳至版本，最後再部署版本。

您也可以參閱完整的 Hosting REST API 參考說明文件，進一步瞭解這個 REST API。

事前準備：啟用 REST API

您必須在 Google API 控制台中啟用 Firebase Hosting REST API：

  1. 在 Google API 控制台中開啟 Firebase Hosting API 頁面。

  2. 系統顯示提示時，請選取 Firebase 專案。

  3. 點選 Firebase Hosting API 頁面中的「啟用」。

步驟 1：取得用於驗證和授權 API 要求的存取權杖

Firebase 專案支援 Google 服務帳戶，您可以透過這些帳戶從應用程式伺服器或信任環境呼叫 Firebase 伺服器 API。如果您在本機開發程式碼，或將應用程式部署到內部部署，則可以使用透過此服務帳戶取得的憑證，授權伺服器要求。

如要驗證服務帳戶，並授權該帳戶存取 Firebase 服務，您必須產生 JSON 格式的私密金鑰檔案。

如何產生服務帳戶的私密金鑰檔案：

  1. 在 Firebase 主控台中，依序開啟「設定」>「服務帳戶」。

  2. 按一下「產生新的私密金鑰」，然後點選「產生金鑰」確認。

  3. 妥善儲存含有金鑰的 JSON 檔案。

請使用 Firebase 憑證搭配偏好語言的 Google 驗證程式庫，擷取短期 OAuth 2.0 存取權杖：

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

在這個範例中，Google API 用戶端程式庫會使用 JSON Web Token 或 JWT 驗證要求。詳情請參閱「JSON 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();
}

存取權杖到期後，系統會自動呼叫權杖重新整理方法，以便擷取更新的存取權杖。

步驟 2：確認您的專案有預設的 Hosting 網站

首次部署至 Firebase Hosting 之前，您的 Firebase 專案必須具備預設的 Hosting SITE。

  1. 請呼叫 sites.list 端點，確認專案是否已設有預設 Hosting 網站。

    例如：

    cURL 指令

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

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

    原始 HTTPS 要求

    Host: firebasehosting.googleapis.com

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

    • 如果其中一個網站有 "type": "DEFAULT_SITE"，則您的專案已具有預設 Hosting 網站。請略過這個步驟的其餘部分，並繼續進行下一個步驟：為網站建立新版本。

    • 如果您收到空陣列，表示您沒有預設 Hosting 網站。完成這個步驟的其餘部分。

  2. 決定預設 Hosting 網站的 SITE_ID。決定這個 SITE_ID 時，請注意下列事項：

    • 這個 SITE_ID 用於建立預設的 Firebase 子網域：
      SITE_ID.web.app 和 SITE_ID.firebaseapp.com。

    • SITE_ID 必須符合下列條件：

      • 必須是有效的主機名稱標籤，不得含有 .、_ 等。
      • 不得超過 30 個字元
      • 在 Firebase 中不得重複

    請注意，一般會建議您使用專案 ID 做為預設 Hosting 網站的 SITE_ID。如要瞭解如何尋找這個 ID，請參閱「瞭解 Firebase 專案」。

  3. 使用所需 SITE_ID 做為 siteId 參數，呼叫 sites.create 端點，即可建立預設 Hosting 網站。

    例如：

    cURL 指令

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

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

    原始 HTTPS 要求

    Host: firebasehosting.googleapis.com

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

    對 sites.create 的這個 API 呼叫會傳回以下 JSON：

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

步驟 3：為網站建立新版本

第一個 API 呼叫是為網站建立新的 Version。在本指南的後續部分，您會將檔案上傳至這個版本，然後部署至網站。

  1. 決定要部署至哪個網站的 SITE_ID。

  2. 在呼叫中使用 SITE_ID 呼叫 versions.create 端點。

    (選用) 您也可以在呼叫中傳遞 Firebase Hosting 設定物件，包括設定可在指定時間內快取所有檔案的標頭。

    例如：

    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

    原始 HTTPS 要求

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

對 versions.create 的這個 API 呼叫會傳回以下 JSON：

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

這個回應包含新版本的專屬 ID，格式為 sites/SITE_ID/versions/VERSION_ID。您需要在本指南中使用這個專屬 ID 參照這個特定版本。

步驟 4：指定要部署的檔案清單

有了新版本 ID 之後，您需要告訴 Firebase Hosting 要在新版本中部署哪些檔案。

請注意，Hosting 的個別檔案大小上限為 2 GB。

這個 API 要求您使用 SHA256 雜湊來識別檔案。因此，在發出 API 呼叫之前，您必須先為各個靜態檔案計算雜湊值，先將每個靜態檔案壓縮成 ZIP 檔案，然後取得每個新壓縮檔案的 SHA256 雜湊。

接著，假設您要在新版本中部署三個檔案：file1、file2 和 file3。

  1. 使用 Gzip 壓縮檔案：

    gzip file1 && gzip file2 && gzip file3

    您現在有三個壓縮檔案 file1.gz、file2.gz 和 file3.gz。

  2. 取得每個壓縮檔案的 SHA256 雜湊：

    cat file1.gz | openssl dgst -sha256

66d61f86bb684d0e35f94461c1f9cf4f07a4bb3407bfbd80e518bd44368ff8f4

    cat file2.gz | openssl dgst -sha256

490423ebae5dcd6c2df695aea79f1f80555c62e535a2808c8115a6714863d083

    cat file3.gz | openssl dgst -sha256

59cae17473d7dd339fe714f4c6c514ab4470757a4fe616dfdb4d81400addf315

    現在，三個壓縮檔案的三個 SHA256 雜湊。

  3. 將這三個雜湊值傳送至 API 要求中的 versions.populateFiles 端點。按照上傳檔案的所需路徑列出每個雜湊 (本範例中為 /file1、/file2 和 /file3)。

    例如：

    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

    原始 HTTPS 要求

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

對 versions.populateFiles 的這個 API 呼叫會傳回以下 JSON：

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

這個回應包含：

  • 需要上傳的每個檔案的雜湊值。舉例來說，在這個範例中，file1 已在先前版本中上傳，因此其雜湊值不會列入 uploadRequiredHashes 清單。

  • 新版本專屬的 uploadUrl。

在上傳兩個新檔案的下一個步驟中，您需要 versions.populateFiles 回應中的雜湊和 uploadURL。

步驟 5：上傳必要檔案

您必須個別上傳每個必要檔案 (這些檔案會在上一節的 versions.populateFiles 回應中列於 uploadRequiredHashes)。針對這些檔案上傳作業，您需要先前步驟中的檔案雜湊和 uploadUrl。

  1. 將 正斜線和檔案的雜湊附加至 uploadUrl，以 https://upload-firebasehosting.googleapis.com/upload/sites/SITE_ID/versions/VERSION_ID/files/FILE_HASH 格式建立檔案專屬網址。

  2. 使用一系列要求，逐一上傳所有必要檔案 (在此範例中僅包含 file2.gz 和 file3.gz) 至檔案專屬網址。

    例如，如要上傳經壓縮的 file2.gz：

    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

    原始 HTTPS 要求

    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

上傳成功時，系統會傳回 200 OK HTTPS 回應。

步驟 6：將版本狀態更新為「已完成」

上傳 versions.populateFiles 回應中列出的所有檔案後，即可將版本的狀態更新為 FINALIZED。

使用設為 FINALIZED 的 API 要求中的 status 欄位，呼叫 versions.patch 端點。

例如：

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

原始 HTTPS 要求

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

對 versions.patch 的這個 API 呼叫會傳回以下 JSON。確認 status 已更新為 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"
}

步驟 7：發布版本以供部署

您現在已完成最終版本，請發布該版本以便部署。在這個步驟中，您需要建立版本的 Release，其中包含託管設定和新版本的所有內容檔案。

呼叫 releases.create 端點來建立版本。

例如：

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

原始 HTTPS 要求

Host: firebasehosting.googleapis.com

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

這個對 releases.create 的 API 呼叫會傳回下列 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"
}

新版本的代管設定和所有檔案現在應已部署至您的網站，您可以使用以下網址存取檔案：

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

也可在與 SITE_ID.firebaseapp.com 網域相關聯的網址上存取這些檔案。

您也可以在 Firebase 控制台的 Hosting 資訊主頁中查看新版本。