Home Assistant IMAP 集成 `imap.fetch_part` 动作详解:提取邮件附件与 MIME 部件
Home Assistant IMAP 集成 imap.fetch_part 动作详解:提取邮件附件与 MIME 部件
导读
本文围绕 Home Assistant 官方文档仓库中的 imap.fetch_part 动作文档,系统讲解如何从 IMAP 服务器上的邮件中提取单个部件(如附件、文本或 HTML 正文),并与 imap_content 事件、imap.fetch 动作配合,构建"收件 → 提取附件 → 标记已读"的完整自动化流水线。读完本文,你将掌握 imap.fetch_part 的 UI 与 YAML 两种用法、全部参数(entry、uid、part)的取值来源、响应数据的字段语义,以及如何在后续步骤中通过响应变量消费附件内容。
动作概述:imap.fetch_part 是什么
imap.fetch_part 是 Home Assistant IMAP 集成 提供的动作(action),用于从 IMAP 服务器上的某封邮件中获取一个特定的部件(part)或附件。它的定位非常明确:
- 它不会拉取整封邮件,而是按部件索引精准提取某一块内容;
- 它典型的使用场景是:先用 imap.fetch 拿到邮件的部件元数据(
parts字典),再用imap.fetch_part按索引取回对应部件的实际内容; - 它同样可以直接消费
imap_content事件数据中的parts信息——事件本身已经携带了可用的部件索引。
该动作的返回结果存放在响应变量(response variable) 中,可在同一自动化或脚本的后续步骤中继续使用。这是它区别于普通"触发即忘"动作的关键特性。
与相关动作的关系
该文档在 front matter 中声明了三个关联动作,它们共同构成 IMAP 邮件事务处理的完整闭环:
| 动作 | 作用 | 文档位置 |
|---|---|---|
imap.fetch |
获取邮件纯文本正文与部件元数据(parts) |
imap.fetch |
imap.fetch_part |
按部件索引提取单个部件/附件的实际内容 | 本文 |
imap.seen |
将邮件标记为已读 | imap.seen |
imap.move |
将邮件移动到其他文件夹 | imap.move |
典型的执行链路是:imap_content 事件触发 → imap.fetch 获取正文与部件元数据 → imap.fetch_part 提取指定部件 → imap.seen 标记已读(或 imap.move 归档)。该链路在 IMAP 集成文档的 post-processing 示例 中有完整演示。
前置知识:imap_content 事件与部件索引
要正确使用 imap.fetch_part,必须先理解部件索引(part index)从何而来。根据 IMAP 集成文档,当新邮件到达时,集成会发送 event_type 为 imap_content 的自定义事件。事件数据(trigger.event.data)中包含一个 parts 字段,它是一个字典,每个键就是一个部件索引,可直接作为 imap.fetch_part 的 part 参数传入。
parts 字典中每个部件还附带元数据:content_type、content_transfer_encoding,以及附件特有的 filename。imap.fetch 文档给出了一个多部分(multipart)邮件的 parts 数据示例:
{
"0,0": {
"content_type": "text/plain",
"content_transfer_encoding": "7bit"
},
"0,1": {
"content_type": "text/html",
"content_transfer_encoding": "7bit"
},
"1": {
"content_type": "text/plain",
"filename": "Text attachment content.txt",
"content_transfer_encoding": "base64"
}
}
注意这里的索引格式:
0,0、0,1这类带逗号的嵌套索引,表示多部分结构中的层级路径(如multipart/alternative中的纯文本与 HTML 分支);1这类单段索引,表示顶层部件(这里是一个名为Text attachment content.txt的附件)。
在实际自动化中,通常先用模板判断某个部件是否存在、其类型是否符合预期,再调用 fetch_part。集成文档中的条件写法如下:
conditions:
- condition: template
value_template: "{{ trigger.event.data['parts'].get('1') }}"
- condition: template
value_template: "{{ trigger.event.data['parts']['1'].get('content_type') == 'text/plain' }}"
这保证了在部件不存在或类型不匹配时不会盲目执行提取动作。
在 UI 中使用 imap.fetch_part
该动作不支持 targets。在 UI 中,你不会被提示选择区域、设备、实体或标签,而是直接选择 IMAP 配置条目(config entry)。按照官方文档,配置步骤如下:
- 进入 Settings > Automations & scenes(自动化与场景);
- 打开一个已有的自动化或脚本,或选择 Create 新建一个;
- 新建自动化时,在 When 部分添加触发器(脚本不需要触发器);
- 在 Then do 部分选择 Add action(添加动作);
- 在搜索框中搜索并选择 IMAP: Fetch message part;
- 选择 Config entry(配置条目),提供消息 UID,并设置 Part 索引;
- 在 Response variable(响应变量)字段中输入一个名称来存储数据,例如
message_part; - 选择 Save 保存。
UI 选项一览
| UI 选项 | 说明 |
|---|---|
| Config entry | 保存该消息的 IMAP 配置条目 |
| UID | 要获取消息的 UID,可从该消息的事件数据中找到 |
| Part | 要获取的消息部件索引,使用消息事件数据或 Fetch message 动作返回的部件信息 |
在 YAML 中使用 imap.fetch_part
如果直接编写 YAML,或者想了解 Home Assistant 在底层到底做了什么,可以参照 yaml_header 中说明的字段级技术参考。在 YAML 中,该动作名称为 imap.fetch_part。官方示例:
action: |
action: imap.fetch_part
data:
entry: 91fadb3617c5a3ea692aeb62d92aa869
uid: "{{ trigger.event.data['uid'] }}"
part: "1"
response_variable: message_part
这个示例获取触发事件消息的部件 1,并将结果存入 message_part 响应变量。
YAML 参数详解
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
entry |
string | 是 | 保存该消息的 IMAP 配置条目的 ID。UI 模式下可从列表中选择条目;YAML 模式下需要自行查找条目 ID |
uid |
string | 是 | 要获取消息的 UID,可从该消息的事件数据中找到 |
part |
string | 是 | 要获取的消息部件索引,使用消息事件数据或 Fetch message 动作返回的部件信息 |
三个参数均为必填字符串类型。其中 uid 与 part 最常见的取值来源都是 trigger.event.data——也就是 imap_content 事件的载荷,这与 imap.fetch_part 文档中"从事件数据中查找"的说明一致。
完整实战示例:提取附件并标记已读
IMAP 集成文档中的 post-processing 示例给出了 imap.fetch_part 的完整用法——结合事件触发、条件过滤、提取部件、标记已读与通知:
alias: "imap fetch and seen example"
description: "Fetch and mark an incoming message as seen"
triggers:
- trigger: event
event_type: imap_content
event_data:
entry_id: 91fadb3617c5a3ea692aeb62d92aa869
conditions:
- condition: template
value_template: "{{ trigger.event.data['sender'] == 'info@example.com' }}"
- condition: template
value_template: "{{ trigger.event.data['parts'].get('1') }}"
- condition: template
value_template: "{{ trigger.event.data['parts']['1'].get('content_type') == 'text/plain' }}"
actions:
- action: imap.fetch_part
data:
entry: 91fadb3617c5a3ea692aeb62d92aa869
uid: "{{ trigger.event.data['uid'] }}"
part: "1"
response_variable: message_text
- action: imap.seen
data:
entry: 91fadb3617c5a3ea692aeb62d92aa869
uid: "{{ trigger.event.data['uid'] }}"
- action: persistent_notification.create
data:
message: "{{ message_text['part_data'] | base64_decode }}"
这段示例值得逐行拆解:
- 触发:监听
imap_content事件,并用event_data.entry_id过滤到指定的配置条目(当有多个 IMAP 条目时,这是避免误处理的关键,imap.seen 文档也专门强调了这一点); - 条件:先校验发送方,再确认部件
1存在且其content_type为text/plain,避免对不存在的部件调用动作; - 提取:调用
imap.fetch_part,uid与part均取自事件数据,结果存入message_text; - 已读:调用
imap.seen将同一邮件标记为已读; - 消费:用
persistent_notification.create发送通知,内容为message_text['part_data'] | base64_decode——注意part_data是编码后的数据,必须先通过base64_decode过滤器解码为可读文本。
响应数据结构
imap.fetch_part 的返回值存放在响应变量中,包含以下字段:
| 字段 | 说明 |
|---|---|
part_data |
获取到的消息部件的编码数据 |
content_type |
部件的 MIME 内容类型,例如 image/jpeg |
content_transfer_encoding |
part_data 中数据的编码方式 |
filename |
当部件是附件时的文件名;未设置文件名时为 null |
uid |
消息的 UID |
part |
部件索引 |
这些字段与事件数据中 parts 字典的元数据字段(content_type、content_transfer_encoding、filename)一一对应,只是补上了实际内容 part_data 与定位信息(uid、part)。
实战要点:part_data 与编码处理
part_data 是编码后的原始数据,不能直接当作文本使用。是否解码、如何解码,取决于 content_transfer_encoding:
- 编码为
base64(如前面的示例附件):使用 Jinja 过滤器{{ part_data | base64_decode }}解码; - 编码为
7bit或quoted-printable:通常已经是(或接近)可读文本,但处理前仍应确认编码方式。
对于二进制附件(如 content_type 为 image/jpeg、application/pdf 等),part_data 的解码产物是原始二进制字节,适合后续写入文件或进一步处理,而不是直接渲染为通知文本。判断附件类型时,应优先依赖响应中的 content_type 与 filename 字段。
响应变量机制与后续步骤消费
imap.fetch_part 与 imap.fetch 一样,属于返回结果的响应式动作。所谓响应变量,是指动作执行完成后,将返回数据挂载到 response_variable 指定的名字下,供同一自动化或脚本中的后续步骤通过模板引用。
例如在上面的完整示例中:
- 动作写入
response_variable: message_text; - 后续的
persistent_notification.create通过{{ message_text['part_data'] | base64_decode }}读取并解码数据。
这里有一个重要的使用边界:响应变量只在同一次自动化/脚本执行中有效,不能跨自动化读取。如果需要持久化,应把提取到的内容写入模板传感器、文件或其他可存储的实体。
该动作也支持通过 Settings > Tools > Actions(开发者工具)页面手动触发调试——参考 try_it 的说明,在动作搜索框中找到该动作、填写字段并执行 Perform action,即可在不写任何 YAML 的情况下观察实际返回结果。
进阶模式:把 imap.fetch_part 纳入邮件流水线
综合本文与 IMAP 集成文档 的内容,可以提炼出三种典型的实战模式:
1. 附件提取与通知(本文核心场景)
事件触发 → 校验 parts 元数据 → imap.fetch_part 提取 → base64_decode 解码 → 通知或存储。适用于发票、报表、验证码等邮件附件的自动提取。
2. 关键词识别(事件文本扫描)
IMAP 集成文档中的 keyword spotting 示例展示了另一条不依赖 fetch_part 的轻量路径:直接在模板传感器中对 trigger.event.data["subject"] 做关键词匹配。当只需要邮件主题级别的内容时,事件数据本身已够用,无需提取部件。
3. 自定义事件数据模板过滤
IMAP 集成文档还支持在配置中定义自定义事件数据模板(如 {{ "@example.com" in sender }}),渲染结果会作为 trigger.event.data["custom"] 附加到事件中。多个发件人的白名单过滤就是典型用法。配合 fetch_part 时,可以用 custom 字段先做粗过滤,减少不必要的部件提取。
使用限制与注意事项
- 不支持 targets:该动作没有区域、设备、实体或标签选择,只针对 IMAP 配置条目操作;
- 三个参数全部必填:
entry、uid、part缺一不可,且part与uid的取值必须与事件数据或imap.fetch返回的元数据严格一致; - 多配置条目场景务必过滤:存在多个 IMAP 配置条目时,应通过
entry_id过滤触发事件,避免 A 条目的动作误处理 B 条目的邮件; - 部件索引格式敏感:多部分邮件的索引可能形如
0,0、0,1,提取前建议用模板条件确认部件存在与类型匹配; part_data为编码数据:使用前需根据content_transfer_encoding决定是否解码、如何解码。
延伸阅读
- IMAP 集成文档:配置流程、
imap_content事件数据字段、IMAP 搜索语法与排错指南; - imap.fetch 动作:获取正文与部件元数据,是
imap.fetch_part的前置步骤; - imap.seen 动作:将邮件标记为已读,可与提取动作串联;
- imap.move 动作:移动邮件到其他文件夹并可选标记已读;
- imap.delete 动作:删除邮件(
imap.seen文档中列出的关联动作)。