名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
グループ オブジェクトのプロパティを更新する。
注:
members@odata.bind を使用して PATCH 経由でメンバーを追加すると、この要求で最近作成されたグループのレプリケーションが遅延する可能性があります。 グループ オブジェクトが Microsoft Entra ID ディレクトリ レプリカ間で完全にレプリケートされるまで、少し時間がかかる場合があります。 この期間中に、グループにメンバーを追加する要求を行うと、"ソース リソース オブジェクトまたは参照されているオブジェクトの 1 つが存在しません" というメッセージを含む400 Bad Requestエラーが返される場合があります。
この動作を軽減するには:
- 少し待ってから再試行 します。数秒待ってから、要求を再試行します。 通常、遅延は短時間です。
詳細については、「Microsoft Entra の最終的整合性の設計」を参照してください。
この API は、次の国内クラウド展開で使用できます。
| グローバル サービス | 米国政府機関 L4 | 米国政府機関 L5 (DOD) | 21Vianet が運営する中国 |
|---|---|---|---|
| ✅ | ✅ | ✅ | ✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。
| アクセス許可の種類 | 最小特権アクセス許可 | より高い特権のアクセス許可 |
|---|---|---|
| 委任 (職場または学校のアカウント) | Group-NestingSupport.ReadWrite.All | Directory.ReadWrite.All、Group-PreferredDataLocation.ReadWrite.All、Group.ManageProtection.All、Group.ReadWrite.All、HardDeletionSetting.ReadWrite.Enable |
| 委任 (個人用 Microsoft アカウント) | サポートされていません。 | サポートされていません。 |
| アプリケーション | Group-NestingSupport.ReadWrite.All | Directory.ReadWrite.All、Group-PreferredDataLocation.ReadWrite.All、Group.ManageProtection.All、Group.ReadWrite.All、HardDeletionSetting.ReadWrite.Enable |
特定のシナリオのアクセス許可
-
isHardDeleteProtectionEnabled を
trueに設定するには、アプリに HardDeletionSetting.ReadWrite.Enable 委任またはアプリケーションのアクセス許可が必要です。 呼び出し元には、Microsoft Entra バックアップ管理者ロールも必要です。 - Group.ManageProtection.All 委任されたアクセス許可は、クラウド セキュリティ グループの assignedLabels プロパティとすべてのグループの writebackConfiguration プロパティを更新するための最小特権アクセス許可です。 アプリのみのシナリオはサポートされていません。
HTTP 要求
PATCH /groups/{id}
要求ヘッダー
| 名前 | 型 | 説明 |
|---|---|---|
| Authorization | string | ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。 |
要求本文
要求本文で、更新すべきプロパティの値のみを指定します。 要求本文に含まれない既存のプロパティは、以前の値のままになるか、他のプロパティ値の変化に基づいて再計算されます。
次の表に、更新できるプロパティを示します。
| プロパティ | 型 | 説明 |
|---|---|---|
| allowExternalSenders | Boolean | 既定値は false です。 組織外部のユーザーがグループにメッセージを送信できるかどうかを示します。 |
| assignedLabels | assignedLabel コレクション | Microsoft 365 グループまたはクラウド セキュリティ グループに関連付けられている秘密度ラベルのペア (ラベル ID、ラベル名) の一覧。 Microsoft Entra ID P1 ライセンスが必要です。 このプロパティは、グループの作成または更新時に指定できます。 ただし、クラウド セキュリティ グループに対しては、一度設定すると変更できません。
|
| autoSubscribeNewMembers | Boolean | 既定値は false です。 グループに追加された新しいメンバーが、電子メールの通知を受信するように自動的にサブスクライブされるかどうかを示します。 グループで subscriptionEnabled が false に設定されている場合、autoSubscribeNewMembers は true になることができません。 |
| 説明 | String | グループに関するオプションの説明。 |
| displayName | 文字列 | グループの表示名。 このプロパティは、グループの作成時の必須プロパティであり、更新時にクリアすることはできません。 |
| isHardDeleteProtectionEnabled | ブール型 | 既存のクラウドのみのグループでハード削除保護を有効にするには、[ true ] に設定します。 一度有効にすると、 false または null に設定することはできません。 保護により、論理的な削除後 7 日間は完全な削除がブロックされます。これは、ソフト削除または復元を防ぐものではありません。 |
| mailNickname | String | 組織内の Microsoft 365 グループに対して一意の、グループのメール エイリアス。 最大文字数は 64 文字です。 このプロパティには、 ASCII 文字セット 0 ~ 127 の文字のみを含めることができます。ただし、以下の @ () \ [] " ; : . <> , SPACEを除いたものです。 |
| preferredDataLocation | String | Microsoft 365 グループのデータの優先される場所。 このプロパティを更新するには、呼び出し元ユーザーに次の Microsoft Entra ロールの少なくとも 1 つが割り当てられている必要があります。
このプロパティの詳細については、「OneDrive Online Multi-Geo」 を参照してください。 |
| securityEnabled | ブール値 | グループがセキュリティ グループ (Microsoft 365 グループを含む) であるかどうかを指定します。 |
| uniqueName | String | グループに割り当てて代替キーとして使用できる一意の識別子。
null場合にのみ更新可能であり、一度設定すると変更できません。 |
| visibility | String | Microsoft 365 グループの表示を指定します。 可能な値は以下のどれかです: Private、Publicまたは empty (これは Publicと解釈されます)。 |
| welcomeMessageEnabled | Boolean | 既定値は true です。 新しいメンバーが Microsoft 365 グループに追加されたときに、ウェルカム メッセージが送信されるかどうかを示します。 |
| writebackConfiguration | groupWritebackConfiguration | グループ オブジェクトのプロパティをオンプレミスの Active Directory に書き戻すようにグループを構成するかどうかを指定します。 これらのプロパティは、グループの書き戻しが Microsoft Entra Connect 同期クライアントで構成されているときに使用されます。 |
重要
- これらのプロパティ (accessType、 allowExternalSenders、 autoSubscribeNewMembers、 hideFromAddressLists、 hideFromOutlookClients、 isFavorite、 isSubscribedByMail、 unseenConversationsCount、 unseenCount、 unseenMessagesCount、 welcomeMessageEnabled) を更新するには、次の操作を行う必要があります。
- 前の表の他のプロパティを含めずに、独自の PATCH 要求でこれらを指定します
- Group.ReadWrite.All アクセス許可を持つ (これらのプロパティでは Directory.ReadWrite.All はサポートされていません)
- コア・グループの管理と管理に関連するグループ API のサブセットのみが、アプリケーション権限と委任権限をサポートします。 グループ API の他のすべてのメンバー ( autoSubscribeNewMembers の更新など) は、委任されたアクセス許可のみをサポートします。
- Microsoft Exchange Server でメールが有効なセキュリティ グループを更新するためのルールが複雑になる場合があります。詳細については、「Exchange Server でメールが有効なセキュリティ グループを管理する」を参照してください。
- assignedLabels を更新するときに、アプリケーションのアクセス許可がサポートされません。 Group.ManageProtection.All は、クラウド セキュリティ グループの assignedLabels を更新するための最低特権アクセス許可です。
グループの作成中に isHardDeleteProtectionEnabled を有効にすることはサポートされていません。 最初にグループを作成してから、別の PATCH 要求で保護を有効にします。
拡張機能と関連データを管理する
次のように、この API を使用して、ディレクトリ、スキーマ、およびユーザーのオープン拡張機能 とそのデータを管理します。
- 既存のユーザーの拡張機能にデータを追加、更新、および格納します。
- ディレクトリおよびスキーマ拡張機能の場合は、カスタム拡張プロパティの値を
nullに設定して、格納されているデータをすべて削除します。 オープン拡張機能の場合は、[オープン拡張機能を削除する] API を使用します。
応答
成功した場合、このメソッドは204 No Content応答コードを返します。ただし、次のプロパティを更新する場合の200 OK応答コードは除きます: accessType、allowExternalSenders、autoSubscribeNewMembers、hideFromAddressLists、hideFromOutlookClients、isFavorite、isSubscribedByMail、unseenConversationsCount、unseenCount、unseenMessagesCount、welcomeMessageEnabled。
エラー
| 状態コード | エラー コード | エラー メッセージ | 説明 |
|---|---|---|---|
400 Bad Request |
Request_BadRequest |
"ソース リソース オブジェクトまたは参照されているオブジェクトの 1 つは存在しません。" | このグループは最近作成されたものであり、すべてのディレクトリ レプリカで完全にレプリケートされていません。 このエラーは、リンク書き込み操作 ( members@odata.bind によるメンバーの追加) に固有です。 少し待ってから要求を再試行します。 |
例
例 1: グループの表示名と説明を更新する
要求
次の例は要求を示しています。
PATCH https://graph.microsoft.com/beta/groups/0d09007d-45b2-458c-b180-880dde3a302e
Content-type: application/json
{
"description":"Contoso Life v2.0",
"displayName":"Contoso Life Renewed"
}
応答
次の例は応答を示しています。
HTTP/1.1 204 No Content
例 2:Microsoft 365 グループに秘密度ラベルを適用する
要求
リスト ラベルを使用すると、Microsoft 365 グループに適用するラベルの ID を取得できます。 その後、グループの assignedLabels プロパティをラベル ID で更新できます。
メモ: この API を使用して秘密度ラベルを Microsoft 365 グループに適用することは、委任されたアクセス許可のシナリオでのみサポートされています。
PATCH https://graph.microsoft.com/beta/groups/{id}
Content-type: application/json
{
"assignedLabels":
[
{
"labelId" : "45cd0c48-c540-4358-ad79-a3658cdc5b88"
}
]
}
応答
次の例は応答を示しています。
HTTP/1.1 204 No Content
例 3: グループのハード削除保護を有効にする
一度有効にしたハード削除保護を無効にすることはできません。 既存のクラウド専用グループと、「 特定のシナリオのアクセス許可」で説明されているアクセス許可とロールを使用します。
要求
PATCH https://graph.microsoft.com/beta/groups/0d09007d-45b2-458c-b180-880dde3a302e
Content-Type: application/json
{
"isHardDeleteProtectionEnabled": true
}
応答
HTTP/1.1 204 No Content