应用部件清单
应用清单 (以前称为 Teams 应用清单) 描述应用如何集成到 Microsoft Teams 产品中。 应用清单必须符合托管在 https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json 的架构。 (URL) 中使用“v1.x”,支持以前的版本 1.0、1.1,...,1.17 和当前版本 1.19。 版本 1.18 不可用。 有关每个版本中所做的更改的详细信息,请参阅 应用清单更改日志 ;对于以前的版本,请参阅 应用清单版本。
根据不同的应用方案,下表列出了 TeamsJS 版本和应用清单版本:
应用类型 | TeamsJS 版本 | 应用清单版本 | 后续步骤 |
---|---|---|---|
跨 Outlook 和 Microsoft 365 扩展的 Teams 应用 | TeamsJS v.2.19.0 或更高版本 | v.1.13 或更高版本 | 扩展 Teams 应用以跨 Microsoft 365 运行或创建新的 Microsoft 365 应用 |
仅限 Teams 的现有应用 | 如果可能,仍支持更新 TeamsJS v.2.19.0 (v.1.12*) | 1.12 | 了解 TeamsJS 向后兼容性和更新到 TeamsJS v.2.0 |
仅限 Teams 的新应用 | TeamsJS v.2.19.0 或更高版本 | 1.12 | 使用 Teams 工具包创建新的 Teams 应用 |
* 尽可能使用最新的 TeamsJS (v.2.19.0 或更高版本) ,以利用最新的改进和新功能支持,包括仅限 Teams 的应用。TeamsJS v.1.12 继续受支持,但不会添加新的功能或改进。1.12 和 1.13 架构是相同的。有关详细信息,请参阅 TeamsJS 库。
注意
如果你的 Teams 应用使用的是应用清单版本 1.13 或更高版本,请确保应用符合 扩展应用以跨 Microsoft 365 或 Outlook 运行的条件。
下面是示例应用清单架构:
示例应用清单
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.19/MicrosoftTeams.schema.json",
"manifestVersion": "1.19",
"version": "1.0.0",
"id": "%MICROSOFT-APP-ID%",
"localizationInfo": {
"defaultLanguageTag": "en",
"defaultLanguageFile": "en.json",
"additionalLanguages": [
{
"languageTag": "es",
"file": "es.json"
}
]
},
"developer": {
"name": "Publisher Name",
"websiteUrl": "https://example.com/",
"privacyUrl": "https://example.com/privacy",
"termsOfUseUrl": "https://example.com/app-tos",
"mpnId": "1234567890"
},
"name": {
"short": "Name of your app (<=30 chars)",
"full": "Full name of app, if longer than 30 characters (<=100 chars)"
},
"description": {
"short": "Short description of your app (<= 80 chars)",
"full": "Full description of your app (<= 4000 chars)"
},
"icons": {
"outline": "A relative path to a transparent .png icon — 32px X 32px",
"color": "A relative path to a full color .png icon — 192px X 192px"
},
"accentColor": "A valid HTML color code.",
"copilotAgents": {
"declarativeAgents": [
{
"id": "agent1",
"file": "declarativeAgent1.json"
}
]
},
"configurableTabs": [
{
"configurationUrl": "https://contoso.com/teamstab/configure",
"scopes": [
"team",
"groupChat"
],
"canUpdateConfiguration": true,
"context": [
"channelTab",
"privateChatTab",
"meetingChatTab",
"meetingDetailsTab",
"meetingSidePanel",
"meetingStage"
],
"sharePointPreviewImage": "Relative path to a tab preview image for use in SharePoint — 1024px X 768",
"supportedSharePointHosts": [
"sharePointFullPage",
"sharePointWebPart"
]
}
],
"staticTabs": [
{
"entityId": "unique Id for the page entity",
"scopes": [
"personal"
],
"context": [
"personalTab",
"channelTab"
],
"name": "Display name of tab",
"contentUrl": "https://contoso.com/content (displayed in Teams canvas)",
"websiteUrl": "https://contoso.com/content (displayed in web browser)",
"searchUrl": "https://contoso.com/content (displayed in web browser)"
}
],
"supportedChannelTypes": [
"sharedChannels",
"privateChannels"
],
"bots": [
{
"botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
"scopes": [
"team",
"personal",
"groupChat"
],
"needsChannelSelector": false,
"isNotificationOnly": false,
"supportsFiles": true,
"supportsCalling": false,
"supportsVideo": true,
"commandLists": [
{
"scopes": [
"team",
"groupChat"
],
"commands": [
{
"title": "Command 1",
"description": "Description of Command 1"
},
{
"title": "Command 2",
"description": "Description of Command 2"
}
]
},
{
"scopes": [
"personal",
"groupChat"
],
"commands": [
{
"title": "Personal command 1",
"description": "Description of Personal command 1"
},
{
"title": "Personal command N",
"description": "Description of Personal command N"
}
]
}
]
}
],
"connectors": [
{
"connectorId": "GUID-FROM-CONNECTOR-DEV-PORTAL%",
"scopes": [
"team"
],
"configurationUrl": "https://contoso.com/teamsconnector/configure"
}
],
"composeExtensions": [
{
"canUpdateConfiguration": true,
"botId": "%MICROSOFT-APP-ID-REGISTERED-WITH-BOT-FRAMEWORK%",
"commands": [
{
"id": "exampleCmd1",
"title": "Example Command",
"type": "query",
"context": [
"compose",
"commandBox"
],
"description": "Command Description; e.g., Search on the web",
"initialRun": true,
"fetchTask": false,
"parameters": [
{
"name": "keyword",
"title": "Search keywords",
"inputType": "choiceset",
"description": "Enter the keywords to search for",
"value": "Initial value for the parameter",
"choices": [
{
"title": "Title of the choice",
"value": "Value of the choice"
}
]
}
]
},
{
"id": "exampleCmd2",
"title": "Example Command 2",
"type": "action",
"context": [
"message"
],
"description": "Command Description; e.g., Add a customer",
"initialRun": true,
"fetchTask": false ,
"parameters": [
{
"name": "custinfo",
"title": "Customer name",
"description": "Enter a customer name",
"inputType": "text"
}
]
},
{
"id": "exampleCmd3",
"title": "Example Command 3",
"type": "action",
"context": [
"compose",
"commandBox",
"message"
],
"description": "Command Description; e.g., Add a customer",
"fetchTask": false,
"taskInfo": {
"title": "Initial dialog title",
"width": "Dialog width",
"height": "Dialog height",
"url": "Initial webview URL"
}
}
],
"messageHandlers": [
{
"type": "link",
"value": {
"domains": [
"mysite.someplace.com",
"othersite.someplace.com"
],
"supportsAnonymizedPayloads": false
}
}
]
}
],
"permissions": [
"identity",
"messageTeamMembers"
],
"devicePermissions": [
"geolocation",
"media",
"notifications",
"midi",
"openExternal"
],
"validDomains": [
"contoso.com",
"mysite.someplace.com",
"othersite.someplace.com"
],
"webApplicationInfo": {
"id": "AAD App ID",
"resource": "Resource URL for acquiring auth token for SSO"
},
"authorization": {
"permissions": {
"resourceSpecific": [
{
"type": "Application",
"name": "ChannelSettings.Read.Group"
},
{
"type": "Delegated",
"name": "ChannelMeetingParticipant.Read.Group"
}
]
}
},
"showLoadingIndicator": false,
"isFullScreen": false,
"activities": {
"activityTypes": [
{
"type": "taskCreated",
"description": "Task created activity",
"templateText": "<team member> created task <taskId> for you"
},
{
"type": "userMention",
"description": "Personal mention activity",
"templateText": "<team member> mentioned you"
}
]
},
"defaultBlockUntilAdminAction": true,
"publisherDocsUrl": "https://example.com/app-info",
"defaultInstallScope": "meetings",
"defaultGroupCapability": {
"meetings": "tab",
"team": "bot",
"groupchat": "bot"
},
"configurableProperties": [
"name",
"shortDescription",
"longDescription",
"smallImageUrl",
"largeImageUrl",
"accentColor",
"developerUrl",
"privacyUrl",
"termsOfUseUrl"
],
"subscriptionOffer": {
"offerId": "publisherId.offerId"
},
"meetingExtensionDefinition": {
"scenes": [
{
"id": "9082c811-7e6a-4174-8173-6ccd57d377e6",
"name": "Getting started sample",
"file": "scenes/sceneMetadata.json",
"preview": "scenes/scenePreview.png",
"maxAudience": 15,
"seatsReservedForOrganizersOrPresenters": 0
},
{
"id": "afeaed22-f89b-48e1-98b4-46a514344e4a",
"name": "Sample-1",
"file": "scenes/sceneMetadata.json",
"preview": "scenes/scenePreview.png",
"maxAudience": 15,
"seatsReservedForOrganizersOrPresenters": 3
}
]
}
}
架构定义以下属性:
$schema
可选,但建议 - 字符串
引用应用清单的 JSON 架构的 https:// URL。
manifestVersion
必需 - 字符串
此清单使用的应用清单架构的版本。 使用 1.13
在 Outlook 和 Microsoft 365 应用中启用 Teams 应用支持;对仅限 Teams 的应用使用 1.12
(或更早的) 。
version
必需 - 字符串
特定应用的版本。 更新应用清单中的某些内容时,版本也必须递增。 这样,当安装新的应用清单时,它会覆盖现有应用清单,并且用户会收到新功能。 将此应用提交到 Microsoft Teams 应用商店时,必须重新提交并重新验证新的应用清单。 应用用户在批准应用清单后的几个小时内自动收到新的更新应用清单。
如果应用请求权限更改,系统会提示用户升级并重新进入应用。
此版本字符串必须遵循semver标准 (MAJOR.MINOR.PATCH)。
注意
如果应用包含 Office 加载项,则版本字符串的每个段限制为最多 5 位。 不支持 semver 标准的预发布和元数据版本字符串扩展。
ID
必需 - Microsoft应用 ID
ID 是 Microsoft 为应用生成的唯一标识符。 ID 的格式为 GUID。 如果机器人是通过Microsoft Bot Framework注册的,则有一个 ID。 如果你的选项卡的 Web 应用已使用 Microsoft 登录,则你有一个 ID。 必须在此处输入 ID。 否则,必须在 Microsoft 应用程序注册门户生成新 ID。 如果添加机器人,请使用相同的 ID。
存储在 Teams 管理中心中的 ID 是 外部应用 ID ,它在跟踪上显示为 ExternalID 。
注意
如果要向 AppSource 中的现有应用提交更新,则不能修改应用清单中的 ID。
developer
必需 - 对象
指定有关公司的信息。 对于提交到 Teams 应用商店的应用,这些值必须与 Teams 应用商店一览中的信息匹配。 有关详细信息,请参阅 Teams 应用商店发布指南。 开发人员名称有助于提高应用在 Teams 应用商店中的可发现性。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
name |
字符串 | 32 个字符 | ✔️ | 开发人员的显示名称。 |
websiteUrl |
String | 2048 个字符 | ✔️ | 开发人员网站的 https:// URL。 此链接必须将用户转到公司或产品特定的登陆页面。 |
privacyUrl |
String | 2048 个字符 | ✔️ | 开发人员隐私策略的 https:// URL。 |
termsOfUseUrl |
String | 2048 个字符 | ✔️ | 开发人员使用条款的 https:// URL。 |
mpnId |
String | 10 个字符 | 自选 Microsoft云合作伙伴计划 ID (以前称为 Microsoft 合作伙伴网络 (MPN) ID) ,用于标识生成应用的合作伙伴组织。 |
name
必需 - 对象
应用体验的名称,在 Teams 体验中向用户显示。 对于提交到 AppSource 的应用,这些值必须与 AppSource 条目中的信息匹配。
short
和full
的值必须不同。 应用名称有助于提高应用在 Teams 应用商店中的可发现性。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
short |
String | 30 个字符 | ✔️ | 应用的短显示名称。 使用 short 空间受限的属性,例如应用标头。 |
full |
String | 100 个字符 | ✔️ | 如果完整应用名称超过 30 个字符,则使用应用的全名。 使用 full 具有更多空间的属性,例如应用目录或应用详细信息页。 |
注意
- 在应用清单 v1.17 或更高版本中,
full
属性是必需的,而对于应用清单 v1.16 或更低版本,则不需要此属性。 - 属性
short
用于所有 UI 图面。
description
必需 - 对象
向用户描述应用。 对于提交到 AppSource 的应用,这些值必须与 AppSource 条目中的信息匹配。 应用说明有助于提高 Teams 应用商店中的应用可发现性。
确保说明描述你的体验,并帮助潜在客户了解你的体验。 如果需要使用外部帐户,则必须在完整说明中进行说明。
short
和full
的值必须不同。 简短说明不能在长说明中重复,并且不得包含任何其他应用名称。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
short |
String | 80 个字符 | ✔️ | 应用体验的简短说明,在空间受限时使用。 |
full |
String | 4000 个字符 | ✔️ | 应用的完整说明。 |
localizationInfo
可选 - 对象
允许指定默认语言,以及指向其他语言文件的指针。 参阅 本地化。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
defaultLanguageTag |
String | ✔️ | 此顶级应用清单文件中字符串的语言标记。 默认值为“en-us ”。 |
|
defaultLanguageFile |
String | 2048 个字符 | 包含字符串的.json文件的相对文件路径。 如果未指定,则直接从应用清单文件获取字符串。 支持多种语言的代理需要默认语言文件。 |
localizationInfo.additionalLanguages
对象数组,每个对象具有以下属性,用于指定其他语言翻译。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
languageTag |
String | ✔️ | 所提供文件中字符串的语言标记。 例如,es |
|
file |
String | 2048 个字符 | ✔️ | 包含已翻译字符串的.json文件的相对文件路径。 |
图标
必需 - 对象
Teams 应用中使用的图标。 图标文件必须作为上传包的一部分包含在内。 有关详细信息,请参阅 图标。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
outline |
String | 32 x 32 像素 | ✔️ | 透明 32x32 PNG 大纲图标的相对文件路径。 边框颜色必须为白色。 |
color |
String | 192 x 192 像素 | ✔️ | 完整颜色 192x192 PNG 图标的相对文件路径。 |
accentColor
必需 - HTML 十六进制颜色代码
一种颜色,用作颜色图标的背景。
该值必须是以"#"开头的有效 HTML 颜色代码,例如 #4464ee
。 有关详细信息,请参阅 accentColor。
copilotAgents
可选 - 对象
定义要智能 Microsoft 365 Copilot 副驾驶®的一个或多个代理。 声明性代理是在其同一业务流程协调程序和基础模型上运行的智能 Microsoft 365 Copilot 副驾驶®的自定义。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
declarativeAgents |
对象的数组。 | 1 | ✔️ | 每个对象定义声明性代理的数组。 |
declarativeAgents
表示智能 Microsoft 365 Copilot 副驾驶®的自定义,由其清单文件定义。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
id |
String | ✔️ | 代理的唯一标识符。 使用 Microsoft Copilot Studio 生成代理时,这是自动生成的。 否则,请根据自己的约定或首选项手动分配值。 | |
file |
String | 2048 个字符 | ✔️ | 应用包中声明 性代理清单 文件的相对文件路径。 |
configurableTabs
可选 - 数组
当你的应用体验具有团队频道选项卡体验时使用,该体验需要在添加之前进行额外配置。 只能在 team
和 groupChat
作用域中使用可配置的选项卡,并且可以多次配置相同的选项卡。 但是,只能在应用清单中定义它一次。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
configurationUrl |
字符串 | 2048 个字符 | ✔️ | 配置选项卡时要使用的 https:// URL。 |
scopes |
枚举数组 | 2 | ✔️ | 可配置的选项卡仅 team 支持 和 groupChat 范围。 |
canUpdateConfiguration |
布尔值 | 一个值,该值指示创建后用户是否可以更新选项卡配置的实例。 默认值: true |
||
meetingSurfaces |
枚举数组 | 2 |
支持选项卡的 meetingSurfaceItem 范围的集合。 默认值: sidePanel 、 stage |
|
context |
枚举数组 | 8 |
支持选项卡的 contextItem 范围的集合。 接受的值: [personalTab,channelTab,privateChatTab,meetingChatTab,meetingDetailsTab,meetingSidePanel,meetingStage]。 |
|
sharePointPreviewImage |
String | 2048 个字符 | 用于 SharePoint 的选项卡预览图像的相对文件路径。 大小 1024x768。 | |
supportedSharePointHosts |
枚举数组 | 2 | 定义如何在 SharePoint 中提供选项卡。 选项为 sharePointFullPage 和 sharePointWebPart 。 |
staticTabs
可选 - 数组
定义一组默认情况下可以固定的选项卡,而无需用户手动添加它们。 在 personal
范围内声明的静态选项卡始终固定到应用的个人体验。 但是,可以通过按相同的所需顺序添加选项卡的详细信息来对固定的选项卡进行重新排序。 有关详细信息,请参阅 对静态个人选项卡进行重新排序。
此属性还允许你为支持个人范围内的选项卡和机器人功能的应用设置默认登陆功能。 有关详细信息,请参阅 配置默认登陆功能。
此项是一个数组(最多 16 个元素),其类型的所有元素 object
。 只有提供静态选项卡解决方案的解决方案才需要此块。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
entityId |
字符串 | 64 个字符 | ✔️ | 选项卡显示的实体的唯一标识符。 |
name |
字符串 | 128 个字符 | 选项卡的显示名称。 | |
contentUrl |
String | 2048 个字符 | 指向要在 Teams 画布中显示的实体 UI 的 https:// URL。 | |
contentBotId |
String | 128 个字符 | 在 Bot Framework 门户中为机器人指定的Microsoft应用 ID。 | |
websiteUrl |
String | 2048 个字符 | 要指向用户是否选择在浏览器中查看的 https:// URL。 | |
searchUrl |
String | 2048 个字符 | 要指向用户搜索查询的 https:// URL。 | |
scopes |
枚举数组 | 3 | ✔️ | 指定选项卡是在团队频道上下文中提供体验,还是提供范围限定为单个用户或群组聊天的体验。 静态选项卡仅支持 personal 范围。 |
context |
枚举数组 | 8 |
支持选项卡的contextItem 上下文集。
接受的值: personalTab 、、channelTab 、privateChatTab 、meetingChatTab meetingDetailsTab meetingStage 、、meetingSidepanel 、 。 teamLevelApp
默认值: personalTab 、channelTab 、、privateChatTab meetingChatTab 、meetingDetailsTab 。 |
注意
-
groupChat
和team
范围仅在公共开发人员预览版中受支持。 - 上下文
teamLevelApp
仅适用于教育版租户。 - 此功能
searchUrl
不适用于第三方开发人员。 - 如果选项卡需要上下文相关信息来显示相关内容或启动身份验证流,请参阅 Microsoft Teams 选项卡的"获取上下文。
机器人
可选 - 数组
定义机器人解决方案以及可选信息(如默认命令属性)。
项是一个数组, (最多只有一个元素 — 每个应用只允许一个机器人,) 具有 类型 object
的所有元素。 只有提供机器人体验的解决方案才需要此块。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
botId |
String | ✔️ | 使用 Bot Framework 注册的自动程序的唯一 Microsoft 应用 ID。 ID 可以与整体应用 ID相同。 | |
scopes |
枚举数组 | 3 | ✔️ | 指定自动程序是在 team 内的频道上下文中提供体验、在群组聊天 (groupChat ) 中提供体验,还是仅在单个用户 (personal ) 范围内提供体验。 这些选项不具排他性。 |
needsChannelSelector |
布尔值 | 描述机器人是否使用用户提示将机器人添加到特定通道。 默认值: false |
||
isNotificationOnly |
布尔值 | 指示自动程序是否为单向、仅通知的自动程序,而不是对话自动程序。 默认值: false |
||
supportsFiles |
布尔值 | 指示自动程序是否支持在个人聊天中上传/下载文件。 默认值: false |
||
supportsCalling |
Boolean | 一个值,该值指示机器人支持音频调用的位置。
重要说明:此属性是实验性的。 实验属性可能不完整,并且可能会在完全可用之前进行更改。 该属性仅用于测试和探索目的,不得在生产应用程序中使用。 默认值: false |
||
supportsVideo |
Boolean | 一个值,该值指示机器人支持视频通话的位置。
重要说明:此属性是实验性的。 实验属性可能不完整,并且可能会在完全可用之前进行更改。 该属性仅用于测试和探索目的,不得在生产应用程序中使用。 默认值: false |
bots.configuration
可选 - 对象
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
team.fetchTask |
Boolean | ✔️ | 一个布尔值,指示它是否应动态提取对话 (TeamsJS v1.x 中称为任务模块) 。 默认值: false |
|
team.taskInfo |
Object | ✔️ | 使用机器人时要预加载的对话 | |
team.taskInfo.title |
字符串 | 64 个字符 | ✔️ | 初始对话框标题。 |
team.taskInfo.width |
字符串 | 16 个字符 | 对话框宽度是数字(以像素为单位)或默认布局,例如 large 、 medium 或 small 。 |
|
team.taskInfo.height |
String | 16 个字符 | 对话框高度是数字(以像素为单位)或默认布局,例如 large 、 medium 或 small 。 |
|
team.taskInfo.url |
String | 2048 个字符 | 初始 Web 视图 URL。 | |
groupChat.fetchTask |
布尔值 | ✔️ | 一个布尔值,指示它是否应动态提取对话。 默认值: false |
|
groupChat.taskInfo |
Object | 提取任务设置为 false 时要启动的对话。 默认值: false |
||
groupChat.taskInfo.title |
字符串 | 64 个字符 | ✔️ | 初始对话框标题。 |
groupChat.taskInfo.width |
字符串 | 16 | 对话框宽度是数字(以像素为单位)或默认布局,例如 large 、 medium 或 small 。 |
|
groupChat.taskInfo.height |
String | 16 | 对话框高度是数字(以像素为单位)或默认布局,例如 large 、 medium 或 small 。 |
|
groupChat.taskInfo.url |
String | 2048 个字符 | 初始 Web 视图 URL。 |
bots.commandLists
可选 - 数组
机器人可以向用户推荐的命令的列表。 对象是一个数组, (最多三个元素) 类型 object
的所有元素;必须为机器人支持的每个范围定义单独的命令列表。 有关详细信息,请参阅 机器人菜单。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
scopes |
枚举数组 | 3 | ✔️ | 指定命令列表有效的作用域。 选项包括 team 、personal 和 groupChat 。 |
commands |
对象的数组。 | 10 | ✔️ | 机器人支持的命令数组。 |
注意
当 属性中 commandLists
没有值时,Teams 移动客户端不支持机器人应用。
bots.commandLists.commands
必需 - 数组
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
title |
String | 32 | ✔️ | 机器人命令名称。 |
description |
String | 128 个字符 | ✔️ | 简单的文本说明或命令语法及其参数的示例。 |
连接器
可选 - 数组
块connectors
定义应用Microsoft 365 组的连接器卡。
对象是一个数组(最多一个元素),其中所有元素的类型为 object
。 只有提供连接器的解决方案才需要此块。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
configurationUrl |
字符串 | 2048 个字符 | ✔️ | 使用内联配置体验配置连接器时要使用的 https:// URL。 |
scopes |
枚举数组 | 1 | ✔️ | 指定连接器是在 team 的频道上下文中提供体验,还是仅限单个用户的体验(personal )。 仅 team 支持范围。 |
connectorId |
字符串 | 64 个字符 | ✔️ | 连接器的唯一标识符,与Connectors 开发人员仪表板中的 ID 匹配。 |
composeExtensions
可选 - 数组
定义应用的消息扩展。
注意
功能的名称在 2017 年 11 月从“撰写扩展”更改为“消息扩展”,但应用清单名称保持不变,以便现有扩展继续运行。
该项是一个数组(最大值为一个元素),其中所有元素的类型。 object
只有提供消息扩展的解决方案才需要此块。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
botId |
String | 支持消息扩展的机器人的唯一 Microsoft 应用 ID,已向机器人框架注册。 ID 可以与整体应用 ID 相同。 | ||
composeExtensionType |
String | ✔️ | 撰写扩展的类型。 枚举值为 botBased 和 apiBased 。 |
|
authorization |
Object | 2 | 基于 API 的消息扩展的授权相关信息。 | |
authorization.authType |
String | 可能授权类型的枚举。 支持的值为 none 、 apiSecretServiceAuth 和 microsoftEntra 。 |
||
authorization.microsoftEntraConfiguration |
Object | 对象捕获执行 microsoftEntra 身份验证流所需的详细信息。 仅当身份验证类型为 microsoftEntra 时适用。 |
||
authorization.microsoftEntraConfiguration.supportsSingleSignOn |
布尔值 | 一个值,该值指示是否为应用配置了单一登录。 | ||
authorization.apiSecretServiceAuthConfiguration |
Object | 对象捕获执行服务身份验证所需的详细信息。仅当身份验证类型为 apiSecretServiceAuth 时适用。 |
||
authorization.apiSecretServiceAuthConfiguration.apiSecretRegistrationId |
String | 128 个字符 | 开发人员通过开发人员门户提交 API 密钥时返回的注册 ID。 | |
apiSpecificationFile |
String | 2048 个字符 | 清单包中 API 规范文件的相对文件路径。 | |
canUpdateConfiguration |
布尔值 | 一个值,该值指示用户是否可以更新消息扩展的配置。 默认值: false |
||
commands |
对象的数组。 | 10 | 消息扩展支持的命令数组。 | |
messageHandlers |
对象的数组。 | 5 | 允许在满足特定条件时调用应用的处理程序列表。 | |
messageHandlers.type |
String | 消息处理程序的类型。 必须是 link 。 |
||
messageHandlers.value.domains |
字符串数组 | 2048 个字符 | 链接消息处理程序可以注册的域数组。 | |
messageHandlers.value.supportsAnonymizedPayloads |
布尔值 | 一个布尔值,指示应用的链接消息处理程序是否支持匿名调用流。 默认值: false |
composeExtensions.commands
消息扩展必须声明一个或多个命令,最多为 10 个命令。 每个命令都显示在 Microsoft Teams 中,作为来自基于 UI 的入口点的潜在交互。
每个命令项都是具有以下结构的对象:
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
id |
字符串 | 64 个字符 | ✔️ | 命令的 ID。 |
type |
字符串 | 命令的类型。
query 或action 之一。 默认值: query |
||
samplePrompts |
Array | 5 | 智能 Microsoft 365 Copilot 副驾驶®用于向用户显示代理支持的提示的属性。 | |
samplePrompts.text |
String | 128 个字符 | ✔️ | 示例提示的内容。 |
apiResponseRenderingTemplateFile |
String | 2048 个字符 | API 响应呈现模板 文件的相对文件路径,用于格式化从开发人员 API 到自适应卡片响应的 JSON 响应。 | |
context |
字符串数组 | 3 | 定义可以从何处调用消息扩展插件。
compose 、commandBox 、message 的任何组合。 默认值: compose, commandBox |
|
title |
字符串 | 32 个字符 | ✔️ | 用户友好的命令名称。 |
description |
字符串 | 128 个字符 | 向用户显示以指示此命令用途的说明。 | |
semanticDescription |
String | 5000 个字符 | 使用大型语言模型 (LLM) 智能 Microsoft 365 Copilot 副驾驶®使用的命令的语义说明。 | |
initialRun |
布尔值 | 布尔值指示命令最初是否在没有参数的情况下运行。 默认值: false |
||
fetchTask |
布尔值 | 一个布尔值,指示它是否必须动态提取对话 (TeamsJS v1.x 中称为任务模块) 。 默认值: false |
||
taskInfo |
Object | 指定要在使用消息扩展命令时预加载的对话。 | ||
taskInfo.title |
字符串 | 64 个字符 | 初始对话框标题。 | |
taskInfo.width |
字符串 | 对话框宽度 - 以像素为单位的数字或默认布局值,例如 large 、 medium 或 small 。 |
||
taskInfo.height |
String | 对话框高度 - 以像素为单位的数字或默认布局值,例如 large 、 medium 或 small 。 |
||
taskInfo.url |
String | 初始 Web 视图 URL。 | ||
parameters |
对象的数组。 | 5 | 命令采用的参数列表。 | |
parameters.name |
字符串 | 64 个字符 | ✔️ | 在客户端中显示的参数的名称。 参数名称包含在用户请求中。 |
parameters.title |
字符串 | 32 个字符 | ✔️ | 参数的用户友好标题。 |
parameters.description |
String | 128 个字符 | 描述此参数用途的用户友好字符串。 | |
parameters.semanticDescription |
String | 2000 个字符 | 使用大型语言模型 (LLM) 智能 Microsoft 365 Copilot 副驾驶®使用的参数的语义说明。 | |
parameters.value |
String | 512 个字符 | 参数的初始值。 不支持值。 | |
parameters.inputType |
String | 定义 在 fetchTask: false 对话框上显示的控件的类型。 输入值只能是 、、textarea 、number 、date time 、 toggle 中的choiceset 一个text 。 默认值: text |
||
parameters.choices |
对象的数组。 | 10 项 |
choiceset 的选择选项。 仅当 parameters.inputType 为 choiceset 时使用。 |
|
parameters.choices.title |
String | 128 个字符 | ✔️ | 选择的标题。 |
parameters.choices.value |
String | 512 个字符 | ✔️ | 选项的值。 |
permissions
可选 – 字符串数组
string
数组,指定应用请求的权限,让最终用户了解扩展的执行方式。 以下选项是非独占的:
-
identity
需要用户标识信息。 -
messageTeamMembers
需要向团队成员发送直接消息的权限。
在应用更新期间更改这些权限会导致用户在运行更新的应用后重复同意过程。 有关详细信息,请参阅更新应用。
注意
现已弃用这些权限。
devicePermissions
可选 – 字符串数组
在应用请求访问的用户设备上提供本机功能。 选项有:
geolocation
media
notifications
midi
openExternal
validDomains
可选 (,但 “必需 ”,其中) - 字符串数组
应用应在 Teams 客户端中加载的网站的有效域列表。 域列表可以包含通配符,例如,*.example.com
。 有效域与域的一个段完全匹配;如果需要匹配 a.b.example.com
则使用 *.*.example.com
。 如果选项卡配置或内容 UI 导航到选项卡配置以外的任何其他域,则必须在此处指定该域。
请 不要 包含要在应用中支持的标识提供程序的域。 例如,若要使用 Google ID 进行身份验证,需要重定向到 accounts.google.com,但不得在 中包含 validDomains[]
accounts.google.com。
需要自己的 SharePoint URL 才能正常运行的 Teams 应用包括 "{teamsitedomain}>在其有效域列表中。
重要
不要直接或通过通配符 () 添加无法控制的域 。例如,.yoursite.com 有效,但 *.onmicrosoft.com 无效,因为它不受你的控制。
使用通配符时,以下规则适用:
- 如果子域段包含通配符,则它必须是段中的唯一字符。
- 通配符段之前的任何段也必须是通配符段。
例如, *..domain.com 有效,但 foo.*.myteam.domain.com 无效。
对象是一个数组,其中包含类型的所有元素 string
。 对象的最大项为 16,最大长度为 2048 个字符。
webApplicationInfo
注意
属性 webApplicationInfo
与单个域相关,不支持多个域。 因此,如果你在不同域中托管了两个应用,则需要为每个应用创建单独的应用清单。
可选 - 对象
提供Microsoft Entra应用 ID 和 Microsoft Graph 信息,帮助用户无缝登录到应用。 如果你的应用已在 Microsoft Entra ID 中注册,则必须提供应用 ID。 管理员可以在 Teams 管理中心轻松查看权限并授予同意。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
id |
String | ✔️ | Microsoft Entra应用的应用程序 ID。 此 ID 必须是 GUID。 | |
resource |
String | 2048 个字符 | 用于获取 SSO 的身份验证令牌的应用的资源 URL。
注意: 如果不使用 SSO,请确保在应用清单的此字段中输入一个虚拟字符串值,例如, https://example 以避免错误响应。 虚拟 URL 字符串值不能包含不在你的控制下(直接或通过通配符)的域或 URL。 例如, yourapp.onmicrosoft.com 有效,但 *.onmicrosoft.com 无效。 顶级域是禁止的,例如 、 *.com *.org 。 |
graphConnector
可选 - 对象
指定应用的 Graph 连接器配置。 如果存在,则还必须指定 webApplicationInfo.id 。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
notificationUrl |
字符串 | 2048 个字符 | ✔️ | 应在其中发送应用程序的 Graph 连接器通知的 URL。 |
showLoadingIndicator
可选 - 布尔值
指示是否在加载应用或选项卡时显示加载指示器。 默认为 false。
注意
- 如果在
showLoadingIndicator
应用清单中选择“true”,若要正确加载页面,请按 显示本机加载指示器 文档中所述修改选项卡和对话框的内容页。 - 如果不修改选项卡的内容页,则选项卡应用不会加载并显示错误
There was a problem reaching this app
。
isFullScreen
可选 - 布尔值
指示是否在没有选项卡标题栏(表示全屏模式)的情况下呈现个人应用。 默认值: false
注意
isFullScreen
仅适用于发布到组织的应用。 上传和发布的第三方应用无法使用此属性, () 忽略此属性。参数
isFullScreen=true
从个人应用和对话中消除 Teams 提供的标题栏和标题。 但是,建议不要将isFullScreen=true
参数用于聊天机器人应用。
activities
可选 - 对象
定义应用用于发布用户活动源的属性。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
activityTypes |
对象的数组。 | 128 个项目 | 提供应用可以发布到用户活动源的活动类型。 |
activities.activityTypes
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
type |
字符串 | 64 个字符 | ✔️ | 通知类型。 |
description |
String | 128 个字符 | ✔️ | 通知的简要说明。 |
templateText |
String | 128 个字符 | ✔️ | 例如:"{actor} 为你创建了任务 {taskId}" |
{
"activities":{
"activityTypes":[
{
"type":"taskCreated",
"description":"Task Created Activity",
"templateText":"{actor} created task {taskId} for you"
},
{
"type":"teamMention",
"description":"Team Mention Activity",
"templateText":"{actor} mentioned team"
},
{
"type":"channelMention",
"description":"Channel Mention Activity",
"templateText":"{actor} mentioned channel"
},
{
"type":"userMention",
"description":"Personal Mention Activity",
"templateText":"{actor} mentioned user"
},
{
"type":"calendarForward",
"description":"Forwarding a Calendar Event",
"templateText":"{actor} sent user an invite on behalf of {eventOwner}"
},
{
"type":"calendarForward",
"description":"Forwarding a Calendar Event",
"templateText":"{actor} sent user an invite on behalf of {eventOwner}"
},
{
"type":"creatorTaskCreated",
"description":"Created Task Created",
"templateText":"The Creator created task {taskId} for you"
}
]
}
}
defaultInstallScope
可选 - 字符串
指定默认情况下为此应用定义的安装范围。 在用户添加应用后,默认安装范围与范围选择对话框中的相应范围相邻的 “建议 ”选项表示。 选项包括:
personal
team
groupChat
meetings
defaultGroupCapability
可选 - 对象
选择组安装范围后,它会定义用户安装应用时的默认功能。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
team |
String | 当选择的安装范围为 team 时,此字段指定可用的默认功能。 选项: tab 、 bot 或 connector 。 |
||
groupchat |
String | 当选择的安装范围为 groupChat 时,此字段指定可用的默认功能。 选项: tab 、 bot 或 connector 。 |
||
meetings |
String | 当选择的安装范围为 meetings 时,此字段指定可用的默认功能。 选项: tab 、 bot 或 connector 。 |
configurableProperties
可选 - 数组
块 configurableProperties
定义 Teams 管理员可以自定义的应用属性。 有关详细信息,请参阅启用 应用自定义。 为组织构建的自定义应用或自定义应用不支持应用自定义功能, (LOB 应用) 。
注意
必须定义至少一个属性。 最多可以在此块中定义九个属性。
可以定义以下任一属性:
- name:应用的显示名称。
- shortDescription:应用的简短说明。
- longDescription:应用的长说明。
- smallImageUrl:应用的大纲图标。
- largeImageUrl:应用的颜色图标。
- accentColor:要使用的颜色和边框图标的背景。
- developerUrl:开发人员网站的 HTTPS URL。
- privacyUrl:开发人员隐私策略的 HTTPS URL。
- termsOfUseUrl:开发人员使用条款的 HTTPS URL。
supportedChannelTypes
可选 - 数组
在非标准频道中启用应用。 如果应用支持团队范围,并且定义了此属性,Teams 会在每个频道类型中相应地启用应用。 supportedChannelTypes 属性仅支持 sharedChannels
和 privateChannels
。
注意
- 如果应用支持团队范围,则无论在此属性中定义的值如何,它都会在标准频道中运行。
- 应用可以考虑每个频道类型的唯一属性,以便正常运行。 若要为专用频道和共享频道启用选项卡,请参阅 检索专用频道中的上下文 和 获取共享频道中的上下文
defaultBlockUntilAdminAction
可选 - 布尔值
当 defaultBlockUntilAdminAction
属性设置为 true时,应用默认向用户隐藏,直到管理员允许它。 如果设置为 true,则应用将隐藏所有租户和最终用户。 Teams 管理员可以在 Teams 管理中心查看应用,并采取措施来允许或阻止应用。 默认值为 false。 有关默认应用阻止的详细信息,请参阅 在管理员批准之前默认阻止用户应用。
publisherDocsUrl
可选 - 字符串
最大大小 - 2048 个字符
参数的值 publisherDocsUrl
是应用开发人员选择提供的应用文档和信息页的安全 HTTPS URL。 Teams 管理员通过此 URL 获取有关应用的文档。 Teams 管理中心在应用详细信息页中显示 URL。 文档可能包括管理员为促进应用采用和应用推出而提供的说明。 在应用文档中,还可以包含对 Teams 管理员、用户和其他业务利益干系人有用的应用的说明或信息。
subscriptionOffer
可选 - 对象
指定与你的应用关联的 SaaS 产品/服务。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
offerId |
字符串 | 2048 个字符 | ✔️ | 包含你的产品/服务 ID Publisher产品/服务 ID 的唯一标识符,可在合作伙伴中心找到。 必须将字符串格式为 publisherId.offerId 。 |
meetingExtensionDefinition
可选 - 对象
指定会议扩展定义。 有关详细信息,请参阅 Teams 中的自定义“同框场景模式”场景。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
scenes |
对象的数组。 | 5 个项目 | 会议支持的场景。 | |
supportsStreaming |
Boolean | 指示应用是否可以将会议的音频和视频内容流式传输到实时会议协议 (RTMP) 终结点的值。 默认值: false |
||
supportsAnonymousGuestUsers |
布尔值 | 一个 值,该值指示应用是否支持匿名用户访问。 默认值: false |
注意
supportsAnonymousGuestUsers
应用清单架构 v1.16 中的 属性仅在新的 Teams 客户端中受支持。
meetingExtensionDefinition.scenes
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
id |
String | ✔️ | 场景的唯一标识符。 此 ID 必须是 GUID。 | |
name |
String | 128 个字符 | ✔️ | 场景的名称。 |
file |
String | 2048 个字符 | ✔️ | 场景的元数据 json 文件的相对文件路径。 |
preview |
String | 2048 个字符 | ✔️ | 场景的 PNG 预览图标的相对文件路径。 |
maxAudience |
整数 | 50 | ✔️ | 场景中支持的最大受众数。 |
seatsReservedForOrganizersOrPresenters |
整数 | 50 | ✔️ | 为组织者或演示者保留的席位数。 |
授权
可选 - 对象
注意
authorization
仅应用清单版本 1.12 或更高版本受支持。
指定并合并应用的授权相关信息。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
permissions |
Object | 应用运行所需的权限列表。 |
authorization.permissions
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
resourceSpecific |
对象的数组。 | 16 个项目 | 在资源实例级别保护数据访问的权限。 |
authorization.permissions.resourceSpecific
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
type |
String | ✔️ | 特定于资源的许可类型 (RSC) 权限。 选项: Application 和 Delegated 。 |
|
name |
String | 128 个字符 | ✔️ | RSC 权限的名称。 有关详细信息,请参阅 RSC 应用程序权限 和 RSC 委托的权限 |
RSC 应用程序权限
应用程序权限允许应用在用户未登录的情况下访问数据。 有关应用程序权限的信息,请参阅 Microsoft Graph 和 Microsoft BotSDK 的 RSC 权限。
RSC 委托的权限
委派的权限允许应用代表已登录用户访问数据。
团队的 RSC 委派权限
名称 说明 ChannelMeetingParticipant.Read.Group
允许应用代表已登录用户读取与此团队关联的频道会议的参与者信息,包括姓名、角色、ID、加入和离开时间。 ChannelMeetingIncomingAudio.Detect.Group
允许应用检测与团队关联的频道会议中的传入音频。 ChannelMeetingActiveSpeaker.Read.Group
允许应用读取向与团队关联的频道会议发送音频的参与者。 ChannelMeetingAudioVideo.Stream.Group
允许应用流式传输与团队关联的频道会议中的音频视频内容。 InAppPurchase.Allow.Group
允许应用代表已登录用户向团队中的用户显示市场产品/服务,并在应用中完成购买。 ChannelMeetingStage.Write.Group
允许应用代表已登录用户在与团队关联的频道会议中显示会议舞台上的内容。 LiveShareSession.ReadWrite.Group
允许应用代表已登录用户为团队创建和同步 Live Share 会话,并获取有关团队名册和任何关联会议的访问权限相关信息,例如名称和角色。 MeetingParticipantReaction.Read.Group
允许应用读取与团队关联的频道会议中参与者的反应。 聊天或会议的 RSC 委派权限
名称 说明 InAppPurchase.Allow.Chat
允许应用代表已登录用户在聊天和任何关联的会议中向用户显示市场优惠,并在应用中完成购买。 MeetingStage.Write.Chat
允许应用代表已登录用户在与聊天关联的会议中显示会议舞台上的内容。 OnlineMeetingParticipant.Read.Chat
允许应用代表已登录用户读取与聊天关联的会议的参与者信息,包括姓名、角色、ID、加入和离开时间。 OnlineMeetingParticipant.ToggleIncomingAudio.Chat
允许应用代表已登录用户为与聊天关联的会议中的参与者切换传入音频。 LiveShareSession.ReadWrite.Chat
允许应用代表已登录用户创建和同步聊天的 Live Share 会话,并获取有关聊天名单和任何关联会议的访问权限相关信息,例如姓名和角色。 MeetingParticipantReaction.Read.Chat
允许应用读取与聊天关联的会议中参与者的反应。 OnlineMeetingIncomingAudio.Detect.Chat
允许应用代表已登录用户检测与聊天关联的会议中传入音频的状态更改。 OnlineMeetingActiveSpeaker.Read.Chat
允许应用读取正在向与聊天关联的会议发送音频的参与者。 OnlineMeetingAudioVideo.Stream.Chat
允许应用流式传输与聊天关联的会议的音频视频内容。 用户的 RSC 委派权限
名称 说明 CameraStream.Read.User
允许应用读取用户的相机流。 InAppPurchase.Allow.User
允许应用代表已登录用户显示用户市场产品/服务并完成用户在应用内的购买。 OutgoingVideoStream.Write.User
允许应用修改用户的传出视频。 MicrophoneStream.Read.User
允许应用读取用户的麦克风流。 MeetingParticipantReaction.Read.User
允许应用在参与会议时读取用户的反应。
extensions
可选 - 对象
属性 extensions
指定应用清单中的 Outlook 外接程序,并简化了跨 Microsoft 365 生态系统的分发和获取。 每个应用仅支持一个扩展。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
requirements |
Object | 指定扩展的客户端或主机要求集。 | ||
runtimes |
Array | 20 | 配置可由每个扩展点使用的运行时和操作集。 有关详细信息,请参阅 Office 外接程序中的运行时。 | |
ribbons |
Array | 20 | 定义功能区扩展点。 | |
autoRunEvents |
Array | 10 | 定义基于事件的激活扩展点。 | |
alternates |
Array | 10 | 指定与替换现有Microsoft 365 解决方案的关系。 它用于对具有重叠功能的同一发布者隐藏加载项或设置其优先级。 | |
audienceClaimUrl |
String | 2048 个字符 | 指定扩展的 URL,并用于验证 Exchange 用户标识令牌。 有关详细信息,请参阅 Exchange 标识令牌内部 |
有关详细信息,请参阅 Microsoft 365 的 Office 外接程序清单。
extensions.requirements
对象 extensions.requirements
指定在 Office 客户端上必须支持的作用域、外形规格和 Office JavaScript 库要求集,以便安装外接程序。 此外,还支持对 ribbon
、 runtime
、 alternates
和 autoRunEvents
子属性的要求,以便有选择地筛选出加载项的某些功能。 有关详细信息,请参阅 Microsoft 365 的统一清单中的指定 Office 外接程序要求。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
capabilities |
Array | 100 | 标识要求集。 | |
capabilities.name |
String | ✔️ | 标识要求集的名称。 | |
capabilities.minVersion |
String | 标识要求集的最低版本。 | ||
capabilities.maxVersion |
String | 标识要求集的最大版本。 | ||
scopes |
枚举数组 | 1 | 标识加载项可在其中运行的范围,并定义扩展可在其中运行的Microsoft 365 应用程序。 例如, mail (Outlook) 。 支持的值: mail |
|
formFactors |
枚举数组 | 标识支持加载项的外形规格。 支持的值: mobile 、 desktop |
extensions.runtimes
可选 - 数组
数组 extensions.runtimes
配置每个扩展点可以使用的运行时和操作集。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
id |
字符串 | 64 个字符 | ✔️ | 指定运行时的 ID。 |
type |
字符串枚举 | ✔️ | 指定运行时的类型。
基于浏览器的运行时general 支持的枚举值为 。 |
|
code |
Object | ✔️ | 指定运行时的代码位置。 基于 runtime.type ,加载项可以使用 JavaScript 文件或带有嵌入 script 标记的 HTML 页面,该标记指定 JavaScript 文件的 URL。 在不确定的情况下 runtime.type ,这两个 URL 都是必需的。 |
|
code.page |
String | 2048 个字符 | ✔️ | 指定包含嵌入 script 标记的网页的 URL,该标记指定要在 基于浏览器的运行时) 加载 (JavaScript 文件的 URL。 |
code.script |
String | 2048 个字符 | 指定要在仅限 JavaScript 的运行时中加载的 JavaScript 文件的 URL。 | |
lifetime |
字符串枚举 | 指定运行时的生存期。 具有生存期的 short 运行时不会跨执行保留状态,而具有生存期的 long 运行时则保留状态。 有关详细信息,请参阅 Office 外接程序中的运行时。默认值: short |
||
actions |
Array | 20 | 指定运行时支持的一组操作。 操作要么运行 JavaScript 函数,要么打开任务窗格等视图。 | |
actions.id |
字符串 | 64 个字符 | ✔️ | 指定传递给代码文件的操作的 ID。 |
actions.type |
String | ✔️ | 指定操作的类型。 该 executeFunction 类型在不等待 JavaScript 函数完成的情况下运行 JavaScript 函数,并且该 openPage 类型在给定视图中打开一个页面。 |
|
actions.displayName |
字符串 | 64 个字符 | 指定操作的显示名称,它不是调用) 配置的 tabs.groups.controls.label 操作 (按钮或菜单项的标签。 |
|
actions.pinnable |
布尔值 | 指定任务窗格支持固定,即使用户选择其他对象,任务窗格也可以继续处于打开状态。 默认值: false |
||
actions.view |
字符串 | 64 个字符 | 指定必须在其中打开页面的视图。 它仅在 为 openPage 时actions.type 使用。 |
|
actions.multiselect |
布尔值 | 指定最终用户是否可以选择多个项目(例如多个电子邮件),并将操作应用于所有这些项目。 默认值: false |
||
actions.supportsNoItemContext |
布尔值 | 允许在不启用阅读窗格或未选择邮件的情况下激活任务窗格加载项。 默认值: false |
||
requirements |
Object | 指定 Office 客户端上必须支持的范围、formFactors 和 Office JavaScript 库要求集,以便将运行时包含在外接程序中。 有关详细信息,请参阅 Microsoft 365 的统一清单中的指定 Office 外接程序要求。 | ||
requirements.capabilities |
Array | 标识要求集。 选项: name (必需) 、 minVersion maxVersion |
||
requirements.capabilities.name |
String | ✔️ | 标识要求集的名称。 | |
requirements.capabilities.minVersion |
String | 标识要求集的最低版本。 | ||
requirements.capabilities.maxVersion |
String | 标识要求集的最大版本。 | ||
requirements.scopes |
枚举数组 | 1 | 标识加载项可在其中运行的范围,并定义扩展可在其中运行的Microsoft 365 应用程序。 例如, mail (Outlook) 。 支持的值: mail |
|
requirements.formFactors |
枚举数组 | 标识支持加载项的外形规格。 支持的值: mobile 、 desktop |
若要使用 extensions.runtimes
,请参阅 创建外接程序命令、 为任务窗格配置运行时和 为函数命令配置运行时。
extensions.ribbons
可选 - 数组
属性 extensions.ribbons
提供将 加载项命令 (按钮和菜单项) 添加到 Microsoft 365 应用程序的功能区的功能区的功能。 根据要求和顺序第一顺序从数组中选择功能区定义。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
contexts |
Array | 7 | 指定用户可以使用功能区自定义的 Microsoft 365 应用程序窗口。 数组中的每个项都是字符串数组的成员。 支持的值: mailRead 、、mailCompose 、meetingDetailsOrganizer 、meetingDetailsAttendee onlineMeetingDetailsOrganizer 、logEventMeetingDetailsAttendee 、default |
|
requirements |
Object | 指定 Office 客户端上必须支持的范围、formFactors 和 Office JavaScript 库要求集,以便显示功能区自定义项。 有关详细信息,请参阅 Microsoft 365 的统一清单中的指定 Office 外接程序要求。 | ||
requirements.capabilities |
Array | 标识要求集。 选项: name (必需) 、 minVersion maxVersion |
||
requirements.capabilities.name |
String | ✔️ | 标识要求集的名称。 | |
requirements.capabilities.minVersion |
String | 标识要求集的最低版本。 | ||
requirements.capabilities.maxVersion |
String | 标识要求集的最大版本。 | ||
requirements.scopes |
枚举数组 | 1 | 标识加载项可在其中运行的范围,并定义扩展可在其中运行的Microsoft 365 应用程序。 例如, mail (Outlook) 。 支持的值: mail |
|
requirements.formFactors |
枚举数组 | 标识支持加载项的外形规格。 支持的值: mobile 、 desktop |
||
tabs |
Array | 20 | ✔️ | 配置 Microsoft 365 应用程序功能区上的自定义选项卡。 |
tabs.id |
字符串 | 64 个字符 | 指定应用中选项卡的 ID。 | |
tabs.builtInTabId |
字符串 | 64 个字符 | 指定内置 Office 功能区选项卡的 ID。有关可能值的详细信息,请参阅 查找内置 Office 功能区选项卡的 ID。 选项卡对象的唯一其他子属性可以与此对象结合使用,即 groups 和 customMobileRibbonGroups 。 |
|
tabs.label |
字符串 | 64 个字符 | 指定为选项卡显示的文本。尽管最大长度为 64 个字符,但为了正确对齐功能区中的选项卡,我们建议将标签限制为 16 个字符。 | |
tabs.position |
Object | 配置自定义选项卡相对于功能区上其他选项卡的位置。 | ||
tabs.position.builtInTabId |
字符串 | 64 个字符 | ✔️ | 指定自定义选项卡应放置在其旁边的内置选项卡的 ID。 有关详细信息,请参阅 查找控件和控件组的 ID。 |
tabs.position.align |
字符串枚举 | ✔️ | 定义自定义选项卡相对于指定内置选项卡的对齐方式。 支持的值: after 、 before |
|
tabs.groups |
Array | 10 | 在非移动设备的功能区选项卡上定义控件组。 对于移动设备,请参阅 tabs.customMobileRibbonGroups 。 |
|
tabs.groups.id |
字符串 | 64 个字符 | 指定应用内选项卡组的 ID。 它必须与 Microsoft 365 应用程序和任何其他自定义组中的任何内置组 ID 不同。 | |
tabs.groups.label |
字符串 | 64 个字符 | 指定为组显示的文本。 尽管最大长度为 64 个字符,但为了正确对齐功能区中的选项卡,我们建议将标签限制为 16 个字符。 | |
tabs.groups.icons |
Array | 3 | 指定为组显示的图标。 | |
tabs.groups.icons.size |
数字 | ✔️ | 指定图标的大小(以像素为单位),枚举为 16 、20 、24 、32 40 、48 、64 80 。 所需的映像大小: 16 、 32 、 80 。 |
|
tabs.groups.icons.url |
String | 2048 个字符 | ✔️ | 指定图标的绝对 URL。 |
tabs.groups.controls |
Array | 配置组中的按钮和菜单。 | ||
tabs.groups.controls.id |
字符串 | 64 个字符 | ✔️ | 指定应用中控件的 ID。 它必须与 Microsoft 365 应用程序和任何其他自定义控件中的任何内置控件 ID 不同。 |
tabs.groups.controls.items |
Array | 配置菜单控件的项。 | ||
tabs.groups.controls.items.id |
String | ✔️ | 指定菜单项的 ID。 | |
tabs.groups.controls.items.type |
字符串枚举 | ✔️ | 定义菜单项的控件类型。 支持的值: button |
|
tabs.groups.controls.items.label |
字符串 | 64 个字符 | ✔️ | 指定为菜单项显示的文本。 |
tabs.groups.controls.items.icons |
Array | 配置菜单项的图标。 | ||
tabs.groups.controls.items.icons.size |
数字 | ✔️ | 指定图标的大小(以像素为单位),枚举为 16 、20 、24 、32 40 、48 、64 80 。 所需的映像大小: 16 、 32 、 80 。 |
|
tabs.groups.controls.items.icons.url |
URL | ✔️ | 指定图标的绝对 URL。 | |
tabs.groups.controls.items.supertip |
✔️ | 为菜单项配置超级提示。 超级提示是一项 UI 功能,当光标悬停在控件上时,它会显示有关控件的简短帮助信息框。 该框可能包含多行文本。 | ||
tabs.groups.controls.items.supertip.title |
字符串 | 64 个字符 | ✔️ | 指定超级提示的标题文本。 |
tabs.groups.controls.items.supertip.description |
String | 128 个字符 | ✔️ | 指定超级提示的说明。 |
tabs.groups.controls.items.actionId |
字符串 | 64 个字符 | ✔️ | 指定用户选择控件或菜单项时所执行的操作的 ID。 必须与 actionId 某些 runtimes.actions.id 属性值匹配。 |
tabs.groups.controls.items.enabled |
布尔值 | 指示最初是否启用菜单项。 默认值: true |
||
tabs.groups.controls.items.overriddenByRibbonApi |
布尔值 | 指定菜单项是否隐藏在支持 API (Office.ribbon.requestCreateControls) 的应用程序和平台组合上。 此 API 在功能区上安装自定义上下文选项卡。 默认值: false |
||
tabs.groups.controls.type |
String | ✔️ | 定义控件类型。 支持的值: button 、 menu |
|
tabs.groups.controls.builtInControlId |
字符串 | 64 个字符 | ✔️ | 指定现有 Microsoft 365 控件的 ID。 有关详细信息,请参阅 查找控件和控件组的 ID。 此属性不能与控件对象的任何其他子属性结合使用,因为外接程序无法自定义内置控件。 |
tabs.groups.controls.label |
字符串 | 64 个字符 | ✔️ | 指定为控件显示的文本。 尽管最大长度为 64 个字符,但为了正确对齐功能区中的选项卡,我们建议将标签限制为 16 个字符。 |
tabs.groups.controls.icons |
Array | ✔️ | 定义控件的图标。 必须至少有三个子对象:每个具有 size 、 32 和 80 像素的属性16 。 |
|
tabs.groups.controls.icons.size |
数字 | ✔️ | 指定图标的大小(以像素为单位),枚举为 16 、20 、24 、32 40 、48 、64 80 。 所需的映像大小: 16 、 32 、 80 |
|
tabs.groups.controls.icons.url |
URL | 指定图标文件的绝对 URL。 | ||
tabs.groups.controls.supertip |
Object | ✔️ | 为控件配置超级提示。 超级提示是一项 UI 功能,当光标悬停在控件上时,它会显示有关控件的简短帮助信息框。 该框可能包含多行文本。 | |
tabs.groups.controls.supertip.title |
字符串 | 64 个字符 | ✔️ | 指定超级提示的标题文本。 |
tabs.groups.controls.supertip.description |
String | 128 个字符 | ✔️ | 指定超级提示的说明。 |
tabs.groups.controls.actionId |
字符串 | 64 个字符 | 如果控件类型为 ,则 button 为 必需。 如果控件类型为 , menu 请不要使用 。 指定用户选择控件时所执行的操作的 ID。 必须与 actionId 对象中runtimes 操作的 属性匹配runtime.actions.id 。 |
|
tabs.groups.controls.enabled |
布尔值 | 指示控件最初是否已启用。 默认值: true |
||
tabs.groups.controls.overriddenByRibbonApi |
布尔值 | 指定控件是否隐藏在支持 API (Office.ribbon.requestCreateControls) 的应用程序和平台组合上。 此 API 在功能区上安装自定义上下文选项卡。 默认值: false |
||
tabs.groups.builtInGroupId |
字符串 | 64 个字符 | 指定内置组的 ID。 有关详细信息,请参阅 查找控件和控件组的 ID。 此属性不能与组对象的任何其他子属性结合使用,因为外接程序无法自定义内置组。 | |
tabs.customMobileRibbonGroups |
Array | 10 | 在移动设备上功能区的默认选项卡上定义控件组。 此数组属性只能存在于属性 tabs.builtInTabId 设置为 DefaultTab 的选项卡对象上。 对于非移动设备,请参阅 tabs.groups 上文。 |
|
tabs.customMobileRibbonGroups.id |
String | 250 个字符 | ✔️ | 指定组的 ID。 它必须与 Microsoft 365 应用程序和任何其他自定义组中的任何内置组 ID 不同。 |
tabs.customMobileRibbonGroups.label |
字符串 | 32 个字符 | ✔️ | 指定组上的标签。 |
tabs.customMobileRibbonGroups.controls |
Array | 20 | ✔️ | 定义组中的控件。 仅支持移动按钮。 |
tabs.customMobileRibbonGroups.controls.id |
String | 250 个字符 | ✔️ | 指定控件的 ID,例如 msgReadFunctionButton 。 |
tabs.customMobileRibbonGroups.controls.type |
字符串枚举 | ✔️ | 指定控件的类型。 支持的值: MobileButton |
|
tabs.customMobileRibbonGroups.controls.label |
字符串 | 32 个字符 | ✔️ | 指定控件上的标签。 |
tabs.customMobileRibbonGroups.controls.actionId |
字符串 | 64 个字符 | ✔️ | 指定用户选择控件时所执行的操作的 ID。 必须与 actionId 对象中runtimes 操作的 属性匹配runtime.actions.id 。 |
tabs.customMobileRibbonGroups.controls.icons |
Array | 9 | ✔️ | 指定控件上显示的图标,具体取决于移动设备屏幕的尺寸和 DPI。 必须正好有 9 个图标。 |
tabs.customMobileRibbonGroups.controls.icons.size |
数字枚举 | ✔️ | 图标的大小(以像素为单位)。 所需大小为 25、32 和 48。 对于图标 scale 属性的每个可能值,每个大小必须正好有一个。 |
|
tabs.customMobileRibbonGroups.controls.icons.url |
String | 2048 个字符 | ✔️ | 图标图像文件的完整绝对 URL。 |
tabs.customMobileRibbonGroups.controls.icons.scale |
数字枚举 | ✔️ | 指定 iOS 设备的 UIScreen.scale 属性。 可能的值为 1、2 和 3。 对于图标 size 属性的每个可能值,每个值必须正好有一个。 |
若要使用 extensions.ribbons
,请参阅 创建外接程序命令、 为任务窗格命令配置 UI 以及 为函数命令配置 UI。
extensions.autoRunEvents
可选 - 数组
属性 extensions.autoRunEvents
定义基于事件的激活扩展点。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
events |
Array | 20 | ✔️ | 配置导致 Outlook 外接程序中的操作自动运行的事件。 例如,请参阅 在 Outlook 外接程序中使用智能警报和 OnMessageSend 和 OnAppointmentSend 事件。 |
events.type |
字符串 | 64 个字符 | ✔️ | 指定要事件的类型。 有关支持的类型,请参阅 支持的事件。 |
events.actionId |
字符串 | 64 个字符 | ✔️ | 标识触发事件时执行的操作。 必须与 actionId 匹配 runtime.actions.id 。 |
events.options |
Object | 配置 Outlook 如何响应事件。 | ||
events.options.sendMode |
String | ✔️ | 指定要在邮件发送操作期间执行的操作。 支持的值: promptUser 、 softBlock 、 block 。 有关详细信息,请参阅 可用的发送模式选项。 |
|
requirements |
Object | 指定作用域、formFactors 和 Office JavaScript 库要求集,这些要求集必须在 Office 客户端上受支持才能运行事件处理代码。 有关详细信息,请参阅 Microsoft 365 的统一清单中的指定 Office 外接程序要求。 | ||
requirements.capabilities |
Array | 标识要求集。 选项: name (必需) 、 minVersion maxVersion |
||
requirements.capabilities.name |
String | ✔️ | 标识要求集的名称。 | |
requirements.capabilities.minVersion |
String | 标识要求集的最低版本。 | ||
requirements.capabilities.maxVersion |
String | 标识要求集的最大版本。 | ||
requirements.scopes |
枚举数组 | 1 | 标识加载项可在其中运行的范围,并定义扩展可在其中运行的Microsoft 365 应用程序。 例如, mail (Outlook) 。 支持的值: mail |
|
requirements.formFactors |
枚举数组 | 标识支持加载项的外形规格。 支持的值: mobile 、 desktop |
extensions.alternates
可选 - 数组
当你发布了具有重叠功能的多个加载项时,属性 extensions.alternates
用于隐藏特定的市场内加载项或确定其优先级。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
prefer |
Object | 指定与等效 COM 加载项和/或 XLL 加载项的向后兼容性。 | ||
prefer.comAddin |
Object | 指定一个 COM 加载项,该外接程序必须用于代替适用于 Windows 的 Microsoft 365 Web 外接程序。 | ||
prefer.comAddin.progId |
字符串 | 64 个字符 | ✔️ | 标识可在其中运行扩展的应用程序类型。 |
hide |
Object | 配置如何隐藏在安装加载项时发布的另一个加载项,以便用户不会在 Microsoft 365 UI 中看到这两者。 例如,如果之前发布了使用旧 XML 应用清单的外接程序,并且将其替换为使用新 JSON 应用清单的版本,请使用此属性。 | ||
hide.storeOfficeAddin |
Object | 指定 Microsoft AppSource 中可用的Microsoft 365 加载项。 | ||
hide.storeOfficeAddin.officeAddinId |
字符串 | 64 个字符 | ✔️ | 指定要隐藏的市场内外接程序的 ID。 如果市场中的外接程序使用 JSON 应用清单 id ,则 GUID 取自应用清单属性。 如果市场内外接程序使用 XML 应用清单, <Id> 则 GUID 取自 元素。 |
hide.storeOfficeAddin.assetId |
字符串 | 64 个字符 | ✔️ | 指定要隐藏的市场内外接程序的 AppSource 资产 ID。 |
hide.customOfficeAddin |
Object | 配置如何隐藏未通过 AppSource 分发的市场内加载项。 | ||
hide.customOfficeAddin.officeAddinId |
字符串 | 64 个字符 | ✔️ | 指定要隐藏的市场内外接程序的 ID。 如果市场中的外接程序使用 JSON 应用清单 id ,则 GUID 取自应用清单属性。 如果市场内外接程序使用 XML 应用清单, <Id> 则 GUID 取自 元素。 |
requirements |
Object | 指定在 Office 客户端上必须支持的作用域、formFactors 和 Office JavaScript 库要求集,以便 hide 、 prefer 或 alternateIcons 属性生效。 有关详细信息,请参阅 Microsoft 365 的统一清单中的指定 Office 外接程序要求。 |
||
requirements.capabilities |
Array | 标识要求集。 选项: name (必需) 、 minVersion maxVersion |
||
requirements.capabilities.name |
String | ✔️ | 标识要求集的名称。 | |
requirements.capabilities.minVersion |
String | 标识要求集的最低版本。 | ||
requirements.capabilities.maxVersion |
String | 标识要求集的最大版本。 | ||
requirements.scopes |
枚举数组 | 1 | 标识加载项可在其中运行的范围,并定义扩展可在其中运行的Microsoft 365 应用程序。 例如, mail (Outlook) 。 支持的值: mail |
|
requirements.formFactors |
枚举数组 | 标识支持加载项的外形规格。 支持的值: mobile 、 desktop |
||
alternateIcons |
Object | 指定用于在旧版 Office 上表示加载项的main图标。 如果要在 Mac 版 Office 中安装 Office 加载项、永久 Office 许可证和 Microsoft 365 订阅版本的 Office(早于 2304 (内部版本 16320.00000) ),则需要此属性。 | ||
alternateIcons.icon |
Object | ✔️ | 指定用于表示外接程序的图像文件的属性。 | |
alternateIcons.icon.size |
数字枚举 | ✔️ | 指定图标的大小(以像素为单位),枚举为 16 、20 、24 、32 40 、48 、64 80 。 所需的映像大小: 16 、 32 、 80 。 |
|
alternateIcons.icon.url |
String | 2048 个字符 | ✔️ | 指定用于表示外接程序的图像文件的完整绝对 URL。 图标图像必须为 64 x 64 像素,并使用以下文件格式之一:GIF、JPG、PNG、EXIF、BMP、TIFF。 |
alternateIcons.highResolutionIcon |
Object | ✔️ | 指定用于在高 DPI 屏幕上表示加载项的图像文件的属性。 | |
alternateIcons.highResolutionIcon.size |
数字枚举 | ✔️ | 指定图标的大小(以像素为单位),枚举为 16 、20 、24 、32 40 、48 、64 80 。 所需的映像大小: 16 、 32 、 80 。 |
|
alternateIcons.highResolutionIcon.url |
String | 2048 个字符 | ✔️ | 指定用于在高 DPI 屏幕上表示加载项的图像文件的完整绝对 URL。 图标图像必须为 128 x 128 像素,并使用以下文件格式之一:GIF、JPG、PNG、EXIF、BMP、TIFF。 |
dashboardCards
可选 - 数组
定义可固定到仪表板(如Microsoft Viva Connections)的卡片列表,以提供应用信息的汇总视图。 若要详细了解如何为Viva Connections仪表板创建卡片,请参阅 Bot Powered Adaptive Card 扩展概述。
此项是 类型的object
元素的dashboardCard
数组。
dashboardCards.dashboardCard
定义单个仪表板 卡及其属性。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
id |
String | ✔️ | 此仪表板 卡的唯一标识符。 ID 必须是 GUID。 | |
displayName |
String | 255 个字符 | ✔️ | 卡的显示名称。 |
description |
String | 255 个字符 | ✔️ | 卡的说明。 |
pickerGroupId |
String | ✔️ | 卡选取器中组的 ID。 ID 必须是 GUID。 | |
icon |
Object | 指定卡的图标。 | ||
contentSource |
Object | ✔️ | 指定卡内容的源 | |
defaultSize |
String | ✔️ | 仪表板 卡的呈现大小。 选项: medium 或 large 。 |
dashboardCards.dashboardCard.icon
定义给定仪表板 卡的图标属性。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
iconUrl |
字符串 | 2048 个字符 | 要显示在工具箱和卡栏中的卡图标的位置。 | |
officeUIFabricIconName |
String | 255 个字符 | 卡的 Office UI Fabric 或 Fluent UI 图标的友好名称。 如果未 iconUrl 指定 ,则使用此值。 |
dashboardCards.dashboardCard.contentSource
定义给定仪表板 卡的内容源。
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
sourceType |
String | 表示卡内容的源。 选项: bot 。 |
||
botConfiguration |
Object | 机器人源的配置。 如果 设置为 bot ,sourceType 则为 必需。 |
dashboardCards.dashboardCard.contentSource.botConfiguration
名称 | 类型 | 最大大小 | 必需 | 说明 |
---|---|---|---|---|
botId |
String | 使用 Bot Framework 注册的自动程序的唯一 Microsoft 应用 ID。 ID 必须是 GUID。 |
创建应用清单文件
如果你的应用没有应用清单文件,则需要创建它。
若要创建应用清单文件,请执行以下操作:
- 使用 示例应用清单架构 创建.json文件。
- 将其作为
manifest.json
保存在项目文件夹的根目录中。
下面是启用了 SSO 的选项卡应用的应用清单架构示例:
注意
此处显示的应用清单示例内容仅适用于选项卡应用。 它使用子域 URI 的示例值。 有关详细信息,请参阅 示例应用清单架构。
{
"$schema": "https://developer.microsoft.com/json-schemas/teams/v1.11/MicrosoftTeams.schema.json",
"manifestVersion": "1.12",
"version": "1.0.0",
"id": "{new GUID for this Teams app - not the Microsoft Entra App ID}",
"developer": {
"name": "Microsoft",
"websiteUrl": "https://www.microsoft.com",
"privacyUrl": "https://www.microsoft.com/privacy",
"termsOfUseUrl": "https://www.microsoft.com/termsofuse"
},
"name": {
"short": "Teams Auth SSO",
"full": "Teams Auth SSO"
},
"description": {
"short": "Teams Auth SSO app",
"full": "The Teams Auth SSO app"
},
"icons": {
"outline": "outline.png",
"color": "color.png"
},
"accentColor": "#60A18E",
"staticTabs": [
{
"entityId": "auth",
"name": "Auth",
"contentUrl": "https://subdomain.example.com/Home/Index",
"scopes": [ "personal" ]
}
],
"configurableTabs": [
{
"configurationUrl": "https://subdomain.example.com/Home/Configure",
"canUpdateConfiguration": true,
"scopes": [
"team"
]
}
],
"permissions": [ "identity", "messageTeamMembers" ],
"validDomains": [
"{subdomain or ngrok url}"
],
"webApplicationInfo": {
"id": "{Microsoft Entra AppId}",
"resource": "api://subdomain.example.com/{Microsoft Entra AppId}"
}
}