發布擴充功能

本頁說明如何將擴充功能發布到 Extensions Hub。

事前準備

如要發布擴充功能，請先註冊為擴充功能發布者。

可驗證的來源

發布到擴充功能中心的擴充功能，都必須有可公開驗證的來源。您不必直接將擴充功能原始碼上傳至擴充功能中心，而是指定來源位置，擴充功能中心就會從該處下載並建構擴充功能。

目前，這表示您必須在公開的 GitHub 存放區中提供擴充功能原始碼。

從可驗證的來源上傳有幾項優點：

  • 使用者可以檢查要安裝的擴充功能特定修訂版本原始碼。
  • 您可以確保只上傳您想上傳的內容，例如未完成的工作，或是開發過程中留下的雜項檔案。

建議的開發週期

Firebase Extensions 開發工具支援上傳擴充功能的預先發布版，方便您在最終發布擴充功能的環境中，測試擴充功能和擴充功能安裝程序。

這項功能可實現下列開發週期：

  1. 使用 Firebase 模擬器套件開發及快速疊代擴充功能。

  2. 從本機來源安裝擴充功能，在實際專案中測試：

    firebase ext:install /path/to/extension
firebase deploy --only extensions

  3. 將預先發布版上傳至擴充功能中心 (請參閱下文)。發布安裝連結以進行更廣泛的測試，並視需要上傳更多預先發布版本，反覆測試。

  4. 將最終穩定版本上傳至擴充功能中心 (請參閱下文)，然後送交審查。擴充功能通過審查後，就會發布到擴充功能中心。

  5. 在 extension.yaml 中依累加原則設定版本號碼，然後為下一個擴充功能版本重複這個週期。

上傳新的擴充功能

首次上傳擴充功能：

  1. 選用：將程式碼提交至公開 GitHub 存放區。

  2. 執行 Firebase CLI 的 ext:dev:upload 指令：

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    本機原始碼

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

    在指令叫用中，您會指定下列項目：

    • 您註冊的發布商 ID。

    • 用於識別擴充功能的 ID 字串。請使用下列格式為擴充功能命名：firebase-product-description-of-tasks-performed。例如：firestore-bigquery-export

    指令會提示您提供額外資訊：

    • 從 GitHub 上傳：

      • GitHub 中擴充功能存放區的網址。請注意，只要每個擴充功能都有專屬根目錄，存放區就能包含多個擴充功能。

        首次上傳新擴充功能時，系統會將存放區註冊為擴充功能的標準來源。

      • 存放區中含有擴充功能的目錄。

      • 您要用來建構擴充功能版本來源的修訂版本 Git 參照。可以是修訂版本雜湊、標記或分支名稱。

    • 上傳版本的發布階段。

      alpha、beta 和 rc (候選版本) 階段適用於上傳預先發布版本，供測試人員安裝。請使用其中一個階段，初步上傳新的擴充功能。

      stable 階段用於發布至擴充功能中心的公開版本。上傳 stable版本後，系統會自動啟動審查程序，通過審查後就會發布擴充功能。

    請注意，您並未指定版本號碼，這個值來自 extension.yaml 檔案。上傳預先發布版擴充功能時，系統會在版本號碼後方附加階段和上傳編號。舉例來說，如果 extension.yaml 指定版本為 1.0.1，而您上傳候選版本，就會產生 1.0.1-rc.0 版本；上傳相同版本的另一個候選版本時，系統會自動遞增計數，產生 1.0.1-rc.1 版本，依此類推。

上傳擴充功能的預先發布版後，即可與他人分享，使用者可以透過下列兩種方式安裝擴充功能：

  • 透過控制台：使用者可以點按下列格式的連結來安裝擴充功能：

    https://console.firebase.google.com/project/_/extensions/install?ref=your_publisher_id/your_extension_id@version

    你可以將直接連結分享給測試人員。

  • 使用 CLI：使用者可以將擴充功能 ID 字串傳遞至 ext:install 指令，藉此安裝擴充功能：

    firebase ext:install your_publisher_id/your_extension_id@version \
    --project=destination_project_id

上傳更新版本

上傳擴充功能的第一個版本後，您可以上傳更新版本來修正問題、新增功能或推進發布階段。上傳新版本後，Firebase 控制台會提示已安裝舊版擴充功能的使用者升級。

如要上傳更新內容，請按照下列步驟操作：

  1. 選用：將程式碼提交至公開的 Git 存放區。

  2. 執行 Firebase CLI 的 ext:dev:upload 指令：

    GitHub

    firebase ext:dev:upload your_publisher_id/your_extension_id

    這次系統不會提示您指定 GitHub 存放區或擴充功能根目錄，因為這些項目已為擴充功能設定完成。如果您已重構存放區結構或遷移至新存放區，可以使用 --root 和 --repo 指令引數變更存放區。

    本機原始碼

    cd /path/to/extension
firebase ext:dev:upload your_publisher_id/your_extension_id --local

