创建和发送邮件

项目
06/26/2024

若要创建和发送可操作的消息，请使用传入 Webhook 或 Microsoft 365 连接器。但是，只有具有 Exchange Online 许可证的用户才能访问可操作邮件。

创建可操作邮件

可操作邮件包括卡片上的六个可见按钮。每个按钮通过使用ActionCard操作在消息的属性中potentialAction定义，每个按钮都具有输入类型、文本字段、日期选取器或多选列表。每个 ActionCard 都具有关联的操作，例如 HttpPOST。

连接器卡支持以下操作:

ActionCard: 显示一个或多个输入类型和关联的操作。
HttpPOST: 向 URL 发送 POST 请求。
OpenUri：在单独的浏览器或应用中打开 URI。（可选）基于操作系统以不同的 URI 为目标。

ActionCard 操作支持三种输入类型：

TextInput: 具有可选长度限制的单行或多行文本字段。
DateInput: 具有可选时间选择器的日期选择器。
MultichoiceInput: 提供单项选择或多重选择的选项枚举列表。

MultichoiceInput 支持控制列表最初是否完全展开的 style 属性。 style: 的默认值取决于 isMultiSelect 的值，如下所示:

`isMultiSelect`	违约 `style`
`false` 或未指定	`compact`
`true`	`expanded`

若要以紧凑样式显示多选列表，请指定 "isMultiSelect": true 和 "style": true。

有关连接器卡操作的详细信息，请参阅操作。

注意

在 Microsoft Teams 中指定 style 属性的 compact 与在 Microsoft Outlook 中指定 style 属性的 normal 相同。
对于 HttpPOST 操作，请求中包括承载令牌。此令牌包括采取操作的 Microsoft 365 用户的 Microsoft Entra 标识。

通过 Microsoft 365 组的传入 Webhook 或连接器发送消息

若要通过 Microsoft 365 组的传入 Webhook 或连接器发送消息，请将 JSON 有效负载发布到 Webhook URL。此有效负载必须采用 Microsoft 365 组的连接卡形式。

还可使用此 JSON 创建包含丰富输入内容 (如文本输入、多重选择或选择日期和时间) 的卡。生成卡并将其发布到 Webhook URL 的代码可以在任何托管服务上运行。这些卡片定义为可操作消息的一部分，在 Teams 机器人和消息扩展中使用的卡片中也受支持。

连接器消息示例

连接器消息示例如下所示:

