本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 将 CodeArtifact 与 Ruby 结合使用
这些主题介绍如何将 RubyGems 和 Bundler 工具与 CodeArtifact 结合使用，以安装和发布 Ruby Gem。
**注意**
CodeArtifact 推荐使用 Ruby 3.3 或更高版本，不适用于 Ruby 2.6 或更低版本。
**Topics**
+ [配置并使用 RubyGems 和 Bundler](configure-use-rubygems-bundler.md)
+ [RubyGems 命令支持](ruby-command-support.md)
+ [Bundler 兼容性](bundler-compatibility.md)
# 配置 RubyGems 和 Bundler 并将其与 CodeArtifact 结合使用
在 CodeArtifact 中创建存储库后，您可以使用 RubyGems（`gem`）和 Bundler（`bundle`）来安装和发布 Gem。本主题介绍如何配置程序包管理器以使用 CodeArtifact 存储库进行身份验证，以及使用 CodeArtifact 存储库。
## 使用 CodeArtifact 配置 RubyGems（`gem`）和 Bundler（`bundle`）
要使用 RubyGems（`gem`）或 Bundler（`bundle`）向 AWS CodeArtifact 发布 Gem 或使用其中的 Gem，首先需要使用您的 CodeArtifact 存储库信息（包括用于访问该存储库的凭证）对其进行配置。按照以下程序之一中的步骤，使用您的 CodeArtifact 存储库端点信息和凭证来配置 `gem` 和 `bundle` CLI 工具。
### 按照控制台说明来配置 RubyGems 和 Bundler
您可以按照控制台中的配置说明，将 Ruby 程序包管理器连接到 CodeArtifact 存储库。控制台说明提供了自定义命令，您可以运行这些命令来设置程序包管理器，而无需查找和填写 CodeArtifact 信息。
1. 打开 AWS CodeArtifact 控制台，网址为：[https://console.aws.amazon.com/codesuite/codeartifact/home](https://console.aws.amazon.com/codesuite/codeartifact/home)。
1. 在导航窗格中，选择**存储库**，然后选择要用于安装或发布 Ruby Gem 的存储库。
1. 选择**查看连接说明**。
1. 选择操作系统。
1. 选择要使用 CodeArtifact 存储库配置的 Ruby 程序包管理器客户端。
1. 按照生成的说明来配置程序包管理器客户端，以便从存储库安装 Ruby Gem 或将 Ruby Gem 发布到存储库。
### 手动配置 RubyGems 和 Bundler
如果您无法或不想使用控制台中的配置说明，可以按照以下说明手动将 Ruby 程序包管理器连接到 CodeArtifact 存储库。
1. 在命令行中，使用以下命令来提取 CodeArtifact 授权令牌并将其存储在环境变量中。
+ 将 *my\$1domain* 替换为您的 CodeArtifact 域名。
+ 将 *111122223333* 替换为域所有者的 AWS 账户 ID。如果您要访问您拥有的域中的存储库，则无需包括 `--domain-owner`。有关更多信息，请参阅 [跨账户域](domain-overview.md#domain-overview-cross-account)。
------
#### [ macOS and Linux ]
```
export CODEARTIFACT_AUTH_TOKEN=`aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text`
```
------
#### [ Windows ]
+ Windows（使用默认命令 shell）：
```
for /f %i in ('aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text') do set CODEARTIFACT_AUTH_TOKEN=%i
```
+ Windows PowerShell：
```
$env:CODEARTIFACT_AUTH_TOKEN = aws codeartifact get-authorization-token --domain my_domain --domain-owner 111122223333 --query authorizationToken --output text
```
------
1. 要将 Ruby Gem 发布到存储库，请使用以下命令获取 CodeArtifact 存储库的端点，然后将其存储在 `RUBYGEMS_HOST` 环境变量中。`gem` CLI 使用此环境变量来确定 Gem 的发布位置。
**注意**
或者，您可以不使用 `RUBYGEMS_HOST` 环境变量，而是在使用 `gem push` 命令时为存储库端点提供 `--host` 选项。
+ 将 *my\$1domain* 替换为您的 CodeArtifact 域名。
+ 将 *111122223333* 替换为域所有者的 AWS 账户 ID。如果您要访问您拥有的域中的存储库，则无需包括 `--domain-owner`。有关更多信息，请参阅 [跨账户域](domain-overview.md#domain-overview-cross-account)。
+ 将 *my\$1repo* 替换为您的 CodeArtifact 存储库名称。
------
#### [ macOS and Linux ]
```
export RUBYGEMS_HOST=`aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text | sed 's:/*$::'`
```
------
#### [ Windows ]
以下命令可检索存储库端点，去除尾部 `/`，然后将其存储在一个环境变量中。
+ Windows（使用默认命令 shell）：
```
for /f %i in ('aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text') do set RUBYGEMS_HOST=%i
set RUBYGEMS_HOST=%RUBYGEMS_HOST:~0,-1%
```
+ Windows PowerShell：
```
$env:RUBYGEMS_HOST = (aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text).TrimEnd("/")
```
------
以下 URL 是一个示例存储库端点：
```
https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/
```
**注意**
要使用双堆栈端点，请使用 `codeartifact.region.on.aws` 端点。
1. 要将 Ruby Gem 发布到存储库，您必须通过编辑 `~/.gem/credentials` 文件以包含身份验证令牌，来使用 RubyGems 向 CodeArtifact 进行身份验证。如果 `~/.gem/` 目录或 `~/.gem/credentials` 文件不存在，则创建该目录和文件。
------
#### [ macOS and Linux ]
```
echo ":codeartifact_api_key: Bearer $CODEARTIFACT_AUTH_TOKEN" >> ~/.gem/credentials
```
------
#### [ Windows ]
+ Windows（使用默认命令 shell）：
```
echo :codeartifact_api_key: Bearer %CODEARTIFACT_AUTH_TOKEN% >> %USERPROFILE%/.gem/credentials
```
+ Windows PowerShell：
```
echo ":codeartifact_api_key: Bearer $env:CODEARTIFACT_AUTH_TOKEN" | Add-Content ~/.gem/credentials
```
------
1. 要使用 `gem` 从存储库安装 Ruby Gem，必须将存储库端点信息和身份验证令牌添加到 `.gemrc` 文件。您可以将其添加到全局文件（`~/.gemrc`）或项目 `.gemrc` 文件。必须添加到 `.gemrc` 的 CodeArtifact 信息是存储库端点和身份验证令牌的组合。它的格式如下：
```
https://aws:${CODEARTIFACT_AUTH_TOKEN}@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/
```
+ 对于身份验证令牌，您可以使用在上一步中设置的 `CODEARTIFACT_AUTH_TOKEN` 环境变量。
+ 要获取存储库端点，您可以读取之前设置的 `RUBYGEMS_HOST` 环境变量的值，也可以使用以下 `get-repository-endpoint` 命令根据需要替换这些值：
```
aws codeartifact get-repository-endpoint --domain my_domain --domain-owner 111122223333 --repository my_repo --format ruby --query repositoryEndpoint --output text
```
获取端点后，使用文本编辑器在适当位置添加 `aws:${CODEARTIFACT_AUTH_TOKEN}@`。创建存储库端点和身份验证令牌字符串后，使用 `echo` 命令将其添加到 `.gemrc` 文件的 `:sources:` 部分，具体操作如下：
**警告**
CodeArtifact 不支持使用 `gem sources -add` 命令将存储库添加为源。必须将源直接添加到文件。
------
#### [ macOS and Linux ]
```
echo ":sources:
- https://aws:${CODEARTIFACT_AUTH_TOKEN}@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/" > ~/.gemrc
```
------
#### [ Windows ]
+ Windows（使用默认命令 shell）：
```
echo ":sources:
- https://aws:%CODEARTIFACT_AUTH_TOKEN%@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/" > "%USERPROFILE%\.gemrc"
```
+ Windows PowerShell：
```
echo ":sources:
- https://aws:$env:CODEARTIFACT_AUTH_TOKEN@my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/" | Add-Content ~/.gemrc
```
------
1. 要使用 Bundler，必须通过运行以下 `bundle config` 命令，使用存储库端点 URL 和身份验证令牌来配置 Bundler：
------
#### [ macOS and Linux ]
```
bundle config $RUBYGEMS_HOST aws:$CODEARTIFACT_AUTH_TOKEN
```
------
#### [ Windows ]
+ Windows（使用默认命令 shell）：
```
bundle config %RUBYGEMS_HOST% aws:%CODEARTIFACT_AUTH_TOKEN%
```
+ Windows PowerShell：
```
bundle config $Env:RUBYGEMS_HOST aws:$Env:CODEARTIFACT_AUTH_TOKEN
```
------
您已经使用 CodeArtifact 存储库配置了 RubyGems（`gem`）和 Bundler（`bundle`），现在可以通过它们向存储库发布 Ruby Gem 以及使用来自存储库的 Ruby Gem。
## 从 CodeArtifact 安装 Ruby Gem
按照以下步骤，使用 `gem` 或 `bundle` CLI 工具从 CodeArtifact 存储库安装 Ruby Gem。
### 使用 `gem` 安装 Ruby Gem
可以使用 RubyGems（`gem`）CLI 从 CodeArtifact 存储库快速安装特定版本的 Ruby Gem。
**使用 `gem` 从 CodeArtifact 存储库安装 Ruby Gem**
1. 如果还没有配置，请按照[使用 CodeArtifact 配置 RubyGems（`gem`）和 Bundler（`bundle`）](#configure-ruby-gem) 中的步骤将 `gem` CLI 配置为通过适当的凭证来使用 CodeArtifact 存储库。
**注意**
生成的授权令牌有效期为 12 小时。如果自创建令牌以来已过去 12 小时，则需要创建一个新的令牌。
1. 使用以下命令从 CodeArtifact 安装 Ruby Gem：
```
gem install my_ruby_gem --version 1.0.0
```
### 使用 `bundle` 安装 Ruby Gem
可以使用 Bundler（`bundle`）CLI 来安装已在 `Gemfile` 中配置的 Ruby Gem。
**使用 `bundle` 从 CodeArtifact 存储库安装 Ruby Gem**
1. 如果还没有配置，请按照[使用 CodeArtifact 配置 RubyGems（`gem`）和 Bundler（`bundle`）](#configure-ruby-gem) 中的步骤将 `bundle` CLI 配置为通过适当的凭证来使用 CodeArtifact 存储库。
**注意**
生成的授权令牌有效期为 12 小时。如果自创建令牌以来已过去 12 小时，则需要创建一个新的令牌。
1. 将 CodeArtifact 存储库端点 URL 作为 `source` 添加到 `Gemfile`，以便从 CodeArtifact 存储库及其上游安装已配置的 Ruby Gem。
```
source "https://my_domain-111122223333.d.codeartifact.us-west-2.amazonaws.com/ruby/my_repo/"
gem 'my_ruby_gem'
```
1. 使用以下命令，按照 `Gemfile` 中的说明来安装 Ruby Gem：
```
bundle install
```
## 向 CodeArtifact 发布 Ruby Gem
按照以下步骤，使用 `gem` CLI 将 Ruby Gem 发布到 CodeArtifact 存储库。
1. 如果还没有配置，请按照[使用 CodeArtifact 配置 RubyGems（`gem`）和 Bundler（`bundle`）](#configure-ruby-gem) 中的步骤将 `gem` CLI 配置为通过适当的凭证来使用 CodeArtifact 存储库。
**注意**
生成的授权令牌有效期为 12 小时。如果自创建令牌以来已过去 12 小时，则需要创建一个新的令牌。
1. 使用以下命令将 Ruby Gem 发布到 CodeArtifact 存储库。请注意，如果未设置 `RUBYGEMS_HOST` 环境变量，则必须在 `--host` 选项中提供您的 CodeArtifact 存储库端点。
```
gem push --key codeartifact_api_key my_ruby_gem-0.0.1.gem
```
# RubyGems 命令支持
CodeArtifact 支持 `gem install` 和 `gem push` 命令。CodeArtifact 不支持以下 `gem` 命令：
+ `gem fetch`
+ `gem info --remote`
+ `gem list --remote`
+ `gem mirror`
+ `gem outdated`
+ `gem owner`
+ `gem query`
+ `gem search`
+ `gem signin`
+ `gem signout`
+ `gem sources --add`
+ `gem sources --update`
+ `gem specification --remote`
+ `gem update`
+ `gem yank`
# Bundler 兼容性
本指南包含有关 CodeArtifact 与 Bundler 兼容性的信息。
## Bundler 兼容性
AWS CodeArtifact 推荐 Bundler 2.4.11 或更高版本。如果在安装时遇到问题，请将 Bundler CLI 更新到最新版本。
### Bundler 版本支持
对于低于 2.4.11 的 Bundler 版本，在 Bundler 决定查询完整索引 `specs.4.8.gz` 之前，Gemfile 中可定义的依赖项上限为 500 个。由于 CodeArtifact 不支持完整索引，因此在使用低于 2.4.11 的 Bundler 版本时，CodeArtifact 不支持指定超过 500 个依赖项。
要使用 CodeArtifact 在 Gemfile 中定义超过 500 个依赖项，请将 Bundler 更新到 2.4.11 或更高版本。
### Bundler 操作支持
CodeArtifact 对 RubyGems 的支持不包括 Bundler Compact Index API（不支持 `/versions` API）。CodeArtifact 仅支持依赖项 API。
此外，CodeArtifact 不支持各种规范 API，例如 `specs.4.8.gz`。