提交擴充功能以供發布

準備好公開發布擴充功能時，請按照下列步驟操作：

  1. 將程式碼提交至公開的 Git 存放區。(公開發布時必須提供)。

  2. 執行 Firebase CLI 的 ext:dev:upload 指令，並指定 stable 做為發布階段：

    firebase ext:dev:upload your_publisher_id/your_extension_id

  3. 如果您先前已發布擴充功能版本，上傳新的穩定版時，系統會自動將擴充功能送交審查。

    如果您已上傳擴充功能的第一個穩定版本，請在發布商資訊主頁中找到該擴充功能，然後按一下「發布至擴充功能中心」。

提交後，審查作業會在幾天內完成。如果通過審查，擴充功能就會發布到擴充功能中心。如果遭拒，你會收到說明原因的訊息，接著可以解決回報的問題，然後重新送審。

為加快審查速度並提高首次通過審查的機率，請在提交前仔細檢查下列事項：

  • 您已徹底測試擴充功能和安裝程序。
  • 文件完整正確，且在 Firebase 控制台中顯示正常。
  • 發布商名稱和品牌資訊清楚且正確地識別您為發布商。
  • 擴充功能的名稱、說明和圖示清楚且準確地呈現擴充功能的用途。
  • 你已套用實用且準確的標記。
  • 您已在extension.yaml所有使用的 Google 和非 Google API，以及擴充功能發出的所有事件類型中聲明。
  • 您只要求擴充功能運作所需的角色存取權，並已向使用者清楚說明需要這類存取權的原因。
  • 您的來源檔案已明確依據 Apache-2.0 的條款授權。

管理已上傳及發布的擴充功能

列出上傳的擴充功能

如要列出您透過發布商 ID 上傳的擴充功能，請執行下列任一操作：

發布商資訊主頁

你可以在發布者資訊主頁查看這些資料。

Firebase CLI

執行 ext:dev:list 指令：

firebase ext:dev:list your_publisher_id

查看上傳擴充功能的用量

如要查看以發布商 ID 上傳的擴充功能用量，請執行下列任一操作：

發布商資訊主頁

發布商資訊主頁會顯示所有擴充功能的累計用量指標，以及各項擴充功能的個別指標。

Firebase CLI

執行 ext:dev:usage 指令：

firebase ext:dev:usage your_publisher_id

淘汰擴充功能版本

有時您可能會想淘汰舊版擴充功能。舉例來說，如果您發布的新版本修正了重大錯誤，或是更新了含有重要安全性更新的依附元件，請務必禁止新使用者安裝舊版，並鼓勵現有使用者升級。

如要淘汰擴充功能版本，請執行下列任一操作：

發布商資訊主頁

  1. 在發布商資訊主頁中，按一下擴充功能，開啟詳細資料檢視畫面。
  2. 選取要淘汰的版本。
  3. 按一下「淘汰版本」。

Firebase CLI

執行 ext:dev:deprecate 指令：

firebase ext:dev:deprecate your_publisher_id/your_extension_id versions \
    [--message "deprecation_message"]

您可以指定單一版本或版本範圍。範例：

  • 1.0.2
  • 1.1.0-1.1.7
  • <1.2.0
  • 1.1.*

擴充功能中心不會列出已淘汰的版本，且無法安裝。如果專案安裝的版本已淘汰，使用者會看到升級提示訊息，但仍可繼續使用及重新設定擴充功能。

如果擴充功能的每個版本都已淘汰，該擴充功能就會視為已淘汰，並從擴充功能中心下架。上傳已淘汰擴充功能的新版本後，系統會自動啟動審查程序，並在通過審查後再次發布至 Extensions Hub。

如要撤銷淘汰，請使用發布者資訊主頁，或執行 Firebase CLI 的 ext:dev:undeprecate 指令：

firebase ext:dev:undeprecate your_publisher_id/your_extension_id versions

附錄：排解建構錯誤

上傳擴充功能時，後端會先使用下列程序建構原始碼：

  1. 複製 GitHub 存放區，並簽出指定的來源參照。

  2. 在 extension.yaml 中指定的每個函式來源目錄中執行 npm clean-install，安裝 NPM 依附元件 (請參閱「Cloud Functions 資源」中的 sourceDirectory)。

    注意事項：

    • 每個 package.json 檔案都必須有對應的 package-lock.json 檔案。詳情請參閱 npm-ci。

    • 安裝依附元件時，系統不會執行安裝後指令碼。 如果原始碼建構作業依賴安裝後指令碼，請先重構原始碼，再上傳。

  3. 在 extension.yaml 中指定的每個函式來源目錄中執行 npm run build，建構程式碼。

最終分享的擴充功能套件只會儲存擴充功能的根目錄。

如果在上傳擴充功能時發生建構錯誤，請在新的目錄中，於本機重複上述建構步驟，直到沒有錯誤為止，然後再試一次上傳。