此页面由 Cloud Translation API 翻译。

使用下载规则限制工件下载

本页介绍了如何通过创建和管理下载规则来限制从 Artifact Registry 代码库下载工件。

借助下载规则，您可以允许或禁止从代码库和软件包下载工件。您还可以设置条件，以便将规则应用于特定代码或版本。

如需详细了解下载规则的运作方式，请参阅“控制访问权限和保护工件”概览的限制工件下载部分。

准备工作

如果您还没有，请创建 Docker 格式的标准代码库。
（可选）为 Google Cloud CLI 命令配置默认值。

所需的角色

如需获得创建和管理下载规则所需的权限，请让管理员向您授予代码库的以下 IAM 角色：

创建、更新、获取、列出和删除规则： Artifact Registry Repository Administrator (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 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

系统会删除规则，并输出以下内容：

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'）的规则时，请注意以下事项：

通过摘要拉取时，客户端不会提供标记。使用代码的条件将与空代码进行匹配，并且可能会导致意外行为。
对于多架构容器映像，使用标记的条件可能无法按预期运行，因此应避免使用。