本頁面由 Cloud Translation API 翻譯而成。

使用下載規則限制構件下載作業

本頁說明如何建立及管理下載規則，限制從 Artifact Registry 存放區下載構件。

下載規則可讓您允許或拒絕從存放區和套件下載構件。您也可以設定條件，讓規則套用至特定標記或版本。

如要進一步瞭解下載規則的運作方式，請參閱「控管存取權並保護構件」總覽中的「限制構件下載」一節。

事前準備

如果您尚未建立，請建立 Docker 格式的標準存放區。
(選用) 設定 Google Cloud CLI 指令的預設值。

必要的角色

如要取得建立及管理下載規則所需的權限，請要求管理員授予您存放區的下列 IAM 角色：

建立、更新、取得、列出及刪除規則： Artifact Registry 存放區管理員 (roles/artifactregistry.repoAdmin)
取得及列出規則： Artifact Registry Reader (roles/artifactregistry.reader)

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

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

建立下載規則

gcloud

使用下列任何指令資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱必須在您的存放區中是唯一的，長度上限為 256 個半形字元，且只能包含英數字元、百分比編碼字元，或 [-, ., _, ~, :, @, +, ^] 清單中的字元。
ACTION：套用至符合此規則的下載作業。請選擇 ALLOW (規則允許相符的下載作業) 或 DENY (規則封鎖相符的下載作業)。
PACKAGE：(選用) 套件名稱。如果提供，則規則只會套用至指定的套件，而非整個存放區。
CONDITION：(選用) 定義比對規則的 CEL 運算式。如果提供此參數，系統只會將規則套用至符合指定條件的下載項目。例如：pkg.version.id < '3.0'。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud artifacts rules create RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows (PowerShell)

gcloud artifacts rules create RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows (cmd.exe)

gcloud artifacts rules create RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"

系統會建立新規則，並顯示以下輸出內容：

Created rule [RULE_NAME].

詳情請參閱 gcloud artifacts rules create 指令。

API

使用任何要求資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱必須在您的存放區中是唯一的，長度上限為 256 個半形字元，且只能包含英數字元、百分比編碼字元，或 [-, ., _, ~, :, @, +, ^] 清單中的字元。
ACTION：套用至符合此規則的下載作業。請選擇 ALLOW (規則允許相符的下載作業) 或 DENY (規則封鎖相符的下載作業)。
PACKAGE：(選用) 套件名稱。如果提供，則規則只會套用至指定的套件，而非整個存放區。
CONDITION：(選用) 定義比對規則的 CEL 運算式。如果提供此參數，系統只會將規則套用至符合指定條件的下載項目。例如：pkg.version.id < '3.0'。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區 ID。

HTTP 方法和網址：

POST https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME

JSON 要求主體：

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json" `
    -InFile request.json `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules?ruleID=RULE_NAME" | Select-Object -Expand Content

新規則建立完成後，會顯示以下輸出內容：

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}

詳情請參閱 REST 參考資料。

列出下載規則

gcloud

使用下列任何指令資料之前，請先替換以下項目：

PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud artifacts rules list \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules list `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules list ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY

系統會顯示指定專案、位置和存放區的規則清單，如下所示：

RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'

詳情請參閱 gcloud artifacts rules list 指令。

API

使用任何要求資料之前，請先替換以下項目：

PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

HTTP 方法和網址：

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules"

PowerShell (Windows)

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules" | Select-Object -Expand Content

指定專案、位置和存放區的規則清單會顯示如下：

{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}

詳情請參閱 REST 參考資料。

說明下載規則

gcloud

使用下列任何指令資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱不得重複。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud artifacts rules describe RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules describe RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules describe RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY

規則詳細資料的顯示方式如下：

RULE: my-rule
PACKAGE: example.com/foo
ACTION: DENY
OPERATION: DOWNLOAD
CONDITION: pkg.version.id < '3.0'

詳情請參閱 gcloud artifacts rules describe 指令。

API

使用任何要求資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱不得重複。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

HTTP 方法和網址：

GET https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell (Windows)

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

規則詳細資料的顯示方式如下：

{
  "rules": [
    {
      "name": "projects/my-project/locations/us-central1/repositories/my-repo/rules/my-rule",
      "action": "DENY",
      "operation": "DOWNLOAD",
      "condition": {
        "expression": "pkg.version.id \u003c '3.0'"
      },
      "packageId": "example.com/foo"
    }
  ]
}

詳情請參閱 REST 參考資料。

更新下載規則

gcloud

移除不想更新的所有變數。

使用下列任何指令資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱不得重複。
ACTION：套用至符合此規則的下載作業。請選擇介於 ALLOW 至 DENY 之間的值。
PACKAGE：套件名稱。如果未提供，則規則會套用至整個存放區。
CONDITION：定義比對規則的 CEL 運算式。如果提供此參數，系統只會將規則套用至符合指定條件的下載項目。例如：pkg.version.id < '3.0'。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud artifacts rules update RULE_NAME \
    --action=ACTION \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY \
    --package=PACKAGE \
    --condition="CONDITION"

Windows (PowerShell)