{
    "@type": "MessageCard",
    "@context": "http://schema.org/extensions",
    "themeColor": "0076D7",
    "summary": "Larry Bryant created a new task",
    "sections": [{
        "activityTitle": "Larry Bryant created a new task",
        "activitySubtitle": "On Project Tango",
        "activityImage": "https://adaptivecards.io/content/cats/3.png",
        "facts": [{
            "name": "Assigned to",
            "value": "Unassigned"
        }, {
            "name": "Due date",
            "value": "Mon May 01 2017 17:07:18 GMT-0700 (Pacific Daylight Time)"
        }, {
            "name": "Status",
            "value": "Not started"
        }],
        "markdown": true
    }],
    "potentialAction": [{
        "@type": "ActionCard",
        "name": "Add a comment",
        "inputs": [{
            "@type": "TextInput",
            "id": "comment",
            "isMultiline": false,
            "title": "Add a comment here for this task"
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Add comment",
            "target": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }, {
        "@type": "ActionCard",
        "name": "Set due date",
        "inputs": [{
            "@type": "DateInput",
            "id": "dueDate",
            "title": "Enter a due date for this task"
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Save",
            "target": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }, {
        "@type": "OpenUri",
        "name": "Learn More",
        "targets": [{
            "os": "default",
            "uri": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }, {
        "@type": "ActionCard",
        "name": "Change status",
        "inputs": [{
            "@type": "MultichoiceInput",
            "id": "list",
            "title": "Select a status",
            "isMultiSelect": "false",
            "choices": [{
                "display": "In Progress",
                "value": "1"
            }, {
                "display": "Active",
                "value": "2"
            }, {
                "display": "Closed",
                "value": "3"
            }]
        }],
        "actions": [{
            "@type": "HttpPOST",
            "name": "Save",
            "target": "https://learn.microsoft.com/outlook/actionable-messages"
        }]
    }]
}

下图是通道中的连接器消息卡的示例：

屏幕截图显示了通道中连接器卡的示例。

若要使用 cURL 在 Webhook 中发布消息，请按照以下步骤进行:

从 cURL 网站安装 cURL。

在命令行中输入以下 cURL 命令：

// on macOS or Linux
curl -H 'Content-Type: application/json' -d '{"text": "Hello World"}' <YOUR WEBHOOK URL>

// on Windows
curl.exe -H "Content-Type:application/json" -d "{'text':'Hello World'}" <YOUR WEBHOOK URL>

注意

如果 POST 成功，则必须看到 curl 简单输出 1。

检查 Teams 客户端以查看已发布的新卡片。

先决条件: 安装 PowerShell 并熟悉其基本用法。

若要使用 PowerShell 将消息发布到 Webhook，请按照以下步骤进行:

在 PowerShell 提示符中，输入以下命令：
```
Invoke-RestMethod -Method post -ContentType 'Application/Json' -Body '{"text":"Hello World!"}' -Uri <YOUR WEBHOOK URL>
```
注意

如果 POST 成功，则必须看到 Invoke-RestMethod 简单输出 1。
检查与 Webhook URL 关联的 Teams 频道。你应查看发布到频道的新卡片。

使用传入 webhook 发送自适应卡

注意

完全支持所有本机自适应卡片架构元素 (Action.Submit除外)。
受支持的操作有 Action.OpenURL、Action.ShowCard，以及 Action.ToggleVisibility

若要通过传入 Webhook 发送带有文本或 Base64 编码图像的自适应卡片，请执行以下步骤：

在 Teams 中设置自定义 Webhook。
使用以下代码创建自适应卡的 JSON 文件:

Text
Base64 编码图像

    {
       "type":"message",
       "attachments":[
          {
             "contentType":"application/vnd.microsoft.card.adaptive",
             "contentUrl":null,
             "content":{
                "$schema":"http://adaptivecards.io/schemas/adaptive-card.json",
                "type":"AdaptiveCard",
                "version":"1.2",
                "body":[
                    {
                    "type": "TextBlock",
                    "text": "For Samples and Templates, see [https://adaptivecards.io/samples](https://adaptivecards.io/samples)"
                    }
                ]
             }
          }
       ]
    }

自适应卡 JSON 文件的属性如下所示:

"type" 字段必须为 "message"。
"attachments" 阵列包含一组卡对象。
"contentType" 字段必须设置为自适应卡类型。
"content" 对象为采用 JSON 格式的卡。

    {
      "type": "message",
      "attachments": [
        {
          "contentType": "application/vnd.microsoft.card.adaptive",
          "content": {
            "type": "AdaptiveCard",
            "body": [
              {
                "type": "Image",
                "url": "data&colon;image/jpeg;base64,/xxxxxxxx"
              }
            ],
            "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
            "version": "1.0"
          }
        }
      ]
    }

在此示例中，图像作为类型的 Image 附件包含，URL 设置为 Base64 编码的图像数据。确保将替换为 /xxxxxxxx 实际的 Base64 编码图像数据。

自适应卡 JSON 文件的属性如下所示:

"type" 字段必须为 "message"。
"attachments" 阵列包含一组卡对象。
"contentType" 字段必须设置为自适应卡类型。
"content" 对象为采用 JSON 格式的卡。

使用 Postman 测试自适应卡:
1. 使用 Postman 测试自适应卡，向为设置传入 Webhook 而创建的 URL 发送 POST 请求。
2. 将 JSON 文件粘贴至请求主体中，并在 Teams 中查看自适应卡。

提示

使用自适应卡代码示例和模板测试 POST 请求的主体。

连接器的速率限制

应用程序速率限制可以控制允许连接器或传入 Webhook 在频道上生成的流量。 Teams 使用固定速率窗口和以秒为单位的增量计数器跟踪请求。如果在一秒内发出的请求超过四个，则客户端连接会受到限制，直到窗口刷新的持续时间为固定速率。

每秒事务数阈值

下表提供了基于时间的事务详细信息:

时间 (秒)	允许的最大请求数
1	4
30	60
3600	100
7200	150
86400	1800

注意

具有指数补偿的重试逻辑将减轻速率限制，以应对请求在一秒内超出限制的情况。请参阅 HTTP 429 响应以避免达到速率限制。

// Please note that response body needs to be extracted and read 
// as Connectors do not throw 429s
try
{
    // Perform Connector POST operation     
    var httpResponseMessage = await _client.PostAsync(IncomingWebhookUrl, new StringContent(content));
    // Read response content
    var responseContent = await httpResponseMessage.Content.ReadAsStringAsync();
    if (responseContent.Contains("Microsoft Teams endpoint returned HTTP error 429")) 
    {
        // initiate retry logic
    }
}

这些限制已就位，通过连接器减少频道垃圾邮件，并确保用户获得最佳体验。

通过