Benutzer erstellen

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 eines neuen Benutzers. Wenn Sie eine @odata.type-Eigenschaft mit einem Wert von #microsoft.graph.agentUser mit den erforderlichen Eigenschaften angeben, erstellt diese API ein agentUser-Objekt .

Sie müssen mindestens die erforderlichen Eigenschaften angeben. Optional können Sie weitere schreibbare Eigenschaften festlegen.

Dieser Vorgang gibt standardmäßig nur eine Teilmenge der Eigenschaften für jeden Benutzer und agentUser zurück. Diese Standardeigenschaften werden im Abschnitt Eigenschaften aufgeführt. 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 externe Benutzer als Teil der B2B-Zusammenarbeit mit Ihrer organization zu erstellen, verwenden Sie die Einladungs-API. Informationen zum Erstellen eines Kunden, Bürgers oder Geschäftspartners in Microsoft Entra External ID in externen Mandanten finden Sie unter Beispiel 4: Erstellen eines Kundenkontos.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service US Government L4 US Government L5 (DOD) China, betrieben von 21Vianet

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. 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) User.Create User.ReadWrite.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto) Nicht unterstützt Nicht unterstützt
Application User.Create User.ReadWrite.All, Directory.ReadWrite.All

HTTP-Anforderung

POST /users

Anforderungsheader

Kopfzeile Wert
Authorization Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type application/json

Anforderungstext

Geben Sie im Anforderungstext eine JSON-Darstellung des user-Objekts an.

In der folgenden Tabelle sind die Eigenschaften aufgeführt , die erforderlich sind, wenn Sie einen Benutzer oder agentUser erstellen.

  • Sie müssen eine @odata.type-Eigenschaft mit dem Wert angeben #microsoft.graph.agentUser , um einen agentUser zu erstellen, andernfalls wird ein Benutzer erstellt und der iden
  • Wenn Sie für den Benutzer, den Sie erstellen, eine identities-Eigenschaft einschließen, sind nicht alle aufgeführten Eigenschaften erforderlich. Bei einer sozialen Identität ist keine der Eigenschaften erforderlich.
Parameter Typ Beschreibung
accountEnabled Boolean "True", wenn das Konto aktiviert ist; Andernfalls wird "false" verwendet.
displayName Zeichenfolge Der Name des Benutzers, der im Adressbuch angezeigt wird.
onPremisesImmutableId Zeichenfolge Nur erforderlich, wenn Sie ein neues Benutzerkonto erstellen, wenn Sie eine Verbunddomäne für die userPrincipalName (UPN)-Eigenschaft des Benutzers verwenden.
mailNickname Zeichenfolge Der E-Mail-Alias für den Benutzer.
passwordProfile passwordProfile Das Kennwortprofil für den Benutzer. Gilt nur für Benutzer und ist für agentUser nicht zulässig.
userPrincipalName Zeichenfolge Der Benutzerprinzipalname (someuser@contoso.com). Es ist ein Anmeldename für den Benutzers im Internetformat, der auf dem Internetstandard RFC 822 basiert. Gemäß der Konvention sollte er dem E-Mail-Namen des Benutzers zugeordnet sein. Das allgemeine Format lautet „alias@domäne“, wobei „domäne“ in der Sammlung der verifizierten Domänen des Mandanten vorhanden sein muss. Auf die verifizierten Domänen für den Mandanten kann über die verifiedDomains -Eigenschaft von organization zugegriffen werden.
HINWEIS: Diese Eigenschaft darf keine Akzentuierungszeichen enthalten. Nur die folgenden Zeichen sind zulässig: A - Z, a - z, 0 - 9, ' . - _ ! # ^ ~. Eine vollständige Liste der zulässigen Zeichen finden Sie unter Richtlinien für Benutzernamen.
identityParentId Zeichenfolge Die Objekt-ID der zugeordneten Agentidentität. Für agentUser erforderlich, wobei @odata. Typ von #microsoft.graph.agentUser festgelegt und für normale Benutzer ignoriert werden muss. Wenn diese Option nicht festgelegt ist, wird ein normaler Benutzer erstellt.

Da diese Ressource Erweiterungen unterstützt, können Sie den POST Vorgang verwenden und der Benutzer-instance beim Erstellen benutzerdefinierte Eigenschaften mit Ihren eigenen Daten hinzufügen.

Über diese API erstellte Verbundbenutzer müssen sich standardmäßig alle 12 Stunden anmelden. Informationen zum Ändern finden Sie unter Ausnahmen für die Lebensdauer von Token.

Hinweis

Das Hinzufügen eines lokalen B2C-Kontos zu einem vorhandenen Benutzerobjekt ist nicht zulässig, es sei denn, das Benutzerobjekt enthält bereits eine lokale Kontoidentität.

Antwort

Bei erfolgreicher Ausführung gibt diese Methode einen 201 Created Antwortcode und ein user - oder agentUser-Objekt im Antworttext zurück.

Wenn die @odata.type Eigenschaft von weggelassen wird #microsoft.graph.agentUser , wird ein Benutzerobjekt erstellt, auch wenn die identityParentId angegeben ist. Der Versuch , einen agentUser mit einer identityParentId zu erstellen, die bereits mit einem anderen agentUser verknüpft ist, gibt einen 400 Bad Request Fehler zurück.

Beispiel

Beispiel 1: Erstellen eines Benutzers

