AWS CLI CodeArtifact `get-repository-endpoint` 命令详解:获取仓库各包格式的 URL 端点
AWS CLI CodeArtifact get-repository-endpoint 命令详解:获取仓库各包格式的 URL 端点
本篇文章以 AWS CLI 官方示例文档 为核心,结合当前仓库中 CodeArtifact 服务模型 service-2.json 与 login 命令源码,系统讲解 aws codeartifact get-repository-endpoint 的用途、全部参数、输出结构、端点的 URL 组成规律,以及它在"连接仓库、配置包管理器"这一完整流程中的位置。读完本文,你将能够针对 npm、PyPI、Maven、NuGet 等任意包格式准确查询仓库端点,并将其接入 aws codeartifact login、get-authorization-token 等配套命令完成客户端配置。
一、命令作用:返回仓库针对指定包格式的 URL 端点
在 AWS CodeArtifact 中,一个仓库会同时托管多种包格式(package format)的制品,而每种包格式都有自己独立的访问端点(endpoint)。get-repository-endpoint 的作用就是返回某个域(domain)下的某个仓库(repository)针对指定包格式的 URL。
根据仓库中的服务模型定义,该命令对应的底层操作说明如下(见 service-2.json 中 GetRepositoryEndpoint 操作的 documentation 字段):
Returns the endpoint of a repository for a specific package format. A repository has one endpoint for each package format.
即:每个仓库对每种包格式都恰好有一个端点,支持格式包括 cargo、generic、maven、npm、nuget、pypi、ruby、swift 八种。
该端点 URL 是后续一切"连接客户端"操作的基础:无论是用 npm config set registry、pip config、mvn settings.xml,还是直接用 AWS CLI 的 login 命令,最终都要把这个 URL 写入包管理器的配置。
二、核心示例(来自官方示例文档)
get-repository-endpoint.rst 中的标准用法如下:查询 test-domain 域中 test-repo 仓库的 npm 端点。
aws codeartifact get-repository-endpoint \
--domain test-domain \
--repository test-repo \
--format npm
输出结果:
{
"repositoryEndpoint": "https://test-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/test-repo/"
}
repositoryEndpoint 字段就是该仓库 npm 格式的完整 URL。将这个 URL 配置给 npm 客户端即可拉取/推送该仓库中的 npm 包。
三、全部参数详解(基于服务模型)
依据 service-2.json 中 GetRepositoryEndpointRequest 结构的定义,该命令共支持 5 个参数,其中 3 个为必填:
| 参数 | 类型 | 必填 | 说明 | 校验规则 |
|---|---|---|---|---|
--domain |
DomainName |
是 | 包含目标仓库的 CodeArtifact 域名称 | 长度 2–50 字符,模式 [a-z][a-z0-9\-]{0,48}[a-z0-9] |
--repository |
RepositoryName |
是 | 仓库名称 | 长度 2–100 字符,模式 [A-Za-z0-9][A-Za-z0-9._\-]{1,99} |
--format |
PackageFormat |
是 | 要查询的包格式 | 枚举:npm、pypi、maven、nuget、generic、ruby、swift、cargo |
--domain-owner |
AccountId |
否 | 拥有该域的 AWS 账户 12 位账号 ID(不含短横线或空格) | 恰好 12 位数字,模式 [0-9]{12} |
--endpoint-type |
EndpointType |
否 | 端点类型 | 枚举:dualstack、ipv4 |
3.1 --format 支持的八种包格式
PackageFormat 枚举定义在 service-2.json 中:
"PackageFormat": {"type": "string", "enum": ["npm", "pypi", "maven", "nuget", "generic", "ruby", "swift", "cargo"]}
- npm:Node.js 生态,配合
npm/yarn/pnpm使用; - pypi:Python 生态,配合
pip/poetry/twine使用; - maven:JVM 生态,配合
mvn/gradle使用; - nuget:.NET 生态,配合
dotnet使用; - generic:通用格式,适合存放任意类型的制品(如 zip 包、二进制文件);
- ruby:RubyGems 生态,配合
gem/bundle使用; - swift:Swift 包管理器生态,配合 Swift Package Manager 使用;
- cargo:Rust 生态,配合
cargo使用。
注意:即使仓库尚未存放任何该格式的包,只要仓库创建成功,其各格式端点即已存在,可以正常查询。
3.2 --domain-owner:跨账户查询
默认情况下该命令作用于当前凭证所属账户的域。若仓库位于其他 AWS 账户拥有的域中,需要通过 --domain-owner 显式传入 12 位账户 ID。它与 create-repository 示例(见 create-repository.rst)中出现的 --domain-owner 111122223333 是同一个语义。
3.3 --endpoint-type:dualstack 与 ipv4
当仓库需要支持通过 IPv6 访问(例如使用 dualstack 类型的 VPC 端点)时,可指定 --endpoint-type dualstack;默认(不传该参数)返回常规的 IPv4 端点。
四、端点 URL 的结构规律
从输出结果可以看出,CodeArtifact 仓库端点的 URL 具有固定结构:
https://<domain>-<account-id>.d.codeartifact.<region>.amazonaws.com/<format>/<repository>/
以上文输出为例拆解 https://test-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/test-repo/:
| URL 片段 | 含义 | 来源 |
|---|---|---|
test-domain |
域名称 | --domain |
111122223333 |
域所属账户的 12 位 ID | 凭证对应的账户或 --domain-owner |
us-west-2 |
区域 | 当前 CLI 配置的区域 |
npm |
包格式 | --format |
test-repo |
仓库名称 | --repository |
该结构并非示例巧合,在 login.rst 中,aws codeartifact login 命令的输出同样打印了完全一致的端点 URL:https://test-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/test-repo/,可作为结构规律的交叉印证。
五、响应字段说明
GetRepositoryEndpointResult 结构(见 service-2.json)只包含一个字段:
| 字段 | 类型 | 说明 |
|---|---|---|
repositoryEndpoint |
String |
返回端点的完整 URL |
实用技巧:当你在脚本中只需要裸 URL(不带引号、不带 JSON 包装)时,可结合 --query 与 --output 直接提取:
aws codeartifact get-repository-endpoint \
--domain test-domain \
--repository test-repo \
--format npm \
--query repositoryEndpoint \
--output text
这与 get-authorization-token.rst 中通过 --query authorizationToken --output text 提取令牌的做法一致,便于将输出直接赋给环境变量或写入配置文件。
六、在"连接仓库"流程中的位置:与 login、get-authorization-token 的配合
获取端点只是第一步,完整的连接流程通常包含"获取端点 + 获取令牌 + 配置客户端"。仓库中的 login 命令正是这一流程的自动化封装。
6.1 login 命令内部依赖端点
查看 login.py,BaseLogin 类的构造函数(第 55–60 行)接收的参数包括:
def __init__(self, auth_token, expiration, repository_endpoint,
domain, repository, subprocess_utils, namespace=None):
self.auth_token = auth_token
self.expiration = expiration
self.repository_endpoint = repository_endpoint
也就是说,login 在底层需要拿到 repository_endpoint(即 get-repository-endpoint 的返回值)才能把包管理器配置到正确的仓库地址上。手动执行 get-repository-endpoint 的本质,就是把 login 自动完成的"获取端点"这一步拆出来单独做,适用于 login 不支持的工具或需要精细控制配置文件的场景。
6.2 login 的自动化方式
如果不想手动拼接端点,直接使用 login 即可(示例见 login.rst):
aws codeartifact login \
--domain test-domain \
--repository test-repo \
--tool npm
输出示例:
Successfully configured npm to use AWS CodeArtifact repository https://test-domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/npm/test-repo/
Login expires in 12 hours at 2020-11-12 01:53:16-05:00
可见 login 内部既完成了端点获取,也完成了令牌获取与包管理器配置。
6.3 手动配置方式
对于 login 不直接支持的工具或脚本化场景,典型的手动流程是:
# 1. 获取端点
ENDPOINT=$(aws codeartifact get-repository-endpoint \
--domain test-domain \
--repository test-repo \
--format pypi \
--query repositoryEndpoint \
--output text)
# 2. 获取授权令牌(12 小时有效)
TOKEN=$(aws codeartifact get-authorization-token \
--domain test-domain \
--query authorizationToken \
--output text)
# 3. 将端点与令牌写入包管理器配置(以 pip 为例)
pip config set global.index-url "$ENDPOINT"
pip config set global.extra-index-url "https://pypi.org/simple"
七、底层原理:该命令对应的 HTTP 请求
从服务模型 service-2.json 的 operations.GetRepositoryEndpoint 定义可以看到:
{
"name": "GetRepositoryEndpoint",
"http": {
"method": "GET",
"requestUri": "/v1/repository/endpoint"
},
"input": {"shape": "GetRepositoryEndpointRequest"},
"output": {"shape": "GetRepositoryEndpointResult"}
}
即该命令实际发起一个 HTTP GET 请求到 /v1/repository/endpoint,domain、repository、format 等参数均以 query string 形式传递(location: "querystring")。这也是该命令无副作用、可安全重复调用的根本原因——它只是一个只读查询操作。
八、常见错误与排查
根据服务模型中的 errors 定义,GetRepositoryEndpoint 可能返回以下异常(对应 HTTP 状态码见 service-2.json 中各异常的 error.httpStatusCode):
| 异常 | HTTP 状态码 | 典型触发场景 |
|---|---|---|
ValidationException |
400 | --format 传了枚举之外的值(如 docker)、--domain 或 --repository 不符合命名规则 |
AccessDeniedException |
403 | 当前凭证无权访问该域/仓库,或跨账户查询时 --domain-owner 传错 |
ResourceNotFoundException |
404 | 指定的 domain / repository 不存在,或区域错误 |
ThrottlingException |
429 | 请求过于频繁被限流,可等待 retryAfterSeconds 后再试 |
InternalServerException |
500 | CodeArtifact 服务内部错误 |
常见排查路径:
- 检查区域:端点 URL 中的区域必须与仓库所在区域一致,可通过
--region显式指定; - 检查账户:跨账户场景必须带
--domain-owner; - 检查格式拼写:
--format为小写枚举值,如npm、pypi、maven,注意不要写成NPM或PyPI。
九、结合本仓库继续深入
- 官方 CLI 示例:查看 get-repository-endpoint.rst 原文;
- 服务模型:完整的参数、枚举、响应与异常定义见 service-2.json;
- 配套示例:login.rst、get-authorization-token.rst、create-repository.rst;
- 自动化封装实现:login.py 中
BaseLogin对repository_endpoint的消费逻辑。
更多关于"连接仓库"的完整说明,可查阅 AWS CodeArtifact User Guide 的 "Connect to a repository" 章节。