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

Firebase Hosting REST API 可啟用 在 Firebase 託管網站上，透過程式輔助和可自訂的方式部署。 使用這個 REST API 部署全新或更新的託管內容，並 此外還會從 0 自動調整資源配置 您完全不必調整資源調度設定

除了使用 Firebase CLI 以外，您也可以 可以使用 Firebase Hosting REST API，透過程式輔助方式 建立新的 version 將檔案上傳至版本，再將檔案部署到 你的網站

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

  • 排定部署作業時間。使用 REST API 搭配 Cron 工作， 定期變更 Firebase 託管的內容 (例如 請部署與節慶或活動相關的特殊版本的內容)。

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

  • 在產生靜態內容時自動執行部署作業。程序 透過程式輔助方式產生靜態內容 (例如 例如維基或新聞報導) 可將生成的內容部署在 靜態檔案，而非動態提供檔案這樣就能節省費用 運算能力，並以擴充性更高的方式提供檔案。

本指南會先說明如何啟用、驗證及授權 API。 接著，本指南會逐步舉例說明建立 Firebase 託管服務的範例 更新必要檔案至版本，最後是部署 版本。

您也可以前往 完整託管 REST API 參考說明文件。

事前準備：啟用 REST API

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

  1. 開啟 Firebase Hosting API 頁面 也可以前往 Google API 控制台

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

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

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

Firebase 專案支援 Google 服務帳戶 可用來呼叫 Firebase 伺服器 API。如果您正在開發 或在地端部署環境部署應用程式 您就能使用取得 透過這個服務帳戶授權伺服器要求

驗證及授權服務帳戶 您必須先產生 JSON 格式的私密金鑰檔案，才能存取 Firebase 服務 格式。

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

  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 網路權杖。

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：確認專案有預設的託管網站

第一次部署至 Firebase 託管之前，你的 Firebase 專案必須 有預設值 代管 SITE。

  1. 呼叫 sites.list 端點

    例如：

    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"」，則代表您的專案 已有預設的託管網站。請�����這個���驟的���餘部分 繼續進行下一步： 為網站建立新版本。

    • 如果取得空白陣列，就表示沒有預設代管服務 網站。完成這個步驟的其餘步驟。

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

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

    • SITE_ID 必須符合下列條件：

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

    請注意，我們通常會建議您將專案 ID 做為專案的 SITE_ID 預設託管網站。瞭解如何在以下平台找出這個 ID： 瞭解 Firebase 專案。

  3. 呼叫 sites.create 方法是使用所需的 SITE_ID siteId 參數。

    例如：

    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 呼叫是建立新的 API 呼叫 Version。 在本指南的後續部分，您需將檔案上傳至這個版本，然後部署至 網站。

  1. 決定您要部署網站的 SITE_ID。

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

    (選用) 您也可以傳遞 Firebase 託管設定物件 ，包括設定標頭，藉此快取指定特定元件的所有檔案 時間。

    例如：

    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 託管 版本。

請注意，「託管」的儲存大小上限為 2 GB 個別檔案

您必須以 SHA256 雜湊識別檔案，才能使用這個 API。因此，您必須先 發出 API 呼叫，您必須先計算每個靜態檔案的雜湊值，方法是 先壓縮檔案，再對每個新壓縮的檔案取得 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：上傳必要檔案

您必須個別上傳每個必要檔案 (列出的檔案 位於 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 指令

    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。

呼叫 versions.patch 且 API 要求中的 status 欄位設為 FINALIZED。

例如：

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 控制台