Anforderung

Das folgende Beispiel zeigt eine Anforderung, die nur die erforderlichen Eigenschaften angibt.

POST https://graph.microsoft.com/beta/users
Content-type: application/json

{
  "accountEnabled": true,
  "displayName": "Adele Vance",
  "mailNickname": "AdeleV",
  "userPrincipalName": "AdeleV@contoso.com",
  "passwordProfile" : {
    "forceChangePasswordNextSignIn": true,
    "password": "xWwvJ]6NMw+bWH-d"
  }
}
Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis

Das hier gezeigte Antwortobjekt wird möglicherweise zur besseren Lesbarkeit verkürzt.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
    "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
    "businessPhones": [],
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "jobTitle": "Product Marketing Manager",
    "mail": "AdeleV@contoso.com",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "AdeleV@contoso.com"
}

Beispiel 2: Erstellen eines Benutzer-Agents

Anforderung

Das folgende Beispiel zeigt eine Anforderung, die nur die erforderlichen Eigenschaften angibt.

POST https://graph.microsoft.com/beta/users
Content-type: application/json

{
  "@odata.type": "#microsoft.graph.agentUser",
  "accountEnabled": true,
  "displayName": "Adele Vance",
  "mailNickname": "AdeleV",
  "userPrincipalName": "AdeleV@contoso.com",
  "identityParentId": ""
}
Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis

Das hier gezeigte Antwortobjekt wird möglicherweise zur besseren Lesbarkeit verkürzt.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#users/$entity",
    "@odata.type": "#microsoft.graph.agentUser",
    "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd",
    "businessPhones": [],
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "jobTitle": "Product Marketing Manager",
    "mail": "AdeleV@contoso.com",
    "mobilePhone": "+1 425 555 0109",
    "officeLocation": "18/2111",
    "preferredLanguage": "en-US",
    "surname": "Vance",
    "userPrincipalName": "AdeleV@contoso.com"
}

Beispiel 3: Erstellen eines Benutzers mit Identitäten sozialer und lokaler Konten in Azure AD B2C

Erstellen Sie einen neuen Benutzer mit einer lokalen Kontoidentität mit einem Anmeldenamen, einer E-Mail-Adresse für die Anmeldung und einer sozialen Identität. Dieses Beispiel wird in der Regel für Migrationsszenarien in Azure AD B2C-Mandanten verwendet.

Hinweis

Bei lokalen Kontoidentitäten müssen das Ablaufen des Kennworts und das Erzwingen der Kennwortänderung bei der nächsten Anmeldung deaktiviert werden.

Anforderung

POST https://graph.microsoft.com/beta/users
Content-type: application/json

{
  "displayName": "John Smith",
  "identities": [
    {
      "signInType": "userName",
      "issuer": "contoso.com",
      "issuerAssignedId": "johnsmith"
    },
    {
      "signInType": "emailAddress",
      "issuer": "contoso.com",
      "issuerAssignedId": "jsmith@yahoo.com"
    },
    {
      "signInType": "federated",
      "issuer": "facebook.com",
      "issuerAssignedId": "5eecb0cd"
    }
  ],
  "passwordProfile" : {
    "password": "password-value",
    "forceChangePasswordNextSignIn": false
  },
  "passwordPolicies": "DisablePasswordExpiration"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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#users/$entity",
  "displayName": "John Smith",
  "id": "4c7be08b-361f-41a8-b1ef-1712f7a3dfb2",
  "identities": [
    {
      "signInType": "userName",
      "issuer": "contoso.com",
      "issuerAssignedId": "johnsmith"
    },
    {
      "signInType": "emailAddress",
      "issuer": "contoso.com",
      "issuerAssignedId": "jsmith@yahoo.com"
    },
    {
      "signInType": "federated",
      "issuer": "facebook.com",
      "issuerAssignedId": "5eecb0cd"
    }
  ],
  "passwordPolicies": "DisablePasswordExpiration"
}

Beispiel 4: Erstellen eines Kundenkontos in externen Mandanten

In diesem Beispiel wird gezeigt, wie Sie ein Kundenkonto in Microsoft Entra External ID in externen Mandanten erstellen.

Hinweis

Bei lokalen Kontoidentitäten muss der Kennwortablauf deaktiviert sein.

Anforderung

POST https://graph.microsoft.com/beta/users
Content-type: application/json

{
    "displayName": "Test User",
    "identities": [
        {
            "signInType": "emailAddress",
            "issuer": "contoso.onmicrosoft.com",
            "issuerAssignedId": "adelev@adatum.com"
        }
    ],
    "mail": "adelev@adatum.com",
    "passwordProfile": {
        "password": "passwordValue",
        "forceChangePasswordNextSignIn": true
    },
    "passwordPolicies": "DisablePasswordExpiration"
}

Antwort

Das folgende Beispiel zeigt die Antwort.

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#users/$entity",
    "id": "daabd280-3978-4d29-acce-d677b9cf2e4d",
    "businessPhones": [],
    "displayName": "Test User",
    "givenName": null,
    "jobTitle": null,
    "mail": "adelev@adatum.com",
    "mobilePhone": null,
    "officeLocation": null,
    "preferredLanguage": null,
    "surname": null,
    "userPrincipalName": "daabd280-3978-4d29-acce-d677b9cf2e4d@contoso.onmicrosoft.com"
}