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

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

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

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

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

事前準備

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

必要的角色

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

建立、更新、取得、列出及刪除規則： Artifact Registry 存放區管理員 (roles/artifactregistry.repoAdmin)
取得及列出規則： Artifact Registry 讀取者 (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) 定義下載規則的條件。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 定義條件

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