您正在从您的应用程序发送消息，并且需要记住该消息属于哪个营销活动，或者将日历事件关联回您自己数据库中的订单。显而易见的方法是建立一个单独的表，将奈拉斯（Nylas）标识符映射到您的记录，这意味着每次读取时都需要进行连接操作，并需保持同步以确保数据最新。有一种更轻量级的方法：将您自己的数据作为元数据直接附加到对象上，然后稍后通过它来过滤对象。您的营销活动标识符会随消息一同传输，只需一次查询即可拉取该营销活动中的所有消息。本文介绍了如何使用应用程序接口（API）和命令行界面（CLI）为对象添加标签。
这是一个实际的使用案例，而非单纯的端点浏览，我们从两个角度探讨元数据：您的后端调用的超文本传输协议（HTTP）应用程序接口（API），以及用于从终端设置和读取元数据的nylas 命令行界面（CLI）。我负责命令行界面（CLI）的工作，因此下面的命令是当我想要标记已发送消息并再次找到它时所常用的命令。
什么是元数据及其存储位置
元数据是您附加到奈拉斯（Nylas）对象上的自定义键值对字段，支持消息、草稿、事件和日历。值为字符串，单个对象上最多可存储 50 个键值对，每个值最多可容纳 500 个字符。这足以容纳营销活动缩略名、外部记录标识符、工作流状态以及任何将对象关联回您应用程序的其他信息，所有这些都直接承载在对象本身上，而不是存储在侧表中。
元数据的目的在于避免使用那种侧表。您无需将奈拉斯（Nylas）消息标识符映射到数据库中的行并在每次读取时进行连接，而是将应用程序的数据放在消息上并直接读回。从您的应用程序角度来看，对象变得具有自描述性，因此消息所属的营销活动或事件对应的订单会随着对象在每次返回它的应用程序接口（API）调用中一同传输。对于较小且您需要按其过滤的应用程序数据，这比维护一个并行存储更简单。
决定您架构的五键规则
这是关于元数据最需要理解的一点，忽略它会导致无法查询的标签方案。您可以存储多达 50 个键值对，但只有五个键（字面命名为 key1 到 key5）是被索引且可过滤的。您设置的任何其他键都会与对象一起存储和返回，但您无法对其进行过滤。因此，您计划用于查询的键必须位于 key1 到 key5 中。
这影响了您设计标签的方式。您将搜索的值（如营销活动标识符、工作流状态、租户）放入这五个被索引的键中，并预先确定这种映射关系：key1 代表营销活动，key2 代表运行实例，依此类推。其他所有数据（您希望携带但从不用于过滤的数据）可以使用描述性的键名，并作为其余 45 个键值对一同传输。如果搞反了，将可过滤的概念放在自由格式的键中，您虽然存储了数据，却无法构建查询它的方法，这通常会在 later 阶段显现出来，即您需要的过滤器静默地返回空结果。
在发送时设置元数据
您可以通过在请求中添加一个 metadata 对象，在创建时附加元数据。在 POST /messages/send 请求中，metadata 对象将您的键值对与消息的其余部分一起携带，并将它们存储在生成的消息上，以便后续检索和过滤。