gcloud artifacts rules update RULE_NAME `
    --action=ACTION `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY `
    --package=PACKAGE `
    --condition="CONDITION"

Windows (cmd.exe)

gcloud artifacts rules update RULE_NAME ^
    --action=ACTION ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY ^
    --package=PACKAGE ^
    --condition="CONDITION"

更新後的規則詳細資料如下所示：

Updated rule [RULE_NAME].
action: ACTION
condition:
  expression: CONDITION
name: projects/PROJECT/locationsLOCATION/repositories/REPOSITORY/rules/RULE_NAME
operation: DOWNLOAD

詳情請參閱 gcloud artifacts rules update 指令。

API

移除不想更新的所有變數。

使用任何要求資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱不得重複。
ACTION：套用至符合此規則的下載作業。請選擇介於 ALLOW 至 DENY 之間的值。
PACKAGE：套件名稱。如果未提供，則規則會套用至整個存放區。
CONDITION：定義比對規則的 CEL 運算式。如果提供此參數，系統只會將規則套用至符合指定條件的下載項目。例如：pkg.version.id < '3.0'。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

HTTP 方法和網址：

PATCH https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

JSON 要求主體：

{
  "action":"ACTION",
  "packageId":"PACKAGE",
  "condition":
  {
    "expression":"CONDITION"
  }
}

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d @request.json \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell (Windows)

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json" `
    -InFile request.json `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

更新後的規則詳細資料如下所示：

{
  "name": "projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME",
  "action": ACTION,
  "operation": "DOWNLOAD"
}

詳情請參閱 REST 參考資料。

刪除下載規則

gcloud

使用下列任何指令資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱不得重複。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud artifacts rules delete RULE_NAME \
    --project=PROJECT \
    --location=LOCATION \
    --repository=REPOSITORY

Windows (PowerShell)

gcloud artifacts rules delete RULE_NAME `
    --project=PROJECT `
    --location=LOCATION `
    --repository=REPOSITORY

Windows (cmd.exe)

gcloud artifacts rules delete RULE_NAME ^
    --project=PROJECT ^
    --location=LOCATION ^
    --repository=REPOSITORY

系統會刪除規則，並顯示以下輸出內容：

You are about to delete rule [RULE_NAME]

Do you want to continue (Y/n)?  Y

Deleted rule [RULE_NAME].

詳情請參閱 gcloud artifacts rules delete 指令。

API

使用任何要求資料之前，請先替換以下項目：

RULE_NAME：規則名稱。名稱不得重複。
PROJECT：您的 Google Cloud 專案 ID。如果您的專案 ID 包含冒號 (:)，請參閱網域範圍專案。
LOCATION：存放區的地區或多地區位置。
REPOSITORY：存放區名稱。

HTTP 方法和網址：

DELETE https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME"

PowerShell (Windows)

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://artifactregistry.googleapis.com/v1/projects/PROJECT/locations/LOCATION/repositories/REPOSITORY/rules/RULE_NAME" | Select-Object -Expand Content

詳情請參閱 REST 參考資料。

使用 CEL 定義條件

您可以使用一般運算語言 (CEL) 定義下載規則的條件，這是一種用於運算式評估的開放原始碼語言。Artifact Registry 會提供 pkg 物件，其中包含下列屬性：

pkg.id：代表構件套件名稱的字串。可搭配在存放區層級設定的規則使用。
pkg.version.id：代表構件版本的字串。
pkg.version.tag：代表構件的標記的字串。僅限在 Docker 存放區中使用。

您可以使用 CEL 搭配邏輯運算子和內建函式。以下是一些可能適用於下載規則的 CEL 運算式範例：

適用於在存放區層級設定的規則：

  pkg.id == 'myPackage'  #Artifact package matches 'myPackage'
  pkg.id.startsWith('my') #Artifact package must start with 'my'

適用於套件上的規則：

  pkg.version.id != '1.0.0' #Artifact version is not '1.0.0'
  pkg.version.id > '1.0.1' || pkg.version.id < '0.0.1' #Artifact version is greater than '1.0.1' or less than '0.0.1'
  pkg.version.id.startsWith('1.0.') #Artifact version must start with '1.0.'
  pkg.version.id in ['1.0.0', '1.2.0'] #Artifact version must be a member of the list ['1.0.0', '1.2.0']
  pkg.version.tag == 'tag1' #Artifact tag must be 'tag1'
  pkg.version.tag.startsWith('tag') #Artifact tag must start with 'tag'
  pkg.version.tag in ['tag1', 'tag2'] #Artifact tag must be a member of the list ['tag1', 'tag2']

在 Docker 存放區中新增標記為基礎條件的規則 (例如 pkg.version.tag == 'latest') 時，請注意下列事項：

透過摘要拉取時，用戶端不會提供標記。使用標記的條件會與空白標記進行比對，可能會導致非預期的行為。
對於多架構容器映像檔，使用代碼的條件可能無法正常運作，因此應避免使用。

使用下載規則限制構件下載作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

建立下載規則

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

列出下載規則

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

說明下載規則

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

更新下載規則

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

刪除下載規則

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

API

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

使用 CEL 定義條件

使用下載規則限制構件下載作業