管理 Go 模組

本頁說明如何管理儲存在 Artifact Registry 中的封裝 Go 模組。

事前準備

1. 如果目標存放區不存在，請建立新的存放區。選擇 Go 做為存放區格式。
2. 確認您具備存放區的必要權限。
3. (選用) 設定 gcloud 指令的預設值。
4. 安裝 Go 1.15 以上版本。

5. 安裝 package-go-module gcloud CLI 外掛程式：

   gcloud components install package-go-module

6. 設定 Go，以便向 Artifact Registry 進行驗證。

必要的角色

如要取得管理模組所需的權限，請要求管理員在存放區中授予下列 IAM 角色：

• 查看模組： Artifact Registry 讀取者 (roles/artifactregistry.reader)
• 下載或安裝模組： Artifact Registry 讀取者 (roles/artifactregistry.reader)
• 將模組新增至存放區： Artifact Registry Writer (roles/artifactregistry.writer)
• 刪除模組： Artifact Registry 存放區管理員 (roles/artifactregistry.repoAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

上傳模組

存放區模式：標準

如要將模組封裝並上傳至存放區，請執行下列指令：

  gcloud artifacts go upload --project=PROJECT \
      --repository=REPOSITORY \
      --location=LOCATION \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

更改下列內容：

• 將 PROJECT 替換為您的 Google Cloud 專案 ID。
• REPOSITORY 替換為儲存套件的存放區名稱。
• LOCATION，其中包含存放區的區域或多區域位置。
• MODULE_PATH，並提供模組路徑。例如：example.com/foo 詳情請參閱 Go 模組參考資料。
• VERSION，其中 語意化版本的格式為 vX.Y.Z，X 是主版本，Y 是次要版本，Z 則是修補程式版本。
• SOURCE_LOCATION，並將其替換為 Go 模組根目錄的路徑。如果省略 --source 旗標，預設為目前目錄。

模組會上傳至 Artifact Registry。

如要進一步瞭解如何建立 Go 模組，請參閱這篇教學課程。

上傳新版模組

存放區模式：標準

如要將新版模組上傳至已設定預設值的預設專案、存放區和位置，請執行下列指令並提供新版本號碼：

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION \
      --source=SOURCE_LOCATION

將 VERSION 替換為更新後模組的版本。舉例來說，如要上傳路徑為 example.com/foo 的模組版本 0.1.1，請執行下列指令：

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v0.1.1 \
      --source=SOURCE_LOCATION

如要將模組標示為預先發布版本，請在 VERSION 後方加上破折號，並附加模組的預先發布 ID：

  gcloud artifacts go upload \
      --module-path=MODULE_PATH \
      --version=VERSION-PRE_RELEASE_IDENTIFIERS \
      --source=SOURCE_LOCATION

將 PRE_RELEASE_IDENTIFIERS 替換為以半形句號分隔的 ASCII 英數字元和連字號。舉例來說，如要上傳路徑為 example.com/foo 且由 alpha.x.12m.5 識別的模組搶先版，請執行下列指令：

  gcloud artifacts go upload \
      --module-path=example.com/foo \
      --version=v1.0.0-alpha.x.12m.5 \
      --source=SOURCE_LOCATION

上傳新的主要版本

存放區模式：標準

主要版本無法與舊版回溯相容。為避免使用者匯入破壞性變更，v1 之後的主要版本必須與舊版使用不同的模組路徑。從 v2 開始，主要版本會新增至模組路徑結尾。

舉例來說，example.com/foo 的 v2.0.0 模組路徑會是 example.com/foo/v2。

建議的最佳做法是開發主要版本，並將這些版本放在以主要版本尾碼命名的個別目錄中。v1

如要上傳模組的新主要版本 2.0.0，並在設定預設值時，將路徑 example.com/foo 設為預設專案、存放區和位置，請執行下列指令：

  gcloud artifacts go upload --module-path=example.com/foo/v2 --version=v2.0.0

列出模組

存放區模式：標準、遠端、虛擬

設定預設值後，執行下列指令，即可檢查預設專案、存放區和位置中上傳的 Go 模組：

  gcloud artifacts packages list

輸出內容會類似以下內容：

  Listing items under project my-project, location us-west1, repository my-repo.

  PACKAGE                   CREATE_TIME          UPDATE_TIME
  example.com/foo           2022-06-03T20:43:39  2022-06-20T20:37:40

查看模組版本詳細資料

存放區模式：標準、遠端、虛擬

設定預設值後，執行下列指令即可查看預設專案、存放區和位置中的模組版本：

  gcloud artifacts versions list --package=MODULE_PATH

輸出內容會類似以下內容：

  Listing items under project my-project, location us-west1, repository my-repo, package example.com/foo.

  VERSION  DESCRIPTION  CREATE_TIME          UPDATE_TIME
  v0.1.0                2022-06-03T20:43:39  2022-06-03T20:43:39
  v0.1.1                2022-06-20T20:37:40  2022-06-20T20:37:40

將模組做為依附元件使用

存放區模式：標準、遠端、虛擬

如要匯入儲存在 Artifact Registry 中的模組，您需要指示 Go 從 Artifact Registry 尋找依附元件，並略過總和檢查碼資料庫。按照「為 Go 設定驗證」中的操作說明，設定驗證和 Go 環境。

1. 如果您使用短期憑證向 Artifact Registry 進行驗證，則必須執行下列指令來重新整理 OAuth 權杖：

     GOPROXY=proxy.golang.org \
     go run github.com/GoogleCloudPlatform/artifact-registry-go-tools/cmd/auth@latest refresh
   

2. 如果模組還沒有 go.mod 檔案，請將目錄變更為模組的資料夾，然後執行 go mod init，為套件建立 go.mod 檔案。

     go mod init MODULE_PATH
   

   請將 MODULE_PATH 改成儲存在 Artifact Registry 中的模組路徑。詳情請參閱 Go 模組參考資料。

3. 如要要求 Artifact Registry 中儲存的模組版本，請編輯 go.mod 檔案，使其類似下列內容：

   
   module example.com/bar
   
   go 1.19
   
   require example.com/foo v0.1.0
   

   更改下列內容：

   • example.com/foo 是必要模組的模組路徑
   • v0.1.0 是儲存在 Artifact Registry 中的版本

4. 在 main.go 檔案的 import 區段中，照常加入模組路徑。

   舉例來說，如要匯入 Artifact Registry 中儲存的路徑為 example.com/foo 的模組，匯入區段可能如下所示：

     
     package main
   
     import (
       foo "example.com/foo"
     )
   
     func main() {
   
       ...
   
     }
   
     
   

5. 執行 go mod tidy 下載依附元件：

     go mod tidy
   

6. 照常執行模組：

     go run .
   

   系統會下載儲存在 Artifact Registry 中的模組，並做為依附元件使用。

刪除封裝的 Go 模組

存放區模式：標準、遠端

您可以刪除套件和所有版本，也可以刪除特定版本。

• 套件刪除後即無法復原。

刪除套件或套件版本前，請確認您已通報或解決其中的任何重要依附元件。

如要刪除套件，請按照下列步驟操作：

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

如要刪除套件版本，請按照下列步驟操作：

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

後續步驟

• 請嘗試 Go 快速入門導覽課程。
• 下載與模組或版本相關聯的個別檔案，無須使用 Go 指令。