创建用户

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

创建新 用户。 请求正文包含要创建的用户。 至少必须指定必需的用户属性。 可以选择指定其他任意可写属性。

默认情况下,此操作仅返回每个用户的一部分属性。 这些默认属性将记录在属性部分中。 若要获取非默认返回的属性,请执行 GET 操作,并在 $select OData 查询选项中指定这些属性。

注意

若要创建外部用户作为与组织的 B2B 协作的一部分,请使用 邀请 API。 若要在外部租户的Microsoft Entra 外部 ID中创建客户、公民或业务合作伙伴,请参阅示例 3:创建客户帐户

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

要调用此 API,需要以下权限之一。 若要了解详细信息,包括如何选择权限的信息,请参阅权限

权限类型 权限(从最低特权到最高特权)
委派(工作或学校帐户) User.ReadWrite.All、Directory.ReadWrite.All
委派(个人 Microsoft 帐户) 不支持。
应用程序 User.ReadWrite.All、Directory.ReadWrite.All

HTTP 请求

POST /users

请求标头

标头
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Content-Type application/json

请求正文

在请求正文中,提供 user 对象的 JSON 表示形式。

下表列出了创建用户时所需的属性。 如果要为正在创建的用户包括 identities 属性,并非所有列出的属性都是必需的。 对于社交标识,则无需任何属性。

参数 类型 说明
accountEnabled Boolean 如果帐户已启用,则为 True;否则为 false。
displayName String 要在用户的通讯簿中显示的名称。
onPremisesImmutableId String 仅当将联合域用于用户的 userPrincipalName (UPN) 属性时,才需要创建新用户帐户。
mailNickname String 用户的邮件别名。
passwordProfile PasswordProfile 用户的密码配置文件。
userPrincipalName String 用户主体名称 (someuser@contoso.com) 。 它是基于 Internet 标准 RFC 822 的用户的 Internet 样式登录名。 按照惯例,此名称应映射到用户的电子邮件名称。 常规格式是 alias@domain,其中 domain 必须位于租户的已验证域集合中。 可从 组织verifiedDomains 属性访问租户的已验证域。
注意:此属性不能包含突出字符。 仅支持使用以下字符:A - Za - z0 - 9 ' . - _ ! # ^ ~。 有关允许字符的完整列表,请参阅用户名策略

由于用户资源支持扩展,因此可以使用 POST 操作,并在创建用户实例时向其添加含有自己的数据的自定义属性。

默认情况下,通过此 API 创建的联合用户将强制每 12 小时登录一次。 有关如何更改此项的信息,请参阅 令牌生存期的异常

注意

不允许将 B2C 本地帐户 添加到现有 用户 对象,除非 该用户 对象已包含本地帐户标识。

响应

如果成功,此方法会在响应正文中返回 201 Created 响应代码和 user 对象。

示例

示例 1:创建用户

请求

以下示例显示了一个请求。

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"
  }
}

在请求正文中,提供 user 对象的 JSON 表示形式。

响应

以下示例显示了相应的响应。

注意

为了提高可读性,可能缩短了此处显示的响应对象。

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"
}

示例 2:在 Azure AD B2C 中创建具有社交帐户标识和本地帐户标识的用户

创建一个新用户,该用户具有本地帐户标识(以登录名和电子邮件地址为登录凭据),并且具有社交标识。 此示例通常用于 Azure AD B2C 租户中的迁移方案。

注意

对于本地帐户标识,必须禁用密码过期,并且还必须禁用下次登录时强制更改密码。

请求

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"
}

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

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"
}

示例 3:在外部租户中创建客户帐户

此示例演示如何在外部租户的 Microsoft Entra 外部 ID 中创建客户帐户。

注意

对于本地帐户标识,必须禁用密码过期,并且还必须禁用下次登录时强制更改密码。

请求

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": false
    },
    "passwordPolicies": "DisablePasswordExpiration"
}

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

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"
}