示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载本篇技术指南围绕aws-doc-sdk-examples仓库中 SES v2 周报邮件Coupon Newsletter场景的核心 API ——ListContacts展开完整讲解其请求语法、URI 参数、请求体过滤条件、响应结构与分页机制并结合仓库内 Python / Rust / Java / .NET 多语言实现帮助开发者理解如何在实际订阅列表中拉取联系人并驱动批量模板邮件发送。读完本文你将掌握ListContacts的完整调用细节、参数语义、错误处理与多语言落地方式可以直接照搬到自己的订阅管理类业务中。一、场景定位ListContacts 在周报邮件流程中的角色ListContacts是 Amazon Simple Email Service (SES) v2 API 中用于列出指定联系人列表Contact List内全部联系人的操作。在本仓库的周报优惠券邮件场景中它是发送阶段的前置关键步骤订阅者通过CreateContact加入weekly-coupons-newsletter联系人列表后程序必须先调用ListContacts取回所有订阅者邮箱地址再对每个地址逐一执行模板化SendEmail详见 场景 README 与 场景规范。完整流程可概括为四步准备应用创建验证邮箱身份CreateEmailIdentity、创建联系人列表CreateContactList、创建邮件模板CreateEmailTemplate。收集订阅者允许用户输入基础邮箱地址通过子地址扩展subaddress / plus addressing即userses-weekly-newsletter-1example.com这类形式生成 3 个变体分别调用CreateContact添加联系人并发送欢迎邮件SendEmailSimple 格式。发送周报调用ListContacts获取weekly-coupons-newsletter列表中的全部联系人再对每个邮箱单独调用SendEmailTemplate 格式并通过ListManagementOptions指定联系人列表使 SES 自动注入退订链接与退订头{{amazonSESUnsubscribeUrl}}。监控与清理在控制台查看发送指标最后依次删除模板、联系人列表可选与邮箱身份。ListContacts位于第 3 步入口其返回结果直接决定了要发送的收件人集合。该 API 的完整参考文档见 content/10_ListContacts.md本文即以其为骨架展开。二、请求语法HTTP 方法与路径构造ListContacts是一个 HTTPGET请求完整请求语法如下来自关联文档GET /v2/email/contact-lists/{ContactListName}/contacts?NextToken{NextToken}PageSize{PageSize} HTTP/1.1 Content-type: application/json { Filter: { FilteredStatus: string, TopicFilter: { TopicName: string, UseDefaultIfPreferenceUnavailable: boolean } } }要点说明HTTP 方法GET用于读取联系人列表内容不会产生副作用。请求路径/v2/email/contact-lists/{ContactListName}/contactsContactListName是路径中的必填占位参数。查询字符串NextToken与PageSize作为查询参数附加在路径之后用于控制分页。请求体虽然方法是GET但该操作允许通过 JSON 请求体携带可选过滤条件FilterContent-type为application/json。三、URI 请求参数详解关联文档明确规定了以下三个 URI 参数参数必填类型说明ContactListName是String要查询的联系人列表名称。若传入不存在的名称服务端将抛出NotFoundException。NextToken否String分页令牌字符串。当响应中存在更多联系人时服务端会在上一次响应的NextToken字段返回令牌将其原样带入下一次ListContacts调用保持其余参数一致即可获取下一页联系人。PageSize否Integer单次调用最多返回的联系人数量。具体返回条数取决于列表中联系人总数与PageSize的对比关系如果实际联系人数量多于该值响应会附带NextToken调用方需携带该令牌继续请求以取回剩余联系人。实际使用时建议总是按分页循环消费结果而不是假设一次调用就能返回全部联系人——当列表增长后缺少分页处理会导致数据不完整。四、请求体Filter 过滤条件请求体仅接受一个可选字段Filter类型为ListContactsFilter_object用于对联系人集合进行过滤FilteredStatusString可选按订阅状态过滤联系人。该字段取自联系人对象上的订阅状态枚举值如订阅、退订、待处理等用于仅筛选处于指定订阅状态的联系人。TopicFilter对象可选按话题Topic偏好过滤联系人其内部包含两个字段TopicNameString可选要按之过滤的话题名称。只有当联系人在该话题上存在偏好记录时才会被匹配返回。UseDefaultIfPreferenceUnavailableBoolean可选当联系人没有针对该话题的显式偏好时是否回退使用默认偏好参与过滤判断。Filter是可选的不传该字段即返回列表中全部联系人受PageSize分页约束。周报场景中的 Python 实现正是不带过滤条件、仅按ContactListName查询的典型用法见下文源码分析。五、响应结构与响应元素成功时服务端返回HTTP 200响应体 JSON 结构如下{ Contacts: [ { EmailAddress: string, LastUpdatedTimestamp: number, TopicDefaultPreferences: [ { SubscriptionStatus: string, TopicName: string } ], TopicPreferences: [ { SubscriptionStatus: string, TopicName: string } ], UnsubscribeAll: boolean } ], NextToken: string }响应包含两个顶层字段Contacts当前页返回的联系人对象数组Array of Contact_objects。每个联系人对象包含EmailAddressString联系人邮箱地址是后续SendEmail的收件人取值来源。LastUpdatedTimestampNumber联系人信息的最后更新时间戳。TopicDefaultPreferences数组联系人针对各话题的默认订阅偏好每项含SubscriptionStatusString与TopicNameString。TopicPreferences数组联系人针对各话题的实际订阅偏好结构与TopicDefaultPreferences相同。UnsubscribeAllBoolean是否已对所有话题执行全局退订。NextTokenString若存在更多联系人可分页获取此字段返回分页令牌将其复制到后续相同参数的ListContacts调用中即可取下一页。若没有更多数据该字段为空。六、分页机制PageSize 与 NextToken 的配合关联文档对分页给出了明确的行为约定首次调用时设置PageSize指定单页上限若列表联系人数量超过该值服务端在响应中携带NextToken。后续调用时将上一次响应的NextToken原样传入查询参数并保持其余参数ContactListName、PageSize、Filter与首次调用完全一致才能正确连续翻页。当响应中不再返回NextToken或Contacts为空时说明已遍历完所有联系人。这一令牌式分页设计意味着调用方应使用while循环或分页器Paginator来聚合全部联系人而不是假定单次响应即完整数据。七、错误处理关联文档声明的异常集合关联文档列出了ListContacts可能抛出的错误异常HTTP 状态码含义BadRequestException400输入无效例如非法的ContactListName、PageSize或Filter取值。NotFoundException404访问的资源不存在如指定的联系人列表不存在。TooManyRequestsException429对同一操作发起了过多请求触发了限流。此外所有 SES v2 操作还共享一组通用错误Common Errors本文不展开。在实际业务代码中NotFoundException是最常见且必须显式处理的异常——它通常意味着联系人列表尚未创建或被误删。八、源码级实现多语言调用印证1. Pythonsesv2客户端直调 逐联系人发信场景的 Python 实现位于 newsletter.pysend_coupon_newsletter方法中的核心调用片段约 198-229 行如下# 获取联系人列表 try: contacts_response self.ses_client.list_contacts( ContactListNameCONTACT_LIST_NAME ) except ClientError as e: if e.response[Error][Code] NotFoundException: print(fContact list {CONTACT_LIST_NAME} does not exist.) return else: raise e # 向每个联系人发送周报模板邮件 coupon_items load_file_content(sample_coupons.json) for contact in contacts_response[Contacts]: email_address contact[EmailAddress] self.ses_client.send_email( FromEmailAddressself.verified_email, Destination{ToAddresses: [email_address]}, Content{ Template: { TemplateName: TEMPLATE_NAME, TemplateData: coupon_items, } }, ListManagementOptions{ContactListName: CONTACT_LIST_NAME}, )从源码可以确认三个关键实践只传必填参数list_contacts仅传入ContactListName未使用分页参数与Filter属于小列表场景的简洁写法若列表规模增长应补充PageSize/NextToken循环。错误分支对NotFoundException单独捕获并友好提示后返回其余ClientError直接上抛。响应字段消费从contacts_response[Contacts]中逐项读取EmailAddress作为Destination.ToAddresses的唯一收件人——这正对应关联文档响应结构中的Contacts[].EmailAddress字段同时保证了每封邮件独立发送便于退订追踪。2. Rustlist_contacts()链式调用Rust 实现位于 newsletter.rs约 241-247 行同样采用先取列表、再逐个发信的模式let contacts self .client .list_contacts() .contact_list_name(CONTACT_LIST_NAME) .send() .await?; // 将 contacts 收集后逐项发送... let contacts match self.client.list_contacts().send().await { Ok(list_contacts_output) { list_contacts_output.contacts.unwrap().into_iter().collect() } ... };Rust 侧将contacts从响应中unwrap并收集为迭代集合随后逐项处理。仓库还提供了独立的命令行示例 bin/list-contacts.rs 供快速验证 API 行为。3. Java / .NET同一操作的不同 SDK 形态按 71_metadata.md 中的代码片段标签约定各语言实现均以sesv2.{Action}命名规范对齐JavaSDK v2代码位于 javav2/example_code/ses片段标签为sesv2.java2.newsletter.ListContacts。PythonSDK v3片段标签为python.example_code.sesv2.ListContacts即上文引用的list_contacts调用。RustSDK v1片段标签为sesv2.rust.list-contacts。.NET 实现见 dotnetv3/SESv2/README.md。无论使用哪种语言请求/响应语义均与关联文档保持一致名称参数必填、响应以Contacts数组承载结果、NextToken承担分页续接职责。4. 测试验证仓库为场景提供了自动化测试。Python 侧测试见 newsletter_test.pyRust 侧测试见 tests/test_newsletter.rs。这些测试通过 mock 或集成方式校验list_contacts的调用参数与错误分支可用于验证上述调用形态的正确性。九、实战小结ListContacts 最佳实践清单结合关联文档、场景规范与多语言源码ListContacts的工程落地建议如下必填校验调用前确认ContactListName已存在或对NotFoundException做幂等处理场景规范中该错误属于失败场景并提示用户的级别。分页必做生产环境列表可能超过单页上限务必使用NextToken循环拉取关联文档强调后续调用需携带相同参数否则翻页会错乱。按需过滤若业务需要区分订阅状态或话题偏好通过请求体Filter的FilteredStatus与TopicFilter提前裁剪数据减少下游发信量。逐人发信周报场景要求每个联系人独立调用SendEmail配ListManagementOptions注入退订信息因此ListContacts返回的EmailAddress应逐条消费而非合并批量发送。限流感知发送阶段场景代码在沙箱环境下会在邮件之间休眠约 2 秒Python 实现中为sleep(1.1)以规避TooManyRequestsException读取联系人阶段若遇到 429也应实现重试或降频策略。综上所述ListContacts虽是一个结构简单的GET操作但它的分页令牌、过滤条件与响应字段直接决定了订阅型邮件系统的数据完整性与发送准确性。通过本文对关联文档的逐项拆解和仓库源码的对照印证读者可以快速将其集成进自己的 SES v2 工作流中。Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0赞分享示例工程教程后端【免费下载链接】aws-doc-sdk-examplesWelcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.项目地址https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples点击查看免费下载相关推荐使用 Amazon SES v2 CreateContactList API 创建联系列表语法、参数与 Weekly Mailer 场景实战使用 Amazon SES v2 CreateContactList API 创建联系列表语法、参数与 Weekly Mailer 场景实战 导读 本文围绕示例工程教程后端使用 AWS SDK for .NET 构建 Amazon SES v2 优惠券新闻邮件工作流从联系人列表到模板化群发使用 AWS SDK for .NET 构建 Amazon SES v2 优惠券新闻邮件工作流从联系人列表到模板化群发 Amazon SES v2 API 是示例工程教程后端AWS SDK for Go V2 操作 Amazon DynamoDB 实战指南表基础操作、PartiQL 单条与批量查询场景AWS SDK for Go V2 操作 Amazon DynamoDB 实战指南表基础操作、PartiQL 单条与批量查询场景 本文以 aws doc sd示例工程教程后端上一篇深入理解Nginx Stream模块中的server_name与SSL关系下一篇SDXL-VAE-FP16-Fix终极指南解决AI绘图NaN问题的完整方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考