Upsert グループ

名前空間: microsoft.graph

新しい グループ オブジェクトが存在しない場合は作成するか、既存の グループ オブジェクトのプロパティを更新します。 次の種類のグループを作成または更新できます。

  • Microsoft 365 グループ (統合グループ)
  • セキュリティ グループ

既定では、この操作は各グループのプロパティのサブセットのみを返します。 既定で返されるプロパティの一覧については、グループ リソースの [プロパティ] セクションを参照してください。 既定で返されないプロパティを取得するには、GET 操作を実行し、$select OData クエリ オプションでプロパティを指定します。

注: チームを作成するには、まずグループを作成してから、チームを追加します。 詳細については、「チームの 作成」を参照してください。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類 最小特権アクセス許可 より高い特権のアクセス許可
委任 (職場または学校のアカウント) Group.ReadWrite.All Directory.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション Group.ReadWrite.All Directory.ReadWrite.All

Group.Create アクセス許可を持つアプリが所有者またはメンバーを持つグループを作成するには、グループ所有者またはメンバーとして割り当てるオブジェクトの種類を読み取る権限が必要です。 そこで：

  • アプリは、グループの所有者またはメンバーとして自身を割り当てることができます。
  • 所有者またはメンバーとしてユーザーを含むグループを作成するには、アプリに少なくとも User.Read.All アクセス許可が必要です。
  • 所有者またはメンバーとして他のサービス プリンシパルを使用してグループを作成するには、アプリに 少なくとも Application.Read.All アクセス許可が必要です。
  • ユーザーまたはサービス プリンシパルを所有者またはメンバーとしてグループを作成するには、アプリに少なくとも Directory.Read.All アクセス許可が必要です。

HTTP 要求

PATCH /groups(uniqueName='uniqueName')

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。
Content-Type application/json. Required.
Prefer create-if-missing. アップサート動作に必要です。それ以外の場合、要求は更新操作として扱われます。

要求本文

要求本文で、グループ オブジェクトの JSON 表記を指定します。

次の表に、 グループを作成するときに必要なプロパティを示します。 作成または更新時にグループに必要に応じて、他の書き込み可能なプロパティを指定します。

プロパティ 型 説明
displayName 文字列 アドレス帳に表示するグループの名前。 最大文字数は 256 文字です。 必須です。
mailEnabled Boolean メールが有効なグループの場合は、true に設定します。 必須です。
mailNickname String 組織内の Microsoft 365 グループに対して一意の、グループのメール エイリアス。 最大文字数は 64 文字です。 このプロパティには、 ASCII 文字セット 0 から 127 の文字 のみを含めることができますが、次の文字を除きます: @ () \ [] " ; : <> , SPACE。 必須です。
securityEnabled Boolean Microsoft 365 グループを含む、セキュリティが有効なグループに true を設定します。 必須です。 メモ：Microsoft Entra 管理センターまたはAzure portalを使用して作成されたグループには、常に securityEnabled が最初に true に設定されています。

重要

  • 所有者を指定せずに Group.Create アプリケーション権限を使用してグループを作成すると、グループが匿名で作成され、グループは変更できません。 グループを変更できる所有者を指定するには、グループの作成中に所有者をグループに追加します。
  • アプリ専用コンテキストを使用し、所有者を指定せずにプログラムで Microsoft 365 グループを作成すると、グループが匿名で作成されます。 この操作を行うと、さらに手動操作が行われるまで、関連付けられている SharePoint Online サイトが自動的に作成されない可能性があります。
  • 管理者以外のユーザーは、グループ所有者コレクションに自分自身を追加できません。 詳細については、関連する既知の 問題に関するページを参照してください。
  • 最初の POST 要求では次のプロパティを設定できません。accessType、allowExternalSenders、autoSubscribeNewMembers、hideFromAddressLists、hideFromOutlookClients、isFavorite、isSubscribedByMail、unseenConversationsCount、unseenCount、unseenMessagesCount。

グループ リソースは拡張機能をサポートしているため、 リソースの作成時にカスタム プロパティを独自のデータとともにグループに追加することができます。

groupTypes オプション

示すように、groupTypes プロパティを使用し、グループの種類とグループのメンバーシップを管理します:

グループの種類 割り当て済みのメンバーシップ 動的メンバーシップ
Microsoft 365 (統合グループ) ["Unified"] ["Unified","DynamicMembership"]
Dynamic [] (null) ["DynamicMembership"]

応答

uniqueName を持つオブジェクトが存在しない場合、このメソッドは応答コード201 Createdと、応答本文に新しいグループ オブジェクトを返します。

uniqueName を持つオブジェクトが存在せず、Prefer: create-if-missing ヘッダーが指定されていない場合、このメソッドは404 Not Foundエラー コードを返します。

uniqueName を持つオブジェクトが既に存在する場合、このメソッドはグループ オブジェクトを更新し、204 No Content応答コードを返します。

例

例 1: Microsoft 365 グループが存在しない場合は作成する

次の例では、指定された uniqueName 値を持つグループが存在しないため、Microsoft 365 グループを作成します。 所有者が指定されていないため、呼び出し元のユーザーがグループの所有者として自動的に追加されます。

要求

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-type: application/json
Prefer: create-if-missing

{
  "description": "Self help community for golf",
  "displayName": "Golf Assist",
  "groupTypes": [
    "Unified"
  ],
  "mailEnabled": true,
  "mailNickname": "golfassist",
  "securityEnabled": false
}

応答

次の例は応答を示しています。 preferredDataLocation プロパティの値は、グループ作成者の優先されるデータの場所から継承されます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "id": "45b7d2e7-b882-4a80-ba97-10b7a63b8fa4",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2018-12-22T02:21:05Z",
    "description": "Self help community for golf",
    "displayName": "Golf Assist",
    "expirationDateTime": null,
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": null,
    "mail": "golfassist@contoso.com",
    "mailEnabled": true,
    "mailNickname": "golfassist",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": "CAN",
    "preferredLanguage": null,
    "proxyAddresses": [
        "SMTP:golfassist@contoso.onmicrosoft.com"
    ],
    "renewedDateTime": "2018-12-22T02:21:05Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": false,
    "securityIdentifier": "S-1-12-1-1753967289-1089268234-832641959-555555555",
    "theme": null,
    "visibility": "Public",
    "uniqueName": "uniqueName",
    "onPremisesProvisioningErrors": []
}

例 2: 所有者とメンバーが存在しない場合は、セキュリティ グループを作成する

次の例では、 指定された uniqueName 値を持つグループが存在しないため、所有者とメンバーが指定されたセキュリティ グループを作成します。 所有者やメンバーなど、最大 20 個のリレーションシップをグループ作成の一部として追加できます。 その後、メンバーの追加 API または JSON バッチ処理を使用して、複数の メンバーを追加 できます。

管理者以外のユーザーは、グループ所有者コレクションに自分自身を追加できません。 詳細については、関連する既知の 問題に関するページを参照してください。

要求

次の例は要求を示しています。

PATCH https://graph.microsoft.com/v1.0/groups(uniqueName='uniqueName')
Content-Type: application/json

{
  "description": "Group with designated owner and members",
  "displayName": "Operations group",
  "groupTypes": [
  ],
  "mailEnabled": false,
  "mailNickname": "operations2019",
  "securityEnabled": true,
  "owners@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/v1.0/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/v1.0/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

応答

次の例は、成功した応答を示しています。 既定のプロパティのみが含まれています。 その後は、グループの owners ナビゲーション プロパティまたは members ナビゲーション プロパティを取得して所有者またはメンバーの詳細を確認できます。 preferredDataLocation プロパティの値は、グループ作成者の優先されるデータの場所から継承されます。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups/$entity",
    "@odata.id": "https://graph.microsoft.com/v2/84841066-274d-4ec0-a5c1-276be684bdd3/directoryObjects/1226170d-83d5-49b8-99ab-d1ab3d91333e/Microsoft.DirectoryServices.Group",
    "id": "1226170d-83d5-49b8-99ab-d1ab3d91333e",
    "deletedDateTime": null,
    "classification": null,
    "createdDateTime": "2021-09-21T07:14:44Z",
    "createdByAppId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
    "organizationId": "84841066-274d-4ec0-a5c1-276be684bdd3",
    "description": "Group with designated owner and members",
    "displayName": "Operations group",
    "expirationDateTime": null,
    "groupTypes": [],
    "infoCatalogs": [],
    "isAssignableToRole": null,
    "mail": null,
    "mailEnabled": false,
    "mailNickname": "operations2019",
    "membershipRule": null,
    "membershipRuleProcessingState": null,
    "onPremisesDomainName": null,
    "onPremisesLastSyncDateTime": null,
    "onPremisesNetBiosName": null,
    "onPremisesSamAccountName": null,
    "onPremisesSecurityIdentifier": null,
    "onPremisesSyncEnabled": null,
    "preferredDataLocation": null,
    "preferredLanguage": null,
    "proxyAddresses": [],
    "renewedDateTime": "2021-09-21T07:14:44Z",
    "resourceBehaviorOptions": [],
    "resourceProvisioningOptions": [],
    "securityEnabled": true,
    "securityIdentifier": "S-1-12-1-304486157-1236829141-2882644889-1043566909",
    "theme": null,
    "uniqueName": "uniqueName",
    "visibility": null,
    "writebackConfiguration": {
        "isEnabled": null,
        "onPremisesGroupType": null
    },
    "onPremisesProvisioningErrors": []
}

例 3: 既存のグループを更新する

この例では、指定したグループが既に存在するため、操作は更新プログラムとして扱われます。

管理者以外のユーザーは、グループ所有者コレクションに自分自身を追加できません。 詳細については、関連する既知の 問題に関するページを参照してください。

要求

次の例は要求を示しています。

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

{
    "description": "Group assignable to a role",
    "displayName": "Role assignable group",
    "groupTypes": [
        "Unified"
    ],
    "isAssignableToRole": true,
    "mailEnabled": true,
    "securityEnabled": true,
    "mailNickname": "contosohelpdeskadministrators",
    "owners@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/v1.0/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

応答

次の例は応答を示しています。 preferredDataLocation プロパティの値は、グループ作成者の優先されるデータの場所から継承されます。

HTTP/1.1 204 No Content

関連コンテンツ

  • Last updated on