管理 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 進行驗證。

注意： Artifact Registry 不支援 Go 模組 -tool 旗標。

必要的角色

如要取得管理模組所需的權限，請要求管理員在存放區中授予下列 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

注意： 預先發布 ID 必須是以半形句號分隔的 ASCII 英數字元和連字號。不支援中繼資料。如要進一步瞭解版本控管，請參閱語意版本控管 2.0.0，以及這篇網誌文章，瞭解 Go 的相關詳細資料。

上傳新的主要版本

存放區模式：標準

主要版本無法與舊版回溯相容。為避免使用者匯入破壞性變更，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 模組

存放區模式：標準、遠端

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

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

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

1. Open the Repositories page in the Google Cloud console.

   開啟「存放區」頁面

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Select the package that you want to delete.

4. Click DELETE.

5. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

1. Open the Repositories page in the Google Cloud console.

   開啟「存放區」頁面

2. In the repository list, click the appropriate repository.

   The Packages page lists the packages in the repository.

3. Click a package to view versions of that package.

4. Select versions that you want to delete.

5. Click DELETE.

6. In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

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

Replace the following:

• VERSION is the name of the version to delete.
• PACKAGE is the name of the package in the repository.
• REPOSITORY is the name of the repository. If you configured a default repository, then you can omit this flag to use the default.
• LOCATION is the regional or multi-regional location of the repository. Use this flag to view repositories in a specific location. If you configured a default location, then you can omit this flag to use the default.

The --async flag causes the command to return immediately, without waiting for the operation in progress to complete.

後續步驟

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