创建团队

命名空间:microsoft.graph

新建团队

注意

创建团队时,常规频道的 SharePoint 网站可能无法预配。 如果站点在 5 分钟后无法预配,请使用 Get filesFolder API 触发预配。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

要调用此 API,需要以下权限之一。 若要了解详细信息,包括如何选择权限的信息,请参阅权限

权限类型 权限(从最低特权到最高特权)
委派(工作或学校帐户) Team.Create、Group.ReadWrite.All**、Directory.ReadWrite.All**
委派(个人 Microsoft 帐户) 不支持。
应用程序 Team.Create、Teamwork.Migrate.All、Group.ReadWrite.All**、Directory.ReadWrite.All**

注意:Teamwork.Migrate.All 权限支持迁移。 将来,Microsoft 可能要求你或你的客户根据导入的数据量支付其他费用。

Note: 仅支持使用 ** 标记的权限以实现向后兼容。 建议更新解决方案,以使用上表中列出的替代权限,并避免今后使用这些权限。

HTTP 请求

POST /teams

请求标头

标头
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-Type application/json. 必需。

请求正文

在请求正文中,提供 team 对象的 JSON 表示形式。

响应

如果成功,则此 API 将返回包含 teamsAsyncOperation 链接的 202 Accepted 响应。

示例

示例 1:委派权限

下面是最小请求的示例。 通过省略其他属性,客户端可以隐式采用 template 表示的预定义模板的默认值。

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
  "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "displayName": "My Sample Team",
  "description": "My Sample Team’s Description"
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0

示例 2:应用权限

下面是使用应用程序权限的最小请求示例。 通过省略其他属性,客户端可以隐式采用 template 表示的预定义模板的默认值。 通过应用程序权限发出请求时,必须在 members 集合中指定用户

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
   "template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
   "displayName":"My Sample Team",
   "description":"My Sample Team’s Description",
   "members":[
      {
         "@odata.type":"#microsoft.graph.aadUserConversationMember",
         "roles":[
            "owner"
         ],
         "user@odata.bind":"https://graph.microsoft.com/v1.0/users('0040b377-61d8-43db-94f5-81374122dc7e')"
      }
   ]
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0

示例 3:通过委派的权限,创建一个包含多个频道、安装了应用且固定有选项卡的团队。

下面是具有完整有效负载的请求。 客户端可以覆盖基础模板中的值,并将数组值项添加到 specialization 的验证规则允许的区间。

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
    "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
    "visibility": "Private",
    "displayName": "Sample Engineering Team",
    "description": "This is a sample engineering team, used to showcase the range of properties supported by this API",
    "channels": [
        {
            "displayName": "Announcements 📢",
            "isFavoriteByDefault": true,
            "description": "This is a sample announcements channel that is favorited by default. Use this channel to make important team, product, and service announcements."
        },
        {
            "displayName": "Training 🏋️",
            "isFavoriteByDefault": true,
            "description": "This is a sample training channel, that is favorited by default, and contains an example of pinned website and YouTube tabs.",
            "tabs": [
                {
                    "teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.web')",
                    "displayName": "A Pinned Website",
                    "configuration": {
                        "contentUrl": "https://learn.microsoft.com/microsoftteams/microsoft-teams"
                    }
                },
                {
                    "teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.youtube')",
                    "displayName": "A Pinned YouTube Video",
                    "configuration": {
                        "contentUrl": "https://tabs.teams.microsoft.com/Youtube/Home/YoutubeTab?videoId=X8krAMdGvCQ",
                        "websiteUrl": "https://www.youtube.com/watch?v=X8krAMdGvCQ"
                    }
                }
            ]
        },
        {
            "displayName": "Planning 📅 ",
            "description": "This is a sample of a channel that is not favorited by default, these channels will appear in the more channels overflow menu.",
            "isFavoriteByDefault": false
        },
        {
            "displayName": "Issues and Feedback 🐞",
            "description": "This is a sample of a channel that is not favorited by default, these channels will appear in the more channels overflow menu."
        }
    ],
    "memberSettings": {
        "allowCreateUpdateChannels": true,
        "allowDeleteChannels": true,
        "allowAddRemoveApps": true,
        "allowCreateUpdateRemoveTabs": true,
        "allowCreateUpdateRemoveConnectors": true
    },
    "guestSettings": {
        "allowCreateUpdateChannels": false,
        "allowDeleteChannels": false
    },
    "funSettings": {
        "allowGiphy": true,
        "giphyContentRating": "Moderate",
        "allowStickersAndMemes": true,
        "allowCustomMemes": true
    },
    "messagingSettings": {
        "allowUserEditMessages": true,
        "allowUserDeleteMessages": true,
        "allowOwnerDeleteMessages": true,
        "allowTeamMentions": true,
        "allowChannelMentions": true
    },
    "discoverySettings": {
        "showInTeamsSearchAndSuggestions": true
    },
    "installedApps": [
        {
            "teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.vsts')"
        },
        {
            "teamsApp@odata.bind": "https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('1542629c-01b3-4a6d-8f76-1938b779e48d')"
        }
    ]
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('958e8cf8-169a-42aa-8599-5c1c5479c0ca')/operations('00000000-0000-0000-0000-000000000000')
Content-Location: /teams('958e8cf8-169a-42aa-8599-5c1c5479c0ca')
Content-Length: 0

示例 4:通过组来创建团队

下面的示例展示了你可如何在给定 groupId 的情况下通过来创建团队

此调用需注意以下几点:

  • 要创建团队,从中创建团队的组必须至少有一名所有者。
  • 所创建的团队将始终从组的显示名称、可见性、规范和成员继承。 因此,使用 group@odata.bind 属性进行此调用时,包含团队 displayNamevisibilityspecializationmembers@odata.bind 属性将返回错误。
  • 如果在不到 15 分钟之前创建组,则可能会因为重复延迟导致“创建团队呼叫”失败并显示错误代码 404。 建议重试创建团队呼叫三次,两次通话延迟为 10 秒。

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
  "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "group@odata.bind": "https://graph.microsoft.com/v1.0/groups('71392b2f-1765-406e-86af-5907d9bdb2ab')"
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('71392b2f-1765-406e-86af-5907d9bdb2ab')/operations('9698b2b8-9636-4f49-b7a8-10dadfa7062a')
Content-Location: /teams('71392b2f-1765-406e-86af-5907d9bdb2ab')
Content-Length: 0

示例 5:通过组创建一个包含多个频道、安装了应用且固定有选项卡的团队

下面是一个请求,该请求转换具有扩展属性的现有组,该组将创建具有多个频道、已安装应用和固定选项卡的团队。

若要了解有关受支持的基本模板类型和受支持的属性的更多信息,请参阅 Teams 模板入门

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
   "template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
   "group@odata.bind":"https://graph.microsoft.com/v1.0/groups('dbd8de4f-5d47-48da-87f1-594bed003375')",
   "channels":[
      {
         "displayName":"Class Announcements 📢",
         "isFavoriteByDefault":true
      },
      {
         "displayName":"Homework 🏋️",
         "isFavoriteByDefault":true
      }
   ],
   "memberSettings":{
      "allowCreateUpdateChannels":false,
      "allowDeleteChannels":false,
      "allowAddRemoveApps":false,
      "allowCreateUpdateRemoveTabs":false,
      "allowCreateUpdateRemoveConnectors":false
   },
   "installedApps":[
      {
         "teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.vsts')"
      },
      {
         "teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('1542629c-01b3-4a6d-8f76-1938b779e48d')"
      }
   ]
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0

示例 6:创建具有非标准基本模板类型的团队

基本模板类型是 Microsoft 为特定行业创建的特殊模板。 这些基本模板通常包含 Microsoft Teams 模板中尚不支持的应用商店中不可用的专有应用和团队属性。

若要从非标准基本模板创建团队,需要将 template@odata.bind 请求正文中的 属性从 standard 更改为要创建的特定基本模板。

若要了解有关受支持的基本模板类型的更多信息,请参阅 Teams 模板入门

注意

Teams 用户最长可能需要 24 小时才能在库中查看自定义模板更改。

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
  "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('educationClass')",
  "displayName": "My Class Team",
  "description": "My Class Team’s Description"
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0

示例 7:通过扩展属性创建具有非标准基本模板类型的团队

基本模板类型可以使用其他属性进行扩展,使你可以使用其他团队设置、渠道、应用或选项卡构建现有基本模板。

若要了解有关受支持的基本模板类型和受支持的属性的更多信息,请参阅 Teams 模板入门

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
   "template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('educationClass')",
   "displayName":"My Class Team",
   "description":"My Class Team’s Description",
   "channels":[
      {
         "displayName":"Class Announcements 📢",
         "isFavoriteByDefault":true
      },
      {
         "displayName":"Homework 🏋️",
         "isFavoriteByDefault":true
      }
   ],
   "memberSettings":{
      "allowCreateUpdateChannels":false,
      "allowDeleteChannels":false,
      "allowAddRemoveApps":false,
      "allowCreateUpdateRemoveTabs":false,
      "allowCreateUpdateRemoveConnectors":false
   },
   "installedApps":[
      {
         "teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('com.microsoft.teamspace.tab.vsts')"
      },
      {
         "teamsApp@odata.bind":"https://graph.microsoft.com/v1.0/appCatalogs/teamsApps('1542629c-01b3-4a6d-8f76-1938b779e48d')"
      }
   ]
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0

示例 8:创建处于迁移模式的团队

请求

以下示例演示如何创建用于导入消息的团队。

注意:将来,Microsoft 可能根据导入的数据量要求你或你的客户支付其他费用。

注意: 在迁移模式下创建的 Teams 仅支持 standard 模板。

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
  "@microsoft.graph.teamCreationMode": "migration",
  "template@odata.bind": "https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
  "displayName": "My Sample Team",
  "description": "My Sample Team’s Description",
  "createdDateTime": "2020-03-14T11:22:17.067Z"
}

响应

HTTP/1.1 202 Accepted
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')

错误响应

如果该请求成功,此方法返回 400 Bad Request 响应代码。

400 Bad Request

下面是出现此响应的常见原因:

  • createdDateTime 将在未来设置。
  • 正确指定了 createdDateTime,但缺少 teamCreationMode 实例属性或者将其设置成了无效值。

示例 9:使用用户主体名称的应用程序权限

下面是使用应用程序权限的最小请求示例。 通过省略其他属性,客户端可以隐式采用 template 表示的预定义模板的默认值。 通过应用程序权限发出请求时,必须在 members 集合中指定用户

请求

POST https://graph.microsoft.com/v1.0/teams
Content-Type: application/json

{
   "template@odata.bind":"https://graph.microsoft.com/v1.0/teamsTemplates('standard')",
   "displayName":"My Sample Team",
   "description":"My Sample Team’s Description",
   "members":[
      {
         "@odata.type":"#microsoft.graph.aadUserConversationMember",
         "roles":[
            "owner"
         ],
         "user@odata.bind":"https://graph.microsoft.com/v1.0/users('jacob@contoso.com')"
      }
   ]
}

响应

HTTP/1.1 202 Accepted
Content-Type: application/json
Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')/operations('3a6fdce1-c261-48bc-89de-1cfef658c0d5')
Content-Location: /teams('dbd8de4f-5d47-48da-87f1-594bed003375')
Content-Length: 0