Criar usuário

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie um novo usuário. Se você especificar uma propriedade @odata.type com um valor de #microsoft.graph.agentUser com as propriedades necessárias, essa API criará um objeto agentUser .

No mínimo, você deve especificar as propriedades necessárias. Opcionalmente, você pode especificar outras propriedades graváveis.

Essa operação retorna, por padrão, apenas um subconjunto das propriedades de cada usuário e agentUser. Essas propriedades padrão estão listadas na seção Propriedades. Para obter propriedades não retornadas por padrão, execute uma operação GET e especifique as propriedades em uma opção de consulta $select do OData.

Observação

Para criar usuários externos como parte da colaboração B2B com sua organização, use a API de convite. Para criar um cliente, cidadão ou parceiro de negócios na ID externa do Microsoft Entra em locatários externos, consulte o Exemplo 4: Criar uma conta de cliente.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global Governo dos EUA L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante) User.Create User.ReadWrite.All, Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Application User.Create User.ReadWrite.All, Directory.ReadWrite.All

Solicitação HTTP

POST /users

Cabeçalhos de solicitação

Cabeçalho Valor
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type application/json

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON do objeto user.

A tabela a seguir lista as propriedades que são necessárias ao criar um usuário ou agentUser.

  • Você deve especificar uma propriedade @odata.type com um valor de #microsoft.graph.agentUser para criar um agentUser, caso contrário, um usuário é criado e o usuário
  • Se você estiver incluindo uma propriedade de identidades para o usuário que está criando, nem todas as propriedades listadas serão necessárias. Para uma identidade social, nenhuma das propriedades é necessária.
Parâmetro Tipo Descrição
accountEnabled Booliano True se a conta estiver habilitada; caso contrário, false.
displayName Cadeia de caracteres Nome de exibição no catálogo de endereços do usuário.
onPremisesImmutableId String Obrigatório somente ao criar uma nova conta de usuário se você estiver usando um domínio federado para a propriedade userPrincipalName (UPN) do usuário.
mailNickname String O alias de email do usuário.
passwordProfile passwordProfile O perfil de senha do usuário. Aplica-se apenas ao usuário e não é permitido para agentUser.
userPrincipalName Cadeia de caracteres O nome UPN (someuser@contoso.com). É um nome de logon no estilo da Internet para o usuário com base no padrão da Internet RFC 822. Por convenção, ele deve ser mapeado para o nome de email do usuário. O formato geral é alias@domain, onde o domínio deve estar presente na coleta de domínios verificados pelo locatário. Os domínios verificados para o locatário podem ser acessados pela propriedade verifiedDomains de organization.
OBSERVAÇÃO: esta propriedade não pode conter caracteres de ênfase. Somente os seguintes caracteres são permitidos A - Z, a - z, 0 - 9, ' . - _ ! # ^ ~. Para obter a lista completa de caracteres permitidos, consulte as políticas de nome de usuário.
identityParentId Cadeia de caracteres A ID do objeto da identidade do agente associado. Necessário para agentUser em que @odata.type of deve ser definido e ignorado #microsoft.graph.agentUser para usuários comuns. Caso contrário, um usuário comum é criado.

Como esse recurso dá suporte a extensões, você pode usar a POST operação e adicionar propriedades personalizadas com seus próprios dados à instância do usuário ao criá-la.

Os usuários federados criados por essa API devem entrar a cada 12 horas por padrão. Para obter informações sobre como alterar isso, consulte Exceções para tempos de vida de token.

Observação

Adicionar uma conta local B2C a um objeto de usuário existente não é permitido, a menos que o objeto de usuário já contenha uma identidade de conta local.

Resposta

Se for bem-sucedido, esse método retornará um código de 201 Created resposta e um objeto user ou agentUser no corpo da resposta.

Omitir a @odata.type propriedade de cria um objeto de #microsoft.graph.agentUser usuário, mesmo que o identityParentId seja especificado. A tentativa de criar um agentUser com um identityParentId já vinculado a outro agentUser retorna um 400 Bad Request erro.

Exemplo

Exemplo 1: criar um usuário

Solicitação

O exemplo a seguir mostra uma solicitação, especificando apenas as propriedades necessárias.

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

O exemplo a seguir mostra a resposta.

Observação

O objeto de resposta mostrado aqui pode ser reduzido para facilitar a leitura.

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

Exemplo 2: Criar um usuário agente

Solicitação

O exemplo a seguir mostra uma solicitação, especificando apenas as propriedades necessárias.

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

O exemplo a seguir mostra a resposta.

Observação

O objeto de resposta mostrado aqui pode ser reduzido para facilitar a leitura.

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

Exemplo 3: Criar um usuário com identidades de conta social e local no Azure AD B2C

Crie um novo usuário, com uma identidade de conta local, com um nome de logon, um endereço de email como logon e com uma identidade social. Esse exemplo normalmente é usado para cenários de migração em locatários do Azure AD B2C.

Observação

Para as identidades de conta local, as expirações de senha devem ser desabilitadas e forçar alteração de senha no próximo logon também deve ser desabilitado.

Solicitação

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

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

Exemplo 4: Criar uma conta de cliente em locatários externos

Este exemplo mostra como criar uma conta de cliente na ID externa do Microsoft Entra em locatários externos.

Observação

Para identidades de conta local, as expirações de senha devem ser desabilitadas.

Solicitação

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

Resposta

O exemplo a seguir mostra a resposta.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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