企业官网建设流程全解析

AWS CLI Chime search-available-phone-numbers 命令实战：号码检索、筛选参数与 E.164 输出解析

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

aws chime search-available-phone-numbers是 Amazon Chime 命令行工具中用于检索可订购电话号码的核心命令，它在 AWS CLI 仓库中的命令定义位于 awscli/botocore/data/chime/2018-05-01/service-2.json，其官方示例文档为 awscli/examples/chime/search-available-phone-numbers.rst。本文以该示例文档为主线，结合命令的底层 API 模型、参数约束与响应结构，系统讲解如何按区号、城市、州、免费前缀等多种条件检索号码，并正确理解返回的 E.164 格式结果，帮助你在 Chime 号码订购流程中准确完成前置查询。

命令概览：一次按区号检索可用号码的完整实践

官方示例 awscli/examples/chime/search-available-phone-numbers.rst 给出了最基本的用法——按美国区号（Area Code）检索可用号码：

aws chime search-available-phone-numbers \ --area-code "206"

命令执行后返回所有匹配条件的可用号码列表，输出结构如下：

{ "E164PhoneNumbers": [ "+12065550100", "+12065550101", "+12065550102", "+12065550103", "+12065550104", "+12065550105", "+12065550106", "+12065550107", "+12065550108", "+12065550109", ] }

从这个示例可以总结出三个关键事实：

1. 入参方式：区号通过--area-code参数传入，CLI 会将其映射为 HTTP GET 请求的area-code查询字符串参数（见 service-2.json 中AreaCode成员的location: "querystring"、locationName: "area-code"定义）。
2. 返回格式：响应体只有一个成员E164PhoneNumbers，即符合 E.164 国际电话号码标准的号码列表。
3. 服务端语义：该 API 的完整描述位于服务模型 service-2.json，明确指出本操作是"检索可以订购（ordered）的电话号码"——也就是说，search-available-phone-numbers是号码订购前的查询环节，检索到的号码随后可用于order-phone-number等订购操作。

参数详解：从 CLI 参数到服务端请求的完整映射

从服务模型 service-2.json 可以看到，SearchAvailablePhoneNumbers操作共支持 7 个请求成员，它们全部通过 URL 查询字符串（querystring）传递。下面是完整的参数对照表：

参数约束要点（源自服务模型的强约束）

• 美国号码的筛选规则：服务模型明确规定，对于美国号码必须提供以下筛选条件中的至少一个：AreaCode、City、State或TollFreePrefix（见 service-2.json）。同时，City与State是成对出现的——如果提供City，则State为必填。
• 非美国号码的强制要求：美国以外的号码只支持PhoneNumberType筛选，且必须提供该参数。也就是说，检索非美国号码时不能使用区号、城市等美国专属筛选器。
• --toll-free-prefix的格式约束：免费前缀的模型定义（见 service-2.json）要求长度为恰好 3 位，且正则匹配^8(00|33|44|55|66|77|88)$，即只能取 800、833、844、855、866、877、888 中的一种。
• --country的格式约束：国家代码必须是大写双字母，匹配正则[A-Z]{2}（ISO 3166-1 alpha-2 规范，见 service-2.json）。
• --max-results的取值范围：模型规定为 1 到 500 之间的整数（见 service-2.json），超出范围会触发客户端参数校验错误。

参数组合示例

按州检索（美国）：

aws chime search-available-phone-numbers \ --state "WA"

按城市 + 州组合检索（城市必须搭配州使用）：

aws chime search-available-phone-numbers \ --city "Seattle" \ --state "WA"

按免费号码前缀检索（前缀只能是 800/833/844/855/866/877/888）：

aws chime search-available-phone-numbers \ --toll-free-prefix "800"

检索非美国号码（必须指定号码类型，此处检索加拿大的本地号码）：

aws chime search-available-phone-numbers \ --country "CA" \ --phone-number-type "Local"

限制返回条数：

aws chime search-available-phone-numbers \ --area-code "206" \ --max-results 20

响应结构解析：E.164 格式号码列表

响应模型定义在 service-2.json，SearchAvailablePhoneNumbersResponse仅包含一个成员E164PhoneNumbers，类型为E164PhoneNumberList（字符串列表）。

每个号码的底层类型为E164PhoneNumber，其定义见 service-2.json：

• 格式正则：^\+?[1-9]\d{1,14}$，即可选+号开头，首位数字 1~9，总长度为 1~15 位——这完全符合 E.164 国际电话编号规范。
• 敏感标记：该字段被标记为"sensitive": true，这意味着 AWS CLI 在输出处理、日志记录等场景中会将其视为敏感数据对待。

对照示例输出中的+12065550100：+1为美国国家代码，206即查询时传入的区号，5550100为本地号码段。理解这个结构，有助于你在拿到查询结果后直接解析、筛选或批量记录可用号码。

分页机制：用 NextToken 遍历全部结果

当检索结果数量较大时，单次调用可能无法返回全部号码。服务模型提供了两个分页配套参数（见 service-2.json）：

• --max-results：控制单次调用返回的最大结果数（1~500）。
• --next-token：服务端返回的令牌，用于获取下一页结果。

对应的手工分页流程为：首次调用不带--next-token获取第一页；如果结果未取完，将响应中携带的令牌传入下一次调用的--next-token参数，循环直至取完所有结果。

由于 AWS CLI 内置了 botocore 的分页器（pagination）机制，对于已声明分页器的操作，你还可以直接使用--page-size与--max-items参数让 CLI 自动完成分页。需要说明的是，当前仓库中 Chime 服务的分页器定义（awscli/botocore/data/chime/2018-05-01/paginators-1.json）未包含SearchAvailablePhoneNumbers操作，因此从仓库中的服务模型看，该命令目前无法借助 CLI 内置分页器自动翻页，需要依赖--next-token手动分页。如果你使用较新的 AWS CLI 版本，建议通过aws chime search-available-phone-numbers help查看当前安装版本的参数列表以确认是否支持分页器参数。

异常处理：理解可能返回的错误

服务模型 service-2.json 为SearchAvailablePhoneNumbers声明了 7 种可能的异常，覆盖了绝大多数请求失败场景：

使用该命令前，请确保你的 IAM 身份已获得 Chime 相关号码操作的权限（如chime:SearchAvailablePhoneNumbers），否则会触发AccessDeniedException或ForbiddenException；高频批量调用时注意控制速率，避免触发ThrottledClientException。

应用场景与总结

search-available-phone-numbers命令在整个 Chime 电话号码生命周期中扮演"号码选型"的角色：先在订购前查询可用的号码池，再结合后续的号码订购、分配操作完成落地。结合本仓库的命令定义，可归纳出以下实战要点：

1. 美国号码必须提供AreaCode、City、State、TollFreePrefix中至少一个筛选条件，City与State必须成对出现；
2. 非美国号码必须提供PhoneNumberType（Local或TollFree）且无法使用美国专属筛选器；
3. 免费前缀仅支持800/833/844/855/866/877/888三种字符格式；
4. 返回结果均为 E.164 格式字符串（可选+号、1~15 位数字），且被服务模型标记为敏感字段；
5. 大批量结果需使用--next-token手动分页，单次最多返回 500 条。

如需验证或深入研究，可进一步查阅命令的 API 模型定义 awscli/botocore/data/chime/2018-05-01/service-2.json 与请求/响应结构定义（L3556-L3615），或运行aws chime search-available-phone-numbers help查看当前环境下的完整参数文档。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli