pymsteams

Python用于发送请求到Microsoft Teams Webhook的包装库。Microsoft将这些消息称为连接器卡。可以只发送主连接器卡的消息，也可以将附加部分包含在消息中。

此库使用Microsoft Teams的Webhook连接器。请访问以下Microsoft文档链接以获取获取正确url的说明：https://dev.outlook.com/Connectors/GetStarted#creating-messages-through-office-365-connectors-in-microsoft-teams

请参阅Microsoft文档以获取最新的屏幕截图。https://dev.outlook.com/connectors/reference

安装

使用pip安装

pip install pymsteams

使用异步功能安装（python 3.6+）

pip install pymsteams[async]

Python 2安装

在撰写本文时，由Python 2支持的最新版本是版本0.1.16

用法

创建ConnectorCard消息

这是pymsteams最简单的实现。它将通过消息中的纯文本将消息发送到teams webhook url。

import pymsteams

# You must create the connectorcard object with the Microsoft Webhook URL
myTeamsMessage = pymsteams.connectorcard("<Microsoft Webhook URL>")

# Add text to the message.
myTeamsMessage.text("this is my text")

# send the message.
myTeamsMessage.send()

创建通过异步循环发送的CreatorCard消息

import asyncio
import pymsteams

loop = asyncio.get_event_loop()

# the async_connectorcard object is used instead of the normal one.
myTeamsMessage = pymsteams.async_connectorcard("<Microsoft Webhook URL>")

# all formatting for the message should be the same
myTeamsMessage.text("This is my message")

# to send the message, pass to the event loop
loop.run_until_complete(myTeamsMessage.send())

请访问python asyncio文档以获取有关使用asyncio和事件循环的更多信息：https://docs.pythonlang.cn/3/library/asyncio-eventloop.html

卡片可选格式化方法

添加标题

myTeamsMessage.title("This is my message title")

添加链接按钮

myTeamsMessage.addLinkButton("This is the button Text", "https://github.com/rveachkc/pymsteams/")

更改URL

如果您需要将相同的信息发布到多个房间，这非常有用。

myTeamsMessage.newhookurl("<My New URL>")

设置颜色主题

这设置了卡片的主题颜色。参数应为一个不带井号或字符串 "red" 的十六进制颜色代码。

myTeamsMessage.color("<Hex Color Code>")

预览对象

这是一个简单的打印命令，用于在发送之前查看您的连接器卡片消息对象。

myTeamsMessage.printme()

向连接器卡片消息添加部分

创建部分并添加各种格式化元素

# create the section
myMessageSection = pymsteams.cardsection()

# Section Title
myMessageSection.title("Section title")

# Activity Elements
myMessageSection.activityTitle("my activity title")
myMessageSection.activitySubtitle("my activity subtitle")
myMessageSection.activityImage("http://i.imgur.com/c4jt321l.png")
myMessageSection.activityText("This is my activity Text")

# Facts are key value pairs displayed in a list.
myMessageSection.addFact("this", "is fine")
myMessageSection.addFact("this is", "also fine")

# Section Text
myMessageSection.text("This is my section text")

# Section Images
myMessageSection.addImage("http://i.imgur.com/c4jt321l.png", ititle="This Is Fine")

# Add your section to the connector card object before sending
myTeamsMessage.addSection(myMessageSection)

您也可以向连接器卡片消息中添加多个部分。

# Create Section 1
Section1 = pymsteams.cardsection()
Section1.text("My First Section")

# Create Section 2
Section2 = pymsteams.cardsection()
Section2.text("My Second Section")

# Add both Sections to the main card object
myTeamsMessage.addSection(Section1)
myTeamsMessage.addSection(Section2)

# Then send the card
myTeamsMessage.send()

向连接器卡片消息添加潜在操作

要创建用户可以在 MS Teams 中与之交互的操作，请访问 https://docs.microsoft.com/en-us/microsoftteams/platform/concepts/connectors/connectors-using#setting-up-a-custom-incoming-webhook

myTeamsMessage = pymsteams.connectorcard("<Microsoft Webhook URL>")

