创建用户

命名空间:microsoft.graph

重要

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

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

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

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

注意

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

此 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 表示形式。

下表列出了创建用户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 - Za - z0 - 9 ' . - _ ! # ^ ~。 有关允许字符的完整列表,请参阅用户名策略
identityParentId String 关联 代理标识的对象 ID。 对于 agentUser 是必需的,其中必须设置和忽略普通用户的 @odata.type#microsoft.graph.agentUser。 如果未设置,则会创建常规用户。

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

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

注意

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

响应

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

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

示例

示例 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:在 AD B2C Azure中创建具有社交和本地帐户标识的用户

创建一个新用户,该用户具有本地帐户标识(以登录名和电子邮件地址为登录凭据),并且具有社交标识。 此示例通常用于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"
}