创建用户

命名空间:microsoft.graph

重要

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

创建新 用户。 如果指定值为 @odata.type#microsoft.graph.agentUser 的属性以及必需的属性,则此 API 将创建 agentUser 对象。

至少必须指定所需的属性。 可以选择指定其他任意可写属性。

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

注意

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

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

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

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考。

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

HTTP 请求

POST /users

请求标头

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

请求正文

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

下表列出了创建 user 或 agentUser 时所需的属性。

  • 您必须指定值#microsoft.graph.agentUser为 @odata.type 属性才能创建 agentUser,否则将创建用户并 iden
  • 如果要为正在创建的用户包括 identities 属性,并非所有列出的属性都是必需的。 对于社交标识,则无需任何属性。
参数 类型 说明
accountEnabled Boolean 如果帐户已启用,则为 true;否则为 false。
displayName String 要在用户的通讯簿中显示的名称。
onPremisesImmutableId String 如果对用户的 userPrincipalName (UPN) 属性使用联合域,则仅在创建新用户帐户时才需要。
mailNickname String 用户的邮件别名。
passwordProfile passwordProfile 用户的密码配置文件。 仅适用于 用户 ,不允许 agentUser。
userPrincipalName String 用户主体名称 (someuser@contoso.com) 。 它是基于 Internet 标准 RFC 822 的用户的 Internet 样式登录名。 按照惯例,此名称应映射到用户的电子邮件名称。 常规格式是 alias@domain,其中 domain 必须位于租户的已验证域集合中。 可从 组织 的 verifiedDomains 属性访问租户的已验证域。
注意:此属性不能包含突出字符。 仅支持使用以下字符:A - Z、a - z、0 - 9、 ' . - _ ! # ^ ~。 有关允许字符的完整列表,请参阅用户名策略。
identityParentId String 关联 的代理标识的对象 ID。 对于 agentUser 是必需的,其中必须为普通用户设置并忽略 @odata.type#microsoft.graph.agentUser。 如果未设置,则创建常规用户。

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

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

注意

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

响应

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

省略 of 的#microsoft.graph.agentUser属性会@odata.type创建一个用户对象,即使指定了 identityParentId。 尝试创建 identityParentId 已链接到另一个 agentUser 400 Bad Request 的 agentUser 返回错误。

示例

示例 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"
  }
}
响应

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

注意

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

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: 创建代理用户

请求

以下示例显示了一个请求,其中仅指定所需的属性。

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": ""
}
响应

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

注意

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

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

示例 3:在 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"
}

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

此示例演示如何在外部租户的 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": true
    },
    "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"
}