發布擴充功能

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

事前準備

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

可驗證的來源

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

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

從可驗證來源上傳有許多好處:

  • 使用者可以檢查要安裝的擴充功能特定修訂版本的原始碼。
  • 您可以確保只上傳要上傳的檔案,而非上傳未完成的工作或開發過程中遺留的孤立檔案。

建議的開發週期

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

這項功能可實現以下開發週期:

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

  2. 如要在實際專案中測試擴充功能,請從本機來源安裝擴充功能:

    firebase ext:install /path/to/extension
    firebase deploy --only extensions
    
  3. 將預先發布版上傳至 Extensions Hub (請參閱下方說明)。發布安裝連結以進行更廣泛的測試,並視需要上傳更多預先發布版,以便進行迭代。

  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 修訂版本參照。這可以是修訂版本 SHA、標記或分支版本名稱。

    • 您要上傳的版本的發布階段。

      alphabetarc (候選版) 階段用於上傳測試人員可安裝的預發布版本。請使用其中一個階段來初次上傳新的擴充功能。

      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. 如果您先前已發布擴充功能的版本,上傳新的穩定版本後,系統會自動將擴充功能送交審查。

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

提交後,審查作業可能需要幾天時間。如果獲准,擴充功能就會發布到 Extensions Hub。如果遭到拒絕,系統會傳送訊息說明原因,您可以解決所回報的問題,然後重新送交審查。

為加快審查作業並提高首次通過的機率,請在提交前仔細檢查下列事項:

  • 您已徹底測試擴充功能和安裝程序。
  • 您的文件完整且正確,且在 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 中,也無法安裝。如果使用者的專案安裝的是已淘汰的版本,系統會顯示訊息,鼓勵他們升級;他們仍可使用及重新設定擴充功能。

如果擴充功能的所有版本都已淘汰,系統會將該擴充功能視為已淘汰,並將其從擴充功能中心下架。上傳淘汰擴充功能的新版本後,系統會自動啟動審查程序,並在通過審查後,再次在 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,藉此建構程式碼。

在要分享的最終擴充功能套件中,系統只會儲存擴充功能的根目錄。

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