名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
セキュリティ グループまたは Microsoft 365 グループにメンバーを追加します。 API を使用して 1 つの要求に複数のメンバーを追加する場合、追加できるメンバーは最大 20 人までです。
注:
この要求には、最近作成されたグループのレプリケーション遅延が発生する可能性があります。 グループが作成されると、オブジェクトが Microsoft Entra ID ディレクトリ レプリカ間で完全にレプリケートされるまでに少し時間がかかることがあります。 この期間中に、グループにメンバーを追加する要求を行うと、"ソース リソース オブジェクトまたは参照されているオブジェクトの 1 つが存在しません" というメッセージを含む400 Bad Requestエラーが返される場合があります。
この動作を軽減するには:
-
少し待ってから再試行 します。数秒待ってから、要求を再試行します。 通常、遅延は短時間です。
詳細については、「Microsoft Entra の最終的整合性の設計」を参照してください。
次の表に、セキュリティ グループまたは Microsoft 365 グループのいずれかに追加できるメンバーの種類を示します。
| オブジェクトの種類 |
セキュリティ グループのメンバー |
Microsoft 365 グループのメンバー |
| User |
|
|
| セキュリティ グループ |
|
|
| Microsoft 365 グループ |
|
|
| デバイス |
|
|
| サービス プリンシパル |
|
|
| 組織の連絡先 |
|
|
この API は、次の国内クラウド展開で使用できます。
| グローバル サービス |
米国政府機関 L4 |
米国政府機関 L5 (DOD) |
21Vianet が運営する中国 |
| ✅ |
✅ |
✅ |
✅ |
アクセス許可
次の表は、この API を呼び出すときに各リソースの種類で必要とされる最低特権のアクセス許可を示しています。 アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。
| サポートされているリソース |
委任 (職場または学校のアカウント) |
委任 (個人用 Microsoft アカウント) |
アプリケーション |
|
device |
GroupMember.ReadWrite.All と Device.Read.All |
サポートされていません。 |
GroupMember.ReadWrite.All および Device.ReadWrite.All |
|
group |
GroupMember.ReadWrite.All |
サポートされていません。 |
GroupMember.ReadWrite.All |
|
orgContact |
GroupMember.ReadWrite.All および OrgContact.Read.All |
サポートされていません。 |
GroupMember.ReadWrite.All および OrgContact.Read.All |
|
servicePrincipal |
GroupMember.ReadWrite.All と Application.ReadWrite.All |
サポートされていません。 |
GroupMember.ReadWrite.All と Application.ReadWrite.All |
|
user |
GroupMember.ReadWrite.All |
サポートされていません。 |
GroupMember.ReadWrite.All |
重要
委任されたシナリオでは、サインインしたユーザーには、サポートされているMicrosoft Entraロールまたはmicrosoft.directory/groups/members/update ロールのアクセス許可を持つカスタム ロールも割り当てられる必要があります。 次のロールは、ロール割り当て可能なグループを除き、この操作でサポートされる最小特権ロールです。
- グループの所有者
- ディレクトリ製作者
- グループ管理者
- Identity Governance 管理者
- ユーザー管理者
- Exchange 管理者 - Microsoft 365 グループのみ
- SharePoint 管理者 - Microsoft 365 グループのみ
- Teams 管理者 - Microsoft 365 グループのみ
- Yammer 管理者 - Microsoft 365 グループのみ
- Intune 管理者 - セキュリティ グループ専用
役割が割り当て可能なグループにメンバーを追加するには、アプリに RoleManagement.ReadWrite.Directory のアクセス許可も割り当てられ、呼び出し元ユーザーにサポートされている Microsoft Entra 役割が割り当てられている必要があります。
特権ロール管理者 は、この操作でサポートされる最小特権ロールです。
HTTP 要求
POST /groups/{group-id}/members/$ref
PATCH /groups/{group-id}
| 名前 |
説明 |
| Authorization |
ベアラー {token}。 必須です。
認証と認可についての詳細をご覧ください。 |
| Content-type |
application/json. 必須です。 |
要求本文
POST /groups/{group-id}/members/$ref構文を使用する場合は、サポートされているグループ メンバー オブジェクト型への ID による参照を含む @odata.id プロパティを含む JSON オブジェクトを指定します。
PATCH /groups/{group-id}構文を使用する場合は、サポートされているグループ メンバー オブジェクトの種類への ID による 1 つ以上の参照を含む members@odata.bind プロパティを含む JSON オブジェクトを指定します。 コードの例を以下に示します。
- Microsoft 365 グループの場合、ユーザーのみが Microsoft 365 グループのメンバーになれるため、
{id}ユーザーがユーザーである必要があるhttps://graph.microsoft.com/v1.0/directoryObjects/{id}とhttps://graph.microsoft.com/v1.0/groups/{id}のみが許可されます。
- セキュリティ グループでは、次の ID 参照を使用できます。
-
https://graph.microsoft.com/v1.0/directoryObjects/{id}
{id}ユーザー、セキュリティ グループ、デバイス、サービス プリンシパル、または組織の連絡先に属している必要があります。
-
https://graph.microsoft.com/v1.0/groups/{id} ここで、 {id} は別のセキュリティ グループに属している必要があります。 Microsoft 365 グループは、セキュリティ グループのメンバーにすることはできません。
-
https://graph.microsoft.com/v1.0/devices/{id}
{id}がデバイスに属している場合。
-
https://graph.microsoft.com/v1.0/servicePrincipal/{id}
{id} がサービス プリンシパルに属している場合。
-
https://graph.microsoft.com/v1.0/orgContact/{id}
{id}が組織の連絡先に属している場合。
応答
成功した場合、このメソッドは 204 No Content 応答コードを返します。 オブジェクトが既にグループのメンバーである場合、グループ メンバーとしてサポートされていない場合、またはグループが最近作成され、完全にレプリケートされていない場合 (エラー メッセージ: "ソース リソース オブジェクトまたは参照されているオブジェクトの 1 つが存在しません。" - 少し待ってから再試行します)、400 Bad Request応答コードが返されます。 追加するオブジェクトが存在しない場合は、 404 Not Found 応答コードを返します。 次のいずれかのシナリオで 403 Forbidden を返します。
-
Microsoft Graph で管理できないグループにメンバーを追加しようとしています。 この API は、セキュリティ グループと Microsoft 365 グループのみをサポートします。
- 追加するアクセス許可がないメンバーを追加しようとしています。 異なるメンバーの種類を追加するために必要なアクセス許可については、前の 「アクセス許可」 セクションを参照してください。
- ロールが割り当て可能なグループにメンバーを追加しようとしていますが、必要なアクセス許可がありません。
例
例 1: グループにメンバーを追加する
要求
次の例は、 directoryObjects 参照を使用してメンバーをグループに追加する要求を示しています。
POST https://graph.microsoft.com/beta/groups/{group-id}/members/$ref
Content-type: application/json
{
"@odata.id": "https://graph.microsoft.com/beta/directoryObjects/{id}"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new ReferenceCreate
{
OdataId = "https://graph.microsoft.com/beta/directoryObjects/{id}",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
await graphClient.Groups["{group-id}"].Members.Ref.PostAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewReferenceCreate()
odataId := "https://graph.microsoft.com/beta/directoryObjects/{id}"
requestBody.SetOdataId(&odataId)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
graphClient.Groups().ByGroupId("group-id").Members().Ref().Post(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
com.microsoft.graph.beta.models.ReferenceCreate referenceCreate = new com.microsoft.graph.beta.models.ReferenceCreate();
referenceCreate.setOdataId("https://graph.microsoft.com/beta/directoryObjects/{id}");
graphClient.groups().byGroupId("{group-id}").members().ref().post(referenceCreate);
const options = {
authProvider,
};
const client = Client.init(options);
const directoryObject = {
'@odata.id': 'https://graph.microsoft.com/beta/directoryObjects/{id}'
};
await client.api('/groups/{group-id}/members/$ref')
.version('beta')
.post(directoryObject);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\ReferenceCreate;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ReferenceCreate();
$requestBody->setOdataId('https://graph.microsoft.com/beta/directoryObjects/{id}');
$graphServiceClient->groups()->byGroupId('group-id')->members()->ref()->post($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Groups
$params = @{
"@odata.id" = "https://graph.microsoft.com/beta/directoryObjects/{id}"
}
New-MgBetaGroupMemberByRef -GroupId $groupId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.reference_create import ReferenceCreate
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ReferenceCreate(
odata_id = "https://graph.microsoft.com/beta/directoryObjects/{id}",
)
await graph_client.groups.by_group_id('group-id').members.ref.post(request_body)
応答
次の例は応答を示しています。
HTTP/1.1 204 No Content
例 2: 1 つの要求でグループに複数のメンバーを追加する
この例は、PATCH 操作で OData バインドがサポートされているグループに複数のメンバーを追加する方法を示しています。 1 回の要求で最大 20 人のメンバーを追加できます。 要求の本文にエラー条件が存在する場合、メンバーは追加されず、適切な応答コードが返されます。
要求
次の例は要求を示しています。
PATCH https://graph.microsoft.com/beta/groups/{group-id}
Content-type: application/json
{
"members@odata.bind": [
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}"
]
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new Group
{
AdditionalData = new Dictionary<string, object>
{
{
"members@odata.bind" , new List<string>
{
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
}
},
},
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Groups["{group-id}"].PatchAsync(requestBody);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
//other-imports
)
requestBody := graphmodels.NewGroup()
additionalData := map[string]interface{}{
odataBind := []string {
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
}
}
requestBody.SetAdditionalData(additionalData)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
groups, err := graphClient.Groups().ByGroupId("group-id").Patch(context.Background(), requestBody, nil)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
Group group = new Group();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
LinkedList<String> membersOdataBind = new LinkedList<String>();
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
membersOdataBind.add("https://graph.microsoft.com/beta/directoryObjects/{id}");
additionalData.put("members@odata.bind", membersOdataBind);
group.setAdditionalData(additionalData);
Group result = graphClient.groups().byGroupId("{group-id}").patch(group);
const options = {
authProvider,
};
const client = Client.init(options);
const group = {
'members@odata.bind': [
'https://graph.microsoft.com/beta/directoryObjects/{id}',
'https://graph.microsoft.com/beta/directoryObjects/{id}',
'https://graph.microsoft.com/beta/directoryObjects/{id}'
]
};
await client.api('/groups/{group-id}')
.version('beta')
.update(group);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\Group;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new Group();
$additionalData = [
'members@odata.bind' => [
'https://graph.microsoft.com/beta/directoryObjects/{id}', 'https://graph.microsoft.com/beta/directoryObjects/{id}', 'https://graph.microsoft.com/beta/directoryObjects/{id}', ],
];
$requestBody->setAdditionalData($additionalData);
$result = $graphServiceClient->groups()->byGroupId('group-id')->patch($requestBody)->wait();
Import-Module Microsoft.Graph.Beta.Groups
$params = @{
"members@odata.bind" = @(
"https://graph.microsoft.com/beta/directoryObjects/{id}"
"https://graph.microsoft.com/beta/directoryObjects/{id}"
"https://graph.microsoft.com/beta/directoryObjects/{id}"
)
}
Update-MgBetaGroup -GroupId $groupId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.group import Group
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Group(
additional_data = {
"members@odata_bind" : [
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
"https://graph.microsoft.com/beta/directoryObjects/{id}",
],
}
)
result = await graph_client.groups.by_group_id('group-id').patch(request_body)
応答
次の例は応答を示しています。
HTTP/1.1 204 No Content
関連コンテンツ