boto 的 AWS Support 接口实战指南：用 Python 编程化管理与查询支持工单

• 后端
• 云原生

AWS Support（AWS 支持中心）不仅可以在控制台网页中人工提交、跟进工单（Case），还通过 AWS Support API 暴露了一套完整的编程接口。boto 在boto.support模块中封装了这一服务，让开发者可以用 Python 直接创建支持工单、查询已有工单、追加沟通内容、拉取沟通记录并关闭（解决）工单，还能调用 Trusted Advisor 检查相关操作。本文以仓库中的官方教程 docs/source/support_tut.rst 为主线，结合boto.support.layer1.SupportConnection的真实实现（boto/support/layer1.py），完整演示从建立连接到工单全生命周期的编程化操作，并剖析其底层 JSON 协议与异常处理机制。读完本文，你将能够在自己的运维脚本、告警自动化或内部工单系统中直接对接 AWS Support 服务。

一、建立到 AWS Support 的连接

访问 AWS Support 的第一步是创建到服务的连接对象。boto 提供了两种方式，最终都得到boto.support.layer1.SupportConnection实例（该教程假设你已安装好 boto）。

方式一：显式传入凭证

>>> from boto.support.connection import SupportConnection >>> conn = SupportConnection('<aws access key>', '<aws secret key>')

变量conn此时指向一个SupportConnection对象，AWS Access Key 和 AWS Secret Key 被显式传入构造函数。

方式二：使用环境变量

同样可以预先设置两个环境变量，然后无参数调用构造函数：

AWS_ACCESS_KEY_ID你的 AWS Access Key ID

AWS_SECRET_ACCESS_KEY你的 AWS Secret Access Key

>>> conn = SupportConnection()

方式三：区域快捷函数

boto 还提供了便捷函数boto.support.connect_to_region，一条语句即可完成连接：

>>> import boto.support >>> conn = boto.support.connect_to_region('us-west-2')

从源码看，该快捷函数定义在 boto/support/init.py，内部委托给boto.regioninfo.connect('support', region_name, connection_cls=SupportConnection)，最终仍然返回SupportConnection实例；同模块还提供regions()用于获取全部可用区域。需要留意的是，SupportConnection的类级默认值定义在 boto/support/layer1.py：DefaultRegionName = "us-east-1"、DefaultRegionEndpoint = "support.us-east-1.amazonaws.com"；同时仓库的端点数据 boto/endpoints.json 中support服务仅列出了us-east-1这一个端点。因此教程中的us-west-2示例可按需使用，但若未配置区域，默认会落到us-east-1，这也是最稳妥的选择。

无论采用哪种方式，接下来的所有工单操作都围绕这个conn对象展开。

二、查询已有工单：describe_cases

如果你已有存量工单，或需要定期拉取新工单，使用SupportConnection.describe_cases方法。不传参数时返回当前账号下的工单列表：

>>> cases = conn.describe_cases() >>> len(cases['cases']) 1 >>> cases['cases'][0]['title'] 'A test case.' >>> cases['cases'][0]['caseId'] 'case-...'

也可以传入case_id_list精确获取一个或多个工单：

>>> cases = conn.describe_cases(case_id_list=['case-1']) >>> len(cases['cases']) 1 >>> cases['cases'][0]['title'] 'A test case.' >>> cases['cases'][0]['caseId'] 'case-...'

源码层面的参数远比教程示例丰富。对照 boto/support/layer1.py 中describe_cases的签名，它实际上支持以下过滤与分页参数，教程只演示了case_id_list，其余参数全部可组合使用：

需要注意，工单数据在创建后 12 个月内可用，超过 12 个月后再请求相关数据可能出错。返回值是 JSON 格式，包含一个或多个CaseDetails数据类型，以及用于分页的NextToken值。

三、获取服务代码：describe_services

创建新工单前，必须先从服务中取回可用的服务代码（及类别代码）。一次简单调用即可：

>>> services = conn.describe_services() >>> services['services'][0]['code'] 'amazon-cloudsearch'

如果你只关心部分服务，可以传入服务代码列表进行过滤：

>>> service_details = conn.describe_services(service_code_list=[ ... 'amazon-cloudsearch', ... 'amazon-dynamodb', ... ])

根据 boto/support/layer1.py 的 docstring，describe_services返回当前 AWS 服务列表以及每个服务适用的服务类别列表，它们将用于CreateCase请求。需要注意：服务代码/类别代码与 AWS Support Center「Open a new case」页面的「Service」「Category」下拉框展示值并不一定一致，务必始终使用编程方式取得的代码，这样才能保证拿到最新、最准确的值。该方法同样支持language参数。

四、获取严重级别：describe_severity_levels

创建新工单还需要严重级别代码。获取方式同样简单：

>>> severities = conn.describe_severity_levels() >>> severities['severityLevels'][0]['code'] 'low'

严重级别标识工单的紧急程度，它直接决定 AWS 依据你的 SLA 给出的响应时间。该方法同样支持可选的language参数。

五、创建新工单：create_case

拿到服务代码、类别代码和严重级别代码后，就可以创建工单了：

>>> new_case = conn.create_case( ... subject='This is a test case.', ... service_code='', ... category_code='', ... communication_body="", ... severity_code='low' ... ) >>> new_case['caseId'] 'case-...'

其中：

• service_code/category_code：先调用describe_services，再从响应中为该服务挑选合适的服务代码（以及该服务内对应的类别代码）；
• severity_code：先调用describe_severity_levels，再从响应中选择合适的严重级别代码。

实际调用时请用上面两个查询接口返回的真实代码替换示例中的空字符串。

