当用户打开可操作消息时刷新它

项目
04/29/2024

重要

由于服务升级，具有全局范围的新可操作消息提供程序的加入将暂时暂停到 2024 年 6 月 30 日。现有的全球范围提供程序以及组织和测试范围提供程序的加入不受影响。有关详细信息，请参阅可操作消息的常见问题解答。

可操作邮件允许用户对电子邮件执行快速操作，通常基于卡中显示的数据。但是，在发送可操作消息后，数据有时会更改。例如，你的服务可能会向多个审批者发送可操作的消息，要求他们批准或拒绝请求。一个审批者批准请求，但另一个审批者邮箱中的可操作邮件仍要求批准。现在，使用 autoInvokeAction 可操作邮件上的属性，你可以提供 HTTP 终结点，以检索用户打开 Outlook 中电子邮件时包含最新信息的最新自适应卡片有效负载。

重要

在用户打开时刷新可操作消息会直接影响可操作消息解决方案的感知性能。提供更新卡的服务必须满足实现 Web API 中所述的性能要求，这一点至关重要。

注册要求

在开发人员仪表板注册到“测试用户”或“组织”作用域的可操作消息服务可以在获得批准后立即使用此功能。如果服务已注册到全局范围，则必须联系 onboardoam@microsoft.com 以启用此功能。

使用 autoInvokeAction

若要使用此功能，卡必须使用自适应卡片格式。 autoInvokeAction 属性是添加到 AdaptiveCard 类型的特定于 Outlook 的属性。此属性的值是 Action.Http 操作， method 并将设置为 POST。属性 url 在服务中指定一个 Web API 终结点，该终结点将提供更新的自适应卡片有效负载。

{
  "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
  "type": "AdaptiveCard",
  "version": "1.0",
  "body": [...],
  "actions": [...],
  "autoInvokeAction": {
    "method": "POST",
    "url": "https://actionablemessages.contoso.com/api/getupdatedcard",
    "body": "",
    "type": "Action.Http"
  }
}

创建初始自适应卡

使用 autoInvokeAction 时，消息中包含的初始卡仍然对最终用户有价值，并且理想情况下是可操作的，这一点非常重要。 autoInvokeAction可能会失败，或者网络状况可能会降低速度，在这种情况下，初始卡是最终用户将看到的所有情况。

不要仅autoInvokeAction使用发送空的初始卡。可操作消息平台将拒绝此类卡片。
不要发送只是要求用户等待的占位符的初始卡。
发送以当前状态显示信息的初始卡，即使这意味着用户在打开邮件时可能会看到过时的数据。

实现 Web API

Action.Http属性中指定的autoInvokeAction操作的工作方式与任何其他Action.Http操作完全相同。有关为此操作实现终结点的详细信息，请参阅实现 Web API。

的 autoInvokeAction 终结点还必须满足以下附加要求。

请求 必须在 2 秒内返回。
客户端将忽略花费较长时间的请求，并且原始卡将继续显示。消息仍将在服务器上更新。
成功的响应应包括一个 CARD-UPDATE-IN-BODY 具有值的 true 标头和一个自适应卡片 JSON 有效负载。

成功后，返回的自适应卡将完全替换电子邮件中的现有卡。如果 URL 返回错误或超时，则现有卡将继续显示。

审批方案示例

请考虑此示例休假请求卡由休假请求工具生成并发送给员工经理。

提示

可以通过在可操作邮件Designer中选择“休假审批”示例来访问 JSON 并修改此卡示例。

表示休假请求的可操作消息，包括请求的日期和员工的剩余休假余额。

卡包括帮助经理做出决策的信息，包括请求的日期和员工剩余的休假。生成和发送消息时，此信息是准确的。但是，在经理检查其电子邮件之前，数据可能会更改。例如，员工可以在休假请求工具中编辑他的请求，以更改请求的日期。

通过在工具生成的可操作消息中包含属性autoInvokeAction，当管理器打开时，具有原始数据的卡将被替换为新数据的新卡。中指定的 autoInvokeAction URL 返回相同的 JSON 有效负载，并为请求的假期日期提供新值。

休假请求可操作消息，其中包含所请求日期的更新值。

通过