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

预览

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

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

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

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

准备工作

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

所需的角色

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

• 创建、更新、获取、列出和删除规则： Artifact Registry Repository Administrator (roles/artifactregistry.repoAdmin)
• 获取并列出规则： Artifact Registry 读取者 (roles/artifactregistry.reader)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建下载规则

gcloud

在使用下面的命令数据之前，请先进行以下替换：

• RULE_NAME：规则的名称。名称 在您的代码库中必须是唯一的，长度上限为 256 个字符，并且由 字母数字字符、百分号编码字符或列表中的字符 [-、.、_、~、:、@、+、^]。
• ACTION：对与此规则匹配的下载内容应用的操作。在 ALLOW 和 DENY 之间进行选择。前者表示规则允许发生匹配的下载，后者表示规则阻止发生匹配的下载。
• PACKAGE：（可选） 软件包。如果提供，则该规则仅适用于指定的软件包，而非整个 存储库
• CONDITION：（可选）a 用于定义匹配的 CEL 表达式 规则。如果提供了此参数，则仅将规则应用于符合指定条件的下载内容。 例如 pkg.version.id < '3.0'。
• PROJECT：您的 Google Cloud 项目 ID。 如果您的项目 ID 包含英文冒号 (:)，请参阅网域级项目。
• LOCATION：代码库的单区域或多区域位置。
• REPOSITORY：代码库 ID。

执行以下命令：

Linux、macOS 或 Cloud Shell

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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：（可选）a 用于定义匹配的 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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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 init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (PowerShell)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

Windows (cmd.exe)

注意：通过运行 gcloud init 或 gcloud auth login 和 gcloud config set project，确保您已使用身份验证和项目初始化了 Google Cloud CLI。

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

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