对照 boto/support/layer1.py 中create_case的完整签名（subject, communication_body为必填参数），它还支持一批可选参数，足以覆盖 AWS Support Center「Open a new case」页面的大部分字段：

创建成功后返回 AWS Support 工单号，该工单号随后可被describe_cases等操作使用。

六、向工单追加沟通：add_communication_to_case

支持工单的本质是来回沟通，因此可以向已有工单追加新的沟通内容：

>>> result = conn.add_communication_to_case( ... communication_body="This is a followup. It's working now.", ... case_id='case-...' ... )

对照 boto/support/layer1.py，add_communication_to_case的完整签名为(communication_body, case_id=None, cc_email_addresses=None, attachment_set_id=None)：communication_body为必填的邮件正文；case_id标识要追加沟通的目标工单；cc_email_addresses指定邮件抄送地址列表；attachment_set_id为要随沟通附加的附件集合 ID（该集合需先通过AddAttachmentsToSet创建）。响应直接指示本次请求成功或失败。

七、拉取工单全部沟通：describe_communications

获取某个工单的全部沟通记录（含附件信息）只需传入工单 ID：

>>> communications = conn.describe_communications('case-...')

源码签名比教程展示的多出四个可选参数：before_time、after_time（按日期过滤，工单沟通数据在创建后 12 个月内可用）、next_token与max_results（控制分页，max_results设置每页显示条数，next_token指定分页续传点）。

八、解决（关闭）工单：resolve_case

工单处理完毕后，应将其标记为已解决以正式关闭：

>>> closed = conn.resolve_case(case_id='case-...') >>> closed['result'] True

resolve_case接收case_id并返回工单在调用前与调用后的状态（调用完成后的状态）——响应中的result为True表示解决成功。

九、底层实现剖析：JSON 协议、认证与异常

以上所有操作都通过 boto/support/layer1.py 中的SupportConnection完成。该类继承自boto.connection.AWSQueryConnection，但按 AWS Support API 的实际要求走 JSON 协议，类级常量定义如下：

• APIVersion = "2013-04-15"
• DefaultRegionName = "us-east-1"，DefaultRegionEndpoint = "support.us-east-1.amazonaws.com"
• ServiceName = "Support"，TargetPrefix = "AWSSupport_20130415"
• _required_auth_capability()返回['hmac-v4']，即所有请求使用 AWS Signature Version 4 签名（源码 docstring 亦注明该服务采用「Signature Version 4 Signing Process」进行认证）

所有请求最终汇聚到make_request(action, body)：它构造X-Amz-Target: AWSSupport_20130415.<Action>头，以Content-Type: application/x-amz-json-1.1发送 POST 到/，并把各方法的 Python 参数按驼峰命名（如caseIdList、communicationBody、serviceCodeList）序列化为 JSON。响应为 200 时直接json.loads返回字典；非 200 时解析响应中的__type字段并抛出对应异常。

异常体系

_faults映射表把服务端返回的错误类型映射到 boto/support/exceptions.py 中定义的异常类，这些类全部继承自boto.exception.JSONResponseError：

• CaseIdNotFound：工单 ID 不存在
• CaseCreationLimitExceeded：超出工单创建配额
• AttachmentLimitExceeded、DescribeAttachmentLimitExceeded、AttachmentSetIdNotFound、AttachmentSetExpired、AttachmentIdNotFound、AttachmentSetSizeLimitExceeded：附件相关错误
• InternalServerError：服务端内部错误

未被映射的错误类型则回退到JSONResponseError本身抛出，便于统一捕获处理。

十、进阶：附件与 Trusted Advisor

教程聚焦于工单生命周期，而SupportConnection还封装了两组进阶能力（实现与 docstring 均在 boto/support/layer1.py），可作为后续自动化扩展方向：

附件相关操作

• add_attachments_to_set(attachments, attachment_set_id=None)：向附件集合添加附件；不传集合 ID 时新建集合。一个集合最多 3 个附件，单个附件最大 5 MB，集合自创建起有效 1 小时（响应中的ExpiryTime标明过期时间）。
• describe_attachment(attachment_id)：按附件 ID 取回附件内容，附件 ID 由DescribeCommunications返回的AttachmentDetails对象给出。

Trusted Advisor 操作

• describe_trusted_advisor_checks(language)：列出全部检查项（名称、ID、类别、描述、元数据），语言必填；
• describe_trusted_advisor_check_result(check_id, language=None)：获取指定检查的结果，响应含TrustedAdvisorCategorySpecificSummary、TrustedAdvisorResourceDetail、TrustedAdvisorResourcesSummary三类对象，以及Status（ok/warning/error/not_available）、Timestamp、CheckId字段；
• describe_trusted_advisor_check_summaries(check_ids)：获取一个或多个检查的汇总结果；
• describe_trusted_advisor_check_refresh_statuses(check_ids)：查询检查的刷新状态；
• refresh_trusted_advisor_check(check_id)：请求重新执行指定检查，响应含Status（none/enqueued/processing/success/abandoned）、MillisUntilNextRefreshable、CheckId。

借助这些接口，你可以把 AWS Support 的工单管理与 Trusted Advisor 检查结果一并接入自己的监控与运维流程。

参考文档与代码索引

• 教程原文：docs/source/support_tut.rst
• API 参考文档（autodoc）：docs/source/ref/support.rst
• 核心实现SupportConnection：boto/support/layer1.py
• 区域与快捷连接函数：boto/support/init.py
• 异常定义：boto/support/exceptions.py
• 服务端点数据：boto/endpoints.json

• 后端
• 云原生