使用託管 REST API 部署到您的站點

Firebase 託管 REST API支援以程式設計方式和可自訂的方式部署到 Firebase 託管的網站。使用此 REST API 部署新的或更新的託管內容和配置。

作為使用Firebase CLI進行部署的替代方法,您可以使用 Firebase Hosting REST API 以程式設計方式為您的網站建立新version的資產,將檔案上傳到該版本,然後將該版本部署到您的網站。

例如,使用 Firebase 來託管 REST API,您可以:

  • 計劃部署。將 REST API 與 cron 作業結合使用,您可以定期變更 Firebase 所託管的內容(例如,部署特殊假期或與活動相關的內容版本)。

  • 與開發者工具整合。您可以在工具中建立選項,只需按一下(例如,按一下 IDE 中的部署按鈕)即可將 Web 應用專案部署到 Firebase Hosting。

  • 產生靜態內容時自動部署。當進程以程式設計方式產生靜態內容(例如,使用者產生的內容,例如 wiki 或新聞文章)時,您可以將產生的內容部署為靜態文件,而不是動態提供它們。這可以節省您昂貴的運算能力,並以更具可擴展性的方式為您的文件提供服務。

本指南首先介紹如何啟用、驗證和授權 API。然後,本指南將透過範例介紹建立 Firebase 託管版本、將所需檔案上傳到該版本,最後部署此版本。

您也可以在完整的託管 REST API 參考文件中了解有關此 REST API 的更多資訊。

開始之前:啟用 REST API

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

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

  2. 出現提示時,選擇您的 Firebase 專案。

  3. 按一下 Firebase 託管 API 頁面上的啟用

步驟 1:取得存取權杖以對 API 請求進行身份驗證和授權

Firebase 專案支援 Google服務帳戶,您可以使用它從應用程式伺服器或受信任的環境中呼叫 Firebase 伺服器 API。如果您在本機開發程式碼或在本機部署應用程序,則可以使用透過此服務帳戶取得的憑證來授權伺服器請求。

若要對服務帳戶進行驗證並授權其存取 Firebase 服務,您必須產生 JSON 格式的私鑰檔案。

要為您的服務帳戶產生私鑰檔案:

  1. 在 Firebase 控制台中,開啟設定 >服務帳戶

  2. 按一下「產生新私鑰」 ,然後按一下「產生金鑰」進行確認。

  3. 安全地儲存包含金鑰的 JSON 檔案。

將您的 Firebase 憑證與您的首選語言的Google Auth 庫一起使用,以檢索短期 OAuth 2.0 存取權令牌:

節點.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 令牌或 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

爪哇

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 Hosting 之前,您的 Firebase 專案必須有一個預設的Hosting SITE

  1. 透過呼叫sites.list端點檢查您的專案是否已有預設託管網站。

    例如:

    捲曲命令

    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.appSITE_ID .firebaseapp.com

    • SITE_ID有以下要求:

      • 必須是有效的主機名稱標籤,這意味著它不能包含._ , ETC。
      • 不得超過 30 個字符
      • 在 Firebase 中必須是全域唯一的

    請注意,我們通常建議使用您的專案 ID 作為預設託管網站的SITE_ID 。了解如何在了解 Firebase 專案中尋找此 ID。

  3. 透過使用所需的SITE_ID作為siteId參數呼叫sites.create端點來建立預設託管網站。

    例如:

    捲曲命令

    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 託管配置對象,包括設定在指定時間長度內快取所有文件的標頭。

    例如:

    捲曲命令

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

此回應包含新版本的唯一標識符,格式為: sites/ SITE_ID /versions/ VERSION_ID 。在本指南中,您將需要這個唯一識別碼來引用此特定版本。

步驟 4:指定要部署的檔案列表

現在您已經有了新的版本標識符,您需要告訴 Firebase Hosting 您希望最終在此新版本中部署哪些檔案。

請注意,託管單一檔案的最大大小限制為 2 GB。

此 API 要求您透過 SHA256 雜湊來識別檔案。因此,在進行 API 呼叫之前,您首先需要透過對檔案進行 Gzip 壓縮,然後取得每個新壓縮檔案的 SHA256 雜湊值來計算每個靜態檔案的雜湊值。

繼續我們的範例,假設您要在新版本中部署三個檔案: file1file2file3

  1. 對檔案進行 Gzip 壓縮:

    gzip file1 && gzip file2 && gzip file3

    您現在擁有三個壓縮檔案file1.gzfile2.gzfile3.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 -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以建立特定於檔案的 URL,格式如下: https://upload-firebasehosting.googleapis.com/upload/sites/ SITE_ID /versions/ VERSION_ID /files/ FILE_HASH

  2. 使用一系列請求將所有必要的文件(在本例中僅file2.gzfile3.gz )逐一上傳到文件特定的 URL。

    例如,上傳壓縮file2.gz

    捲曲命令

    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:將版本狀態更新為FINALIZED

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

呼叫versions.patch端點,並將 API 請求中的status欄位設定為FINALIZED

例如:

捲曲命令

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

新版本的託管配置和所有文件現在應該部署到您的站點,您可以使用以下 URL 存取您的文件:

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

也可以透過與您的SITE_ID .firebaseapp.com網域關聯的 URL 存取這些檔案。

您也可以在 Firebase 控制台的託管儀表板中查看列出的新版本。