myTeamsPotentialAction1 = pymsteams.potentialaction(_name = "Add a comment")
myTeamsPotentialAction1.addInput("TextInput","comment","Add a comment here",False)
myTeamsPotentialAction1.addAction("HttpPost","Add Comment","https://...") 

myTeamsPotentialAction2 = pymsteams.potentialaction(_name = "Set due date")
myTeamsPotentialAction2.addInput("DateInput","dueDate","Enter due date")
myTeamsPotentialAction2.addAction("HttpPost","save","https://...")

myTeamsPotentialAction3 = pymsteams.potentialaction(_name = "Change Status")
myTeamsPotentialAction3.choices.addChoices("In progress","0")
myTeamsPotentialAction3.choices.addChoices("Active","1")
myTeamsPotentialAction3.addInput("MultichoiceInput","list","Select a status",False)
myTeamsPotentialAction3.addAction("HttpPost","Save","https://...")

myTeamsMessage.addPotentialAction(myTeamsPotentialAction1)
myTeamsMessage.addPotentialAction(myTeamsPotentialAction2)
myTeamsMessage.addPotentialAction(myTeamsPotentialAction3)

myTeamsMessage.summary("Test Message")

myTeamsMessage.send()

向连接器卡片消息中的潜在操作添加 HTTP POST

myTeamsMessage = pymsteams.connectorcard("<Microsoft Webhook URL>")

myTeamsPotentialAction1 = pymsteams.potentialaction(_name = "Add a comment")
# You can add a TextInput to your potential action like below - Please note the 2nd argment below as the id name
myTeamsPotentialAction1.addInput("TextInput","comment","Add a comment here",False)
# we use the 2nd argument above as the id name to parse the values into the body post like below.
myTeamsPotentialAction1.addAction("HttpPost","Add Comment","https://...", "{{comment.value}}") 
myTeamsMessage.addPotentialAction(myTeamsPotentialAction1)


myTeamsMessage.summary("Test Message")

myTeamsMessage.send()

# Notes:
# If you post anything via teams, you will get some Javascript encoding happening via the post - For example:
# Posting this:  {"name":"john", "comment" : "nice"}
# Output will be:  b'{\\u0022name\\u0022:\\u0022john\\u0022, \\u0022comment\\u0022 : \\u0022nice\\u0022}'
# i solved this issue by decoding unicode escape for a custom rest backend.

请使用 Github issues 报告任何错误或请求增强功能。

故障排除 HTTP 响应

此模块实际上是一个指向 Microsoft API 的优美包装器。为了帮助调试缺失的消息，请求的响应内容被保存到连接器卡片类的 last_http_response 属性中。

获取最后一个 HTTP 状态码

import pymsteams

myTeamsMessage = pymsteams.connectorcard("<Microsoft Webhook URL>")
myTeamsMessage.text("this is my text")
myTeamsMessage.send()

last_status_code = myTeamsMessage.last_http_response.status_code

关于响应内容的更多信息可在 requests 文档中找到，链接。

异常

如果调用 Microsoft Teams webhook 服务失败，将抛出 TeamsWebhookException。

测试

为了在您的环境中使用 pytest 进行测试，请将环境变量 MS_TEAMS_WEBHOOK 设置为您想要使用的 Microsoft Teams Webhook URL。

然后，从存储库的根目录安装需求并运行 pytest。

pip install -r dev-requirements.txt
MS_TEAMS_WEBHOOK=MicrosoftWebhookURL
export MS_TEAMS_WEBHOOK
pytest --cov=./pymsteams --cov-report=term-missing --cov-branch

这将发送两条 MS Teams 消息，描述它们的格式。手动验证消息是否按预期到达。

证书验证

在某些情况下，必须使用自定义 CA 包。这可以在类初始化时设置，通过设置 verify 参数。

import pymsteams

# set custom ca bundle
msg = pymsteams.connectorcard("<Microsoft Webhook URL>", verify="/path/to/file")

# disable CA validation
msg = pymsteams.connectorcard("<Microsoft Webhook URL>", verify=False)

设置为自定义 CA 包的路径或设置为 False 以禁用。

有关完整详细信息，请参阅 requests 文档：https://2.python-requests.org/en/master/user/advanced/#ssl-cert-verification