使用 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 託管內容 (例如部署節慶或活動相關的特殊版本內容)。

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

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

本指南首先說明如何啟用、驗證及授權 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.jsPythonJava 
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 網頁符記。

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
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 指令原始 HTTPS 要求 
    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

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

    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 做為預設SITE_IDHosting網站的 SITE_ID。如要瞭解如何找出這個 ID，請參閱「瞭解 Firebase 專案」一文。

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

    例如：

    cURL 指令原始 HTTPS 要求 
    curl -H "Content-Type: application/json" \
       -H "Authorization: Bearer ACCESS_TOKEN" \

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

    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 指令原始 HTTPS 要求 
    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

    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 雜湊識別檔案。因此，您必須先計算每個靜態檔案的雜湊值，方法是先將檔案 Gzip 壓縮，然後取得每個新壓縮檔案的 SHA256 雜湊值，才能進行 API 呼叫。

繼續以我們的範例來說明，假設您要在新版本中部署三個檔案：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 指令原始 HTTPS 要求 
    $ 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

    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：上傳必要檔案

您必須個別上傳每個必要檔案 (前一個步驟中 uploadRequiredHashes 的 versions.populateFiles 回應中列出的檔案)。上傳這些檔案時，您需要檔案雜湊和上一個步驟中的 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 指令原始 HTTPS 要求 
    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

    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。

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

例如：

cURL 指令原始 HTTPS 要求 
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

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 指令原始 HTTPS 要求 
curl -H "Authorization: Bearer ACCESS_TOKEN" \
       -X POST
https://firebasehosting.googleapis.com/v1beta1/sites/SITE_ID/releases?versionName=sites/SITE_ID/versions/VERSION_ID

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資訊主頁中，查看新版本。