Freigeben über

Upsert-Gruppe

  • Artikel

Namespace: microsoft.graph

Wichtig

Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.

Erstellen Sie ein neues Gruppenobjekt , wenn es nicht vorhanden ist, oder aktualisieren Sie die Eigenschaften eines vorhandenen Gruppenobjekts . Sie können die folgenden Gruppentypen erstellen oder aktualisieren:

  • Microsoft 365-Gruppe (einheitliche Gruppe)
  • Sicherheitsgruppe

Standardmäßig gibt dieser Vorgang nur eine Teilmenge der Eigenschaften für jede Gruppe zurück. Eine Liste der Eigenschaften, die standardmäßig zurückgegeben werden, finden Sie im Abschnitt Eigenschaften der Gruppenressource . Um Eigenschaften abzurufen, die nicht standardmäßig zurückgegeben werden, führen Sie eine GET-Operation aus, und geben Sie die Eigenschaften in einer $select OData-Abfrageoption an.

Hinweis: Um ein Team zu erstellen, erstellen Sie zuerst eine Gruppe, und fügen Sie ihr dann ein Team hinzu. Weitere Informationen finden Sie unter Erstellen eines Teams.

Berechtigungen

Wählen Sie für diese API die Als am wenigsten privilegierten Berechtigungen gekennzeichneten Berechtigungen aus. Verwenden Sie nur dann eine Berechtigung mit höheren Berechtigungen , wenn dies für Ihre App erforderlich ist. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp Berechtigungen mit den geringsten Berechtigungen Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto) Group.ReadWrite.All Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Anwendung Group.ReadWrite.All Directory.ReadWrite.All

Damit eine App mit der Group.Create-Berechtigung eine Gruppe mit Besitzern oder Mitgliedern erstellen kann, muss sie über die Berechtigungen zum Lesen des Objekttyps verfügen, den sie als Gruppenbesitzer oder -mitglied zuweisen möchte. Deshalb:

  • Die App kann sich selbst als Besitzer oder Mitglied der Gruppe zuweisen.
  • Um die Gruppe mit Benutzern als Besitzer oder Mitglieder zu erstellen, muss die App mindestens über die Berechtigung User.Read.All verfügen.
  • Um die Gruppe mit anderen Dienstprinzipalen als Besitzer oder Mitglieder zu erstellen, muss die App mindestens über die Berechtigung Application.Read.All verfügen.
  • Um die Gruppe mit Benutzern oder Dienstprinzipalen als Besitzer oder Mitgliedern zu erstellen, muss die App mindestens über die Berechtigung Directory.Read.All verfügen.

HTTP-Anforderung

PATCH /groups/(uniqueName='uniqueName')

Anforderungsheader

Name Beschreibung
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über die Authentifizierung und Autorisierung.
Content-Type application/json. Erforderlich.
Prefer create-if-missing. Erforderlich für upsert-Verhalten, andernfalls wird die Anforderung als Aktualisierungsvorgang behandelt.

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung des Gruppenobjekts an.

In der folgenden Tabelle sind die Eigenschaften aufgeführt, die beim Erstellen der Gruppe erforderlich sind. Geben Sie bei Bedarf andere beschreibbare Eigenschaften für Ihre Gruppe an, wenn sie erstellt oder aktualisiert werden.

Eigenschaft Typ Beschreibung
displayName String Der Name der Gruppe, der im Adressbuch angezeigt wird. Die maximale Länge beträgt 256 Zeichen. Erforderlich.
mailEnabled Boolesch Für E-Mail-aktivierte Gruppen auf true setzen. Erforderlich.
mailNickname String Der E-Mail-Alias für die Gruppe, eindeutig für Microsoft 365-Gruppen in der Organisation. Die maximale Länge beträgt 64 Zeichen. Diese Eigenschaft darf nur Zeichen im ASCII-Zeichensatz 0 bis 127 mit Ausnahme der folgenden enthalten: @ () \ [] " ; : <> , SPACE. Erforderlich.
securityEnabled Boolean true für sicherheitsaktivierte Gruppen festlegen, einschließlich Microsoft 365-Gruppen. Erforderlich. Hinweis: Gruppen, die mit dem Microsoft Entra Admin Center oder dem Azure-Portal erstellt wurden, ist securityEnabled anfangs immer auf truefestgelegt.

Wichtig

  • Wenn Sie eine Gruppe mit der Anwendungsberechtigung Group.Create erstellen, ohne Besitzer anzugeben, wird die Gruppe anonym erstellt und kann nicht geändert werden. Fügen Sie der Gruppe beim Erstellen Besitzer hinzu, um Besitzer anzugeben, die die Gruppe ändern können.
  • Beim programmgesteuerten Erstellen einer Microsoft 365-Gruppe mit Nur-App-Kontext und ohne Angabe von Besitzern wird die Gruppe anonym erstellt. Dies kann dazu führen, dass die zugehörige SharePoint Online-Website nicht automatisch erstellt wird und weitere manuelle Aktionen nötig sind.
  • Ein Benutzer ohne Administratorrechte kann sich nicht selbst zur Sammlung der Gruppenbesitzer hinzufügen. Weitere Informationen finden Sie unter dem zugehörigen bekannten Problem.
  • Die folgenden Eigenschaften können in der ersten POST-Anforderung nicht festgelegt werden und müssen in einer nachfolgenden PATCH-Anforderung festgelegt werden: allowExternalSenders, autoSubscribeNewMembers, hideFromAddressLists, hideFromOutlookClients, isSubscribedByMail, unseenCount.

Da die Ressource groupextensions unterstützt, können Sie beim Erstellen der Gruppe benutzerdefinierte Eigenschaften mit Ihren eigenen Daten hinzufügen.

groupTypes-Optionen

Verwenden Sie, wie dargestellt, die Eigenschaft groupTypes zum Steuern des Typs der Gruppe und ihrer Mitgliedschaft.

Typ der Gruppe Zugeordnete Mitgliedschaft Dynamische Mitgliedschaft
Microsoft 365 (auch einheitliche Gruppe genannt) ["Unified"] ["Unified","DynamicMembership"]
Dynamisch [] (null) ["DynamicMembership"]

Antwort

Wenn kein Objekt mit dem uniqueName vorhanden ist, gibt diese Methode einen 201 Created Antwortcode und ein neues Gruppenobjekt im Antworttext zurück.

Wenn kein Objekt mit uniqueName vorhanden ist und der Prefer: create-if-missing Header nicht angegeben ist, gibt diese Methode einen 404 Not Found Fehlercode zurück.

Wenn bereits ein Objekt mit dem uniqueName vorhanden ist, aktualisiert diese Methode das Gruppenobjekt und gibt einen 204 No Content Antwortcode zurück.

Beispiele

Beispiel 1: Erstellen einer Microsoft 365-Gruppe, wenn sie nicht vorhanden ist

Im folgenden Beispiel wird eine Microsoft 365-Gruppe erstellt, da keine Gruppe mit dem angegebenen uniqueName-Wert vorhanden ist. Da die Besitzer nicht angegeben wurden, wird der anrufende Benutzer automatisch als Besitzer der Gruppe hinzugefügt.

Anforderung

PATCH https://graph.microsoft.com/beta/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
}

Antwort

Das folgende Beispiel zeigt die Antwort. Der Wert der Eigenschaft preferredDataLocation-Eigenschaft wird vom bevorzugten Datenspeicherort des Gruppenerstellers geerbt.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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": []
}

Beispiel 2: Erstellen einer Sicherheitsgruppe mit einem Besitzer und Mitgliedern, falls diese nicht vorhanden ist

Im folgenden Beispiel wird eine Sicherheitsgruppe mit einem Besitzer und mitgliedern erstellt, da keine Gruppe mit dem angegebenen uniqueName-Wert vorhanden ist. Bitte beachten Sie, dass maximal 20 Beziehungen, beispielsweise Besitzer und Mitglieder, als Teil im Rahmen der Gruppenerstellung hinzugefügt werden können. Anschließend können Sie mehrere zusätzliche Member hinzufügen, indem Sie die Add-Member-API oder JSON-Batchverarbeitung verwenden.

Ein Benutzer ohne Administratorrechte kann sich nicht selbst zur Sammlung der Gruppenbesitzer hinzufügen. Weitere Informationen finden Sie unter dem zugehörigen bekannten Problem.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

PATCH https://graph.microsoft.com/beta/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/beta/users/26be1845-4119-4801-a799-aea79d09f1a2"
  ],
  "members@odata.bind": [
    "https://graph.microsoft.com/beta/users/ff7cb387-6688-423c-8188-3da9532a73cc",
    "https://graph.microsoft.com/beta/users/69456242-0067-49d3-ba96-9de6f2728e14"
  ]
}

Antwort

Es folgt ein Beispiel für eine erfolgreiche Antwort. Es enthält nur Standardeigenschaften. Sie können anschließend die owners- oder members-Navigationseigenschaft der Gruppe abrufen, um den Besitzer oder die Mitglieder zu überprüfen. Der Wert der Eigenschaft preferredDataLocation-Eigenschaft wird vom bevorzugten Datenspeicherort des Gruppenerstellers geerbt.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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,
    "isManagementRestricted": 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": []
}

Beispiel 3: Aktualisieren einer vorhandenen Gruppe

In diesem Beispiel ist die angegebene Gruppe bereits vorhanden, sodass der Vorgang als Update behandelt wird.

Ein Benutzer ohne Administratorrechte kann sich nicht selbst zur Sammlung der Gruppenbesitzer hinzufügen. Weitere Informationen finden Sie unter dem zugehörigen bekannten Problem.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

POST https://graph.microsoft.com/beta/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/beta/users/99e44b05-c10b-4e95-a523-e2732bbaba1e"
    ],
    "members@odata.bind": [
        "https://graph.microsoft.com/beta/users/6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0",
        "https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
    ]
}

Antwort

Das folgende Beispiel zeigt die Antwort. Der Wert der Eigenschaft preferredDataLocation-Eigenschaft wird vom bevorzugten Datenspeicherort des Gruppenerstellers geerbt.

HTTP/1.1 204 No Content

Verwandte Inhalte