發布擴充功能

本頁面說明如何在 Extensions Hub 中發布擴充功能。

事前準備

如要發布擴充功能，您必須先註冊為擴充功能發布者。

可驗證的來源

在 Extensions Hub 上發布的所有擴充功能，都必須有可公開驗證的來源。您不用將擴充功能原始碼直接上傳至 Extensions Hub，而是改為指定來源位置，Extension Hub 就會下載該位置並在其上建立。

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

透過可驗證的來源上傳影片有幾項好處：

  • 使用者可以針對即將安裝的擴充功能修訂版本檢查其原始碼。
  • 可以確定只上傳想要上傳的內容，而無法上傳，例如處理中的工作或遺留開發中的檔案。

建議的開發週期

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

這項功能提供開發週期，如下所示：

  1. 使用 Firebase Emulator 套件開發並快速疊代擴充功能。

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

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

  3. 將預先發布版上傳至 Extensions Hub (請參閱下方說明)。發布安裝連結以進行更廣泛的測試，並視需要上傳更多的預先發布版本來疊代。

  4. 將最終的穩定版本上傳至 Extensions Hub (請見下方說明)，然後送交審查。擴充功能通過審查後就會發布到擴充功能中心。

  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. 按一下「Deprecate version」。

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 中移除。上傳已淘汰的擴充功能的新版本後，系統會自動進行審查，等接受接受，再將該擴充功能再次發布到 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 函式資源中的 sourceDirectory)。

    注意事項：

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

    • 安裝依附元件時將不會執行安裝後指令碼。如果您的原始碼建構必須使用安裝後指令碼，請在上傳之前重構。

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

系統只會將擴充功能的根目錄儲存在即將共用的最終擴充功能套件中。

如果您在上傳擴充功能時遇到建構錯誤，請在本機的新目錄中複製上述建構步驟，直到沒有任何錯誤，然後再重新上傳。