Trabalhar com usuários no Microsoft Graph

  • Artigo

Pode utilizar o Microsoft Graph para criar experiências de aplicações apelativas com base nos utilizadores e nas respetivas relações com outros objetos. Por exemplo, as respetivas relações com outros utilizadores e grupos, associações a grupos e os recursos a que acedem, como os respetivos e-mails, calendários, ficheiros e funções administrativas.

Você pode acessar usuários pelo Microsoft Graph de duas maneiras:

  • Pelo respetivo ID ou userPrincipalName ou /users/{id}/users/{userPrincipalName}
  • Usando o alias /me para o usuário conectado, que é igual a /users/{signed-in user's id}

Operações de API comuns

Caminho Descrição
/me Obtenha os detalhes do utilizador com sessão iniciada.
/users Lista os usuários na organização.
/users/{id} Obtém um utilizador específico por ID.
/users/{id}/photo/$value Obtém a foto de perfil do usuário.
/users/{id}/manager Obtém o gerente do usuário.
/users/{id}/messages Lista as mensagens de email do usuário em sua caixa de entrada principal.
/users/{id}/events Lista os eventos futuros do usuário em seu calendário.
/users/{id}/drive Obtém o repositório de arquivos do OneDrive do usuário.
/users/{id}/memberOf Lista os grupos dos quais o usuário é membro.
/users/{id}/joinedTeams Lista as Microsoft Teams das quais o usuário é membro.

Autorização e privilégios

O Microsoft Graph suporta a utilização de permissões delegadas e de aplicações para gerir operações de utilizador. Para obter mais informações, veja Permissões Delegadas vs. Aplicação e a documentação de referência da API correspondente para as permissões necessárias para cada operação.

Algumas operações de utilizador podem ser realizadas pelo utilizador com sessão iniciada em relação aos seus próprios detalhes. Para tais operações, o utilizador pode conceder à aplicação as permissões do Microsoft Graph para aceder aos seus próprios detalhes. As permissões User.ReadBasic.All, User.Read e User.ReadWrite são essas permissões.

Outras operações, incluindo a gestão de detalhes para outros utilizadores, requerem privilégios administrativos concedidos através de outras permissões do Microsoft Graph e Microsoft Entra funções. Além disso, algumas operações são consideradas confidenciais e apenas os administradores limitados podem executá-las. Para obter mais informações, veja Quem pode repor palavras-passe e Quem pode atualizar secções de atributos confidenciais .

Permissões de utilizador predefinidas no Microsoft Entra ID

Existem dois tipos de utilizadores no Microsoft Entra ID - membros e convidados. Inicialmente, os utilizadores membros são criados nativamente no inquilino. Os utilizadores convidados associam-se ao inquilino através da resgate do convite e do acesso ao inquilino como convidados de colaboração empresa-empresa (B2B).

O conjunto de permissões predefinidas depende se o utilizador é um membro ou um utilizador convidado. Para obter mais informações sobre o que os utilizadores membros e os utilizadores convidados podem fazer, veja Quais são as permissões de utilizador predefinidas no Microsoft Entra ID?.

Permissões de utilizador predefinidas nos inquilinos do cliente

Também existem permissões predefinidas para clientes no Microsoft Entra ID para clientes. A tabela seguinte indica as operações da API que permitem aos clientes gerir o seu próprio perfil.

O ID de utilizador ou userPrincipalName é sempre do utilizador com sessão iniciada.

Operação do utilizador Operação de API Permissões obrigatórias
Ler perfil GET /me ou GET /users/{id or userPrincipalName} User.Read
Atualizar perfil PATCH /me ou PATCH /users/{id or userPrincipalName}

As seguintes propriedades são atualizáveis: cidade, país, displayName, givenName, jobTitle, postalCode, state, streetAddress, apelido e preferredLanguage		 User.ReadWrite
Alterar senha POST /me/changePassword Directory.AccessAsUser.All

Ações confidenciais

As seguintes ações contra o objeto de utilizador são consideradas confidenciais e podem ser bloqueadas apenas para administradores específicos. Todos os utilizadores podem ler as propriedades confidenciais.

Ação sensível Nome da propriedade confidencial
Desativar ou ativar utilizadores accountEnabled
Atualizar telefone da empresa businessPhones
Atualizar telemóvel mobilePhone
Atualizar o ID imutável no local onPremisesImmutableId
Atualizar outros e-mails otherMails
Atualizar perfil de palavra-passe passwordProfile
Atualizar nome principal de utilizador userPrincipalName
Excluir ou restaurar usuários Não aplicável

Quem pode realizar ações confidenciais

Alguns administradores podem executar as ações confidenciais anteriores para alguns utilizadores.

Na tabela seguinte, as colunas listam as funções que podem executar ações confidenciais. As linhas listam as funções nas quais a ação confidencial pode ser executada.

A tabela seguinte destina-se a funções atribuídas no âmbito de um inquilino. Para funções atribuídas no âmbito de uma unidade administrativa, aplicam-se mais restrições.

Função sobre a qual a ação sensível pode ser executada Administração de autenticação Administração de utilizador Administração de Autenticação Privilegiada Administrador Global
Administração de autenticação ✅   ✅ ✅
Leitores de Diretórios ✅ ✅ ✅ ✅
Administrador Global     ✅ ✅
Grupos Administração   ✅ ✅ ✅
Convidado ✅ ✅ ✅ ✅
Administração de suporte técnico   ✅ ✅ ✅
Leitor do Centro de Mensagens ✅ ✅ ✅ ✅
Administração de palavras-passe ✅ ✅ ✅ ✅
Administração de Autenticação Privilegiada     ✅ ✅
Administração de Função Privilegiada     ✅ ✅
Leitor de Relatórios ✅ ✅ ✅ ✅
Usuário
(sem função de administrador)		 ✅ ✅ ✅ ✅
Usuário
(sem função de administrador, mas membro ou proprietário de um grupo atribuível a funções)		     ✅ ✅
Utilizador com uma função confinada a uma unidade administrativa de gestão restrita     ✅ ✅
Administração de utilizador   ✅ ✅ ✅
Leitor de relatórios de resumo do uso ✅ ✅ ✅ ✅
Todas as funções personalizadas ✅ ✅

Quem pode repor palavras-passe

Na tabela seguinte, as colunas listam as funções que podem repor palavras-passe e invalidar tokens de atualização. As linhas listam as funções para as quais a palavra-passe pode ser reposta. Por exemplo, um Administrador de Palavra-passe pode repor a palavra-passe para Leitores de Diretórios, Convidado convidado, Administrador de Palavra-passe e utilizadores sem função de administrador. Se for atribuída qualquer outra função a um utilizador, o Administrador de Palavras-passe não poderá repor a palavra-passe.

A tabela seguinte destina-se a funções atribuídas no âmbito de um inquilino. Para funções atribuídas no âmbito de uma unidade administrativa, aplicam-se mais restrições.

Função que a palavra-passe pode ser reposta Administração de palavras-passe Administração de suporte técnico Administração de autenticação Administração de utilizador Administração de Autenticação Privilegiada Administrador Global
Administração de autenticação     ✅   ✅ ✅
Leitores de Diretórios ✅ ✅ ✅ ✅ ✅ ✅
Administrador Global         ✅ ✅*
Grupos Administração       ✅ ✅ ✅
Convidado ✅ ✅ ✅ ✅ ✅ ✅
Administração de suporte técnico   ✅   ✅ ✅ ✅
Leitor do Centro de Mensagens   ✅ ✅ ✅ ✅ ✅
Administração de palavras-passe ✅ ✅ ✅ ✅ ✅ ✅
Administração de Autenticação Privilegiada         ✅ ✅
Administração de Função Privilegiada         ✅ ✅
Leitor de Relatórios   ✅ ✅ ✅ ✅ ✅
Usuário
(sem função de administrador)		 ✅ ✅ ✅ ✅ ✅ ✅
Usuário
(sem função de administrador, mas membro ou proprietário de um grupo atribuível a funções)		         ✅ ✅
Utilizador com uma função confinada a uma unidade administrativa de gestão restrita         ✅ ✅
Administração de utilizador       ✅ ✅ ✅
Leitor de relatórios de resumo do uso   ✅ ✅ ✅ ✅ ✅
Todas as funções personalizadas ✅ ✅

A capacidade de repor uma palavra-passe inclui a capacidade de atualizar as seguintes propriedades confidenciais necessárias para a reposição personalizada de palavra-passe:

  • businessPhones
  • mobilePhone
  • otherMails

Propriedades comuns

O item a seguir representa o conjunto padrão de propriedades que serão retornadas ao se obter um usuário ou listar usuários. Este é um subconjunto de todas as propriedades disponíveis. Para obter mais propriedades do usuário, use o parâmetro de consulta $select. Saiba como usar o parâmetro $selecionar consulta e consulte propriedades que dão suporte ao parâmetro $selecionar consulta.

Propriedade Descrição
id O identificador exclusivo do usuário.
businessPhones Os números de telefone do usuário.
displayName O nome exibido no catálogo de endereços do usuário.
givenName O nome do usuário.
jobTitle O cargo do usuário.
email O endereço de email do usuário.
mobilePhone O número de telefone celular do usuário.
officeLocation O local do escritório físico do usuário.
preferredLanguage O idioma preferencial do usuário.
surname O sobrenome do usuário.
userPrincipalName O nome UPN do usuário.

Para obter detalhes e uma lista de todas as propriedades, confira o objeto user.

Limitações de pesquisa de usuário e grupo para usuários convidados em organizações

Os recursos de pesquisa de usuário e grupo permitem que o aplicativo pesquise usuários ou grupos em um diretório da organização executando consultas no conjunto de recursos /users ou /groups (por exemplo, https://graph.microsoft.com/v1.0/users). Tanto os administradores como os utilizadores que são membros têm esta capacidade; no entanto, os utilizadores convidados não.

Se o usuário conectado for um convidado, dependendo das permissões que recebeu um aplicativo, ele pode ler o perfil de um usuário específico ou grupo (por exemplo, https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531). No entanto, o usuário não pode executar consultas no conjunto de recursos /users ou /groups que, potencialmente, retornam mais de um recurso.

Com as permissões apropriadas, o aplicativo pode ler os perfis de usuários ou grupos que ele obtém seguindo os links nas propriedades de navegação. Por exemplo, /users/{id}/directReports ou /groups/{id}/members.

Propriedades não devolvidas por predefinição

Algumas propriedades do objeto de utilizador não são devolvidas por predefinição e têm de ser especificadas num $select parâmetro de consulta. Por exemplo, aniversário e competências. Veja a tabela de propriedades da entidade de utilizador para identificar as propriedades que são devolvidas apenas quando .$select

Propriedades armazenadas fora do arquivo de dados main

Embora os dados de recursos do utilizador estejam armazenados principalmente no Microsoft Entra ID, algumas das suas propriedades, como competências, são armazenadas no SharePoint Online. Na maioria das instâncias, não pode especificar estas propriedades no mesmo corpo do pedido Criar ou Atualizar que outras propriedades do utilizador.

As propriedades armazenadas fora do arquivo de dados main também não são suportadas como parte do controlo de alterações. Por conseguinte, uma alteração a qualquer uma destas propriedades não resulta na apresentação de um objeto na resposta da consulta delta.

Conteúdo relacionado