Skip to content

Commit 8c187f6

Browse files
LauragraLauragra
authored
Merge pull request #25141 from microsoftgraph/users/prachigiyal/bulkDeleteTeamMembers
Bulk delete team members API in beta
2 parents 4d36d88 + f522ea3 commit 8c187f6

File tree

9 files changed

+291
-25
lines changed

9 files changed

+291
-25
lines changed

‎api-reference/beta/api/conversationmember-remove.md

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
---
2+
title: "conversationMember: remove"
3+
description: "Remove members in bulk from a team."
4+
author: "prachigoyal-ms"
5+
doc_type: "apiPageType"
6+
ms.localizationpriority: high
7+
ms.subservice: "teams"
8+
---
9+
10+
# conversationMember: remove
11+
12+
Namespace: microsoft.graph
13+
14+
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
15+
16+
Remove multiple members from a [team](../resources/team.md) in a single request. The response provides details about which memberships could and couldn't be removed.
17+
18+
[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
19+
20+
## Permissions
21+
22+
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
23+
24+
<!-- { "blockType": "permissions", "name": "conversationmember_remove" } -->
25+
[!INCLUDE [permissions-table](../includes/permissions/conversationmember-remove-permissions.md)]
26+
27+
28+
## HTTP request
29+
30+
This is a bound action to remove multiple elements from a [conversationMember](../resources/conversationmember.md) collection in a single request.
31+
<!-- { "blockType": "ignored" } -->
32+
33+
```http
34+
POST /teams/{team-id}/members/remove
35+
```
36+
37+
## Request headers
38+
39+
| Header | Value |
40+
| :------------ | :------------------------ |
41+
|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
42+
| Content-Type | application/json. Required. |
43+
44+
## Request body
45+
46+
In the request body, supply the JSON representation of the list of **conversationMember** derivatives to be removed from a team. A maximum of 20 **conversationMember** derivatives can be removed in a single request.
47+
48+
The following table shows the parameter that you can use with this method.
49+
50+
|Parameter|Type|Description|
51+
|:---|:---|:---|
52+
|values|[conversationMember](../resources/conversationmember.md) collection|A list of conversation members that should be removed.|
53+
54+
## Response
55+
56+
If successful, this method returns either a `204 No Content` response if all specified members were successfully removed from the team or a `207 Multi-Status` response if only some members were removed. The caller should inspect the response payload to identify which member removals failed. The response body contains a collection of derivatives of the [actionResultPart](../resources/actionresultpart.md) resource. If the request fails, the API returns an error. For more information about Microsoft Graph errors, see [Microsoft Graph error responses and resource types](/graph/errors).
57+
58+
## Examples
59+
60+
### Example 1: Remove members in bulk from a team
61+
62+
The following example shows how to remove multiple members from a **team** in a single request.
63+
64+
#### Request
65+
66+
The following example shows a request.
67+
68+
<!-- {
69+
"blockType": "request",
70+
"name": "bulkremovemembers_team"
71+
}-->
72+
73+
```http
74+
POST https://graph.microsoft.com/beta/teams/e4183b04-c9a2-417c-bde4-70e3ee46a6dc/members/remove
75+
Content-Type: application/json
76+
77+
{
78+
"values": [
79+
{
80+
"@odata.type": "microsoft.graph.aadUserConversationMember",
81+
"user@odata.bind": "https://graph.microsoft.com/beta/users('18a80140-b0fb-4489-b360-2f6efaf225a0')"
82+
},
83+
{
84+
"@odata.type": "microsoft.graph.aadUserConversationMember",
85+
"user@odata.bind": "https://graph.microsoft.com/beta/users('86503198-b81b-43fe-81ee-ad45b8848ac9')"
86+
}
87+
]
88+
}
89+
```
90+
91+
#### Response
92+
93+
The following example shows the response.
94+
95+
<!-- {
96+
"blockType": "response",
97+
"truncated": false
98+
} -->
99+
100+
```http
101+
HTTP/1.1 204 No Content
102+
```
103+
104+
### Example 2: Remove members in bulk from a team using user principal name
105+
106+
The following example shows how to remove multiple members from a **team** in a single request using their user principal names.
107+
108+
#### Request
109+
110+
The following example shows a request.
111+
112+
<!-- {
113+
"blockType": "request",
114+
"name": "bulkdeletemembers_team_upn"
115+
}-->
116+
117+
```http
118+
POST https://graph.microsoft.com/beta/teams/e4183b04-c9a2-417c-bde4-70e3ee46a6dc/members/remove
119+
Content-Type: application/json
120+
121+
{
122+
"values": [
123+
{
124+
"@odata.type": "microsoft.graph.aadUserConversationMember",
125+
"user@odata.bind": "https://graph.microsoft.com/beta/users('jacob@contoso.com')"
126+
},
127+
{
128+
"@odata.type": "microsoft.graph.aadUserConversationMember",
129+
"user@odata.bind": "https://graph.microsoft.com/beta/users('alex@contoso.com')"
130+
}
131+
]
132+
}
133+
```
134+
135+
#### Response
136+
137+
The following example shows the response.
138+
139+
<!-- {
140+
"blockType": "response",
141+
"truncated": false
142+
} -->
143+
144+
```http
145+
HTTP/1.1 204 No Content
146+
```
147+
148+
### Example 3: Remove members in bulk from a team with failed removals
149+
150+
The following example shows how to remove multiple members from a **team** when the removal of a member fails.
151+
152+
#### Request
153+
154+
The following example shows a request.
155+
156+
<!-- {
157+
"blockType": "request",
158+
"name": "bulkdeletemembers_team_partial"
159+
}-->
160+
161+
```http
162+
POST https://graph.microsoft.com/beta/teams/e4183b04-c9a2-417c-bde4-70e3ee46a6dc/members/remove
163+
Content-Type: application/json
164+
165+
{
166+
"values": [
167+
{
168+
"@odata.type": "microsoft.graph.aadUserConversationMember",
169+
"user@odata.bind": "https://graph.microsoft.com/beta/users('c04f28bf-ab68-40a2-974b-e6af31fa78fb')"
170+
},
171+
{
172+
"@odata.type": "microsoft.graph.aadUserConversationMember",
173+
"user@odata.bind": "https://graph.microsoft.com/beta/users('86503198-b81b-43fe-81ee-ad45b8848ac9')"
174+
}
175+
]
176+
}
177+
```
178+
179+
#### Response
180+
181+
The following example shows the response.
182+
183+
> **Note:** The response object shown here might be shortened for readability.
184+
<!-- {
185+
"blockType": "response",
186+
"truncated": true,
187+
"@odata.type": "Collection(microsoft.graph.actionResultPart)"
188+
} -->
189+
190+
```http
191+
HTTP/1.1 207 Multi-Status
192+
Content-Type: application/json
193+
194+
{
195+
"@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(microsoft.graph.aadUserConversationMemberResult)",
196+
"value": [
197+
{
198+
"@odata.type": "#microsoft.graph.aadUserConversationMemberResult",
199+
"userId": "c04f28bf-ab68-40a2-974b-e6af31fa78fb",
200+
"error": {
201+
"code": "NotFound",
202+
"message": "Could not find resource"
203+
}
204+
},
205+
{
206+
"@odata.type": "#microsoft.graph.aadUserConversationMemberResult",
207+
"userId": "86503198-b81b-43fe-81ee-ad45b8848ac9",
208+
"error": null
209+
}
210+
]
211+
}
212+
```
213+
214+
## Related content
215+
216+
[Remove member from team](team-delete-members.md)
217+
218+
<!-- uuid: 8fcb5dbc-d5aa-4681-8e31-b001d5168d79
219+
2024-09-12 06:02:30 UTC -->
220+
<!--
221+
{
222+
"type": "#page.annotation",
223+
"description": "Remove members from a team in bulk.",
224+
"keywords": "",
225+
"section": "documentation",
226+
"tocPath": "",
227+
"suppressions": []
228+
}
229+
-->

‎api-reference/beta/includes/permissions/conversationmember-remove-permissions.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
description: "Automatically generated file. DO NOT MODIFY"
3+
ms.topic: include
4+
ms.localizationpriority: medium
5+
---
6+
7+
|Permission type|Least privileged permissions|Higher privileged permissions|
8+
|:---|:---|:---|
9+
|Delegated (work or school account)|TeamMember.ReadWrite.All|Not available.|
10+
|Delegated (personal Microsoft account)|Not supported.|Not supported.|
11+
|Application|TeamMember.ReadWrite.All|Not available.|

‎api-reference/beta/resources/aaduserconversationmember.md

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "aadUserConversationMember resource type"
3-
description: "Represents a Microsoft Entra user in a chat or channel."
3+
description: "Represents a Microsoft Entra user in a team, a channel, or a chat. "
44
ms.localizationpriority: high
55
author: "akjo"
66
ms.subservice: "teams"
@@ -13,7 +13,9 @@ Namespace: microsoft.graph
1313

1414
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
1515

16-
Represents a Microsoft Entra user in a [team](team.md) or a [channel](channel.md) or a [chat](chat.md). This type inherits from [conversationMember](conversationmember.md).
16+
Represents a Microsoft Entra user in a [team](team.md), a [channel](channel.md), or a [chat](chat.md).
17+
18+
Inherits from [conversationMember](conversationmember.md).
1719

1820
## Methods
1921

@@ -25,6 +27,7 @@ Represents a Microsoft Entra user in a [team](team.md) or a [channel](channel.md
2527
|[Get team member](../api/team-get-members.md) | [conversationMember](conversationmember.md) collection | Get a member in the team.|
2628
|[Update team member's role](../api/team-update-members.md)|[conversationMember](../resources/conversationmember.md)|Change a member to an owner or back to a regular member.|
2729
|[Remove team member](../api/team-delete-members.md)|None|Remove an existing member from the team.|
30+
|[Remove team members in bulk](../api/conversationmember-remove.md)|[actionResultPart](../resources/actionresultpart.md) collection|Remove multiple members from a team in a single request.|
2831
|[List channel members](../api/channel-list-members.md) | [conversationMember](conversationmember.md) collection | Get the list of all members in a channel.|
2932
|[Add channel member](../api/channel-post-members.md) | [conversationMember](conversationmember.md) | Add a member to a channel. Only supported for `channel` with membershipType of `private`.|
3033
|[Get channel member](../api/channel-get-members.md) | [conversationMember](conversationmember.md) collection | Get a member in a channel.|
@@ -39,12 +42,12 @@ Represents a Microsoft Entra user in a [team](team.md) or a [channel](channel.md
3942

4043
| Property | Type |Description|
4144
|:---------------|:--------|:----------|
42-
|id| String | Read-only. Unique ID of the user.|
4345
|displayName| String | The display name of the user. |
44-
|roles| String collection | The roles of the user such as owner, member, or guest. |
45-
|userId| String | The GUID of the user. |
4646
|email| String | The email address of the user. |
47+
|id| String | Read-only. Unique ID of the user.|
48+
|roles| String collection | The roles of the user such as owner, member, or guest. |
4749
|tenantId| string | TenantId which the Microsoft Entra user belongs to. |
50+
|userId| String | The GUID of the user. |
4851
|visibleHistoryStartDateTime| DateTimeOffset | The timestamp denoting how far back a conversation's history is shared with the conversation member. This property is settable only for members of a chat.|
4952

5053
## JSON representation
@@ -61,16 +64,14 @@ The following JSON representation shows the resource type.
6164
-->
6265
``` json
6366
{
64-
"@odata.type": "#microsoft.graph.aadUserConversationMember",
65-
"id": "String (identifier)",
66-
"roles": [
67-
"String"
68-
],
67+
"@odata.type": "#microsoft.graph.aadUserConversationMember",
6968
"displayName": "String",
70-
"visibleHistoryStartDateTime": "String (timestamp)",
71-
"userId": "String",
7269
"email": "String",
73-
"tenantId": "String"
70+
"id": "String (identifier)",
71+
"roles": ["String"],
72+
"tenantId": "String",
73+
"userId": "String",
74+
"visibleHistoryStartDateTime": "String (timestamp)"
7475
}
7576
```
7677

‎api-reference/beta/resources/aaduserconversationmemberresult.md

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,15 @@ Namespace: microsoft.graph
1313

1414
[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
1515

16-
Represents the individual response for each member specified in a bulk operation comprising of [aadUserConversationMember(s)](aadUserConversationMember.md) in the request.
17-
This resource is the derivative of the [actionResultPart](actionresultpart.md) resource.
16+
Represents the individual response for each member specified in a bulk operation that includes [aadUserConversationMember](aaduserconversationmember.md) objects in the request.
17+
18+
Inherits from [actionResultPart](actionresultpart.md).
1819

1920
## Properties
2021

2122
| Property | Type | Description |
2223
|:---------------|:--------|:----------|
23-
|userId|`String`|The user object ID of the Microsoft Entra user that was being added as part of the bulk operation.|
24+
|userId|String|The user object ID of the Microsoft Entra user that was being added as part of the bulk operation.|
2425
|error|[publicError](publicerror.md) |The error that occurred, if any, during the course of the bulk operation.|
2526

2627
## JSON representation
@@ -34,21 +35,22 @@ The following JSON representation shows the resource type.
3435

3536
```json
3637
{
37-
"userId": "string",
38+
"userId": "String",
3839
"error": "microsoft.graph.publicError"
3940
}
4041
```
4142

4243
## Related content
4344

44-
- [Add members in bulk to team](../api/conversationmembers-add.md)
45+
- [Add members in bulk to a team](../api/conversationmembers-add.md)
46+
- [Remove members in bulk from a team](../api/conversationmember-remove.md)
4547

4648
<!-- uuid: 20fd7863-9545-40d4-ae8f-fee2d115a690
4749
2015-10-25 14:57:30 UTC -->
4850
<!--
4951
{
5052
"type": "#page.annotation",
51-
"description": "actionResultPart",
53+
"description": "aadUserConversationMemberResult",
5254
"keywords": "",
5355
"section": "documentation",
5456
"tocPath": "",

‎api-reference/beta/resources/actionresultpart.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,9 @@ The following JSON representation shows the resource type.
4141
```
4242
## Related content
4343

44-
- [aadUserConversationMemberResult](aadUserConversationMemberResult.md)
44+
- [aadUserConversationMemberResult](aaduserconversationmemberresult.md)
4545
- [Add members in bulk to a team](../api/conversationmembers-add.md)
46+
- [Remove members in bulk from a team](../api/conversationmember-remove.md)
4647

4748
<!-- uuid: 20fd7863-9545-40d4-ae8f-fee2d115a690
4849
2015-10-25 14:57:30 UTC -->

‎api-reference/beta/resources/conversationmember.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
---
1+
---
22
title: "conversationMember resource type"
33
description: "Represents a user in a conversation."
44
ms.localizationpriority: medium
@@ -33,6 +33,7 @@ Base type for the following supported conversation member types:
3333
|[Get team member](../api/team-get-members.md) | [conversationMember](conversationmember.md) collection | Get a member in the team.|
3434
|[Update team member's role](../api/team-update-members.md)|[conversationMember](../resources/conversationmember.md)|Change a member to an owner or back to a regular member.|
3535
|[Remove team member](../api/team-delete-members.md)|None|Remove an existing member from the team.|
36+
|[Remove team members in bulk](../api/conversationmember-remove.md)|[actionResultPart](../resources/actionresultpart.md) collection|Remove multiple members from a team in a single request.|
3637
|[List channel members](../api/channel-list-members.md) | [conversationMember](conversationmember.md) collection | Get the list of all members in a channel.|
3738
|[Add channel member](../api/channel-post-members.md) | [conversationMember](conversationmember.md) | Add a member to a channel. Only supported for `channel` with membershipType of `private`.|
3839
|[Get channel member](../api/channel-get-members.md) | [conversationMember](conversationmember.md) collection | Get a member in a channel.|

0 commit comments

Comments
 (0)