Home Assistant IMAP 集成 `imap.fetch_part` 动作详解:提取邮件附件与 MIME 部件

原创2026-09-16 14:28:161,833 阅读
文章标签:文档教程智能家居

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)。按照官方文档,配置步骤如下:

  1. 进入 Settings > Automations & scenes(自动化与场景);
  2. 打开一个已有的自动化或脚本,或选择 Create 新建一个;
  3. 新建自动化时,在 When 部分添加触发器(脚本不需要触发器);
  4. 在 Then do 部分选择 Add action(添加动作);
  5. 在搜索框中搜索并选择 IMAP: Fetch message part;
  6. 选择 Config entry(配置条目),提供消息 UID,并设置 Part 索引;
  7. 在 Response variable(响应变量)字段中输入一个名称来存储数据,例如 message_part;
  8. 选择 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 }}"

这段示例值得逐行拆解:

  1. 触发:监听 imap_content 事件,并用 event_data.entry_id 过滤到指定的配置条目(当有多个 IMAP 条目时,这是避免误处理的关键,imap.seen 文档也专门强调了这一点);
  2. 条件:先校验发送方,再确认部件 1 存在且其 content_type 为 text/plain,避免对不存在的部件调用动作;
  3. 提取:调用 imap.fetch_part,uid 与 part 均取自事件数据,结果存入 message_text;
  4. 已读:调用 imap.seen 将同一邮件标记为已读;
  5. 消费:用 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 文档中列出的关联动作)。
登录后查看全文
home-assistant.io