管理 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 authenticate。

必要的角色

如要取得管理模組所需的權限，請要求管理員授予您存放區的下列 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 英數字元和連字號。舉例來說，如要上傳模組的預先發布版本，並使用 alpha.x.12m.5 指定的路徑 example.com/foo 模組，請執行下列指令：

  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 區段中，照常加入模組路徑。

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

     
     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 指令。