Compartilhar via

Trabalhar com usuários no Microsoft Graph

  • Artigo

O Microsoft Graph permite-lhe criar experiências de aplicações apelativas com base nos utilizadores e nas respetivas relações com outros objetos, como outros utilizadores e grupos, associações a grupos e recursos aos quais acedem, como e-mails, calendários, ficheiros e funções administrativas.

Este artigo explica como aceder e gerir dados de utilizador com o Microsoft Graph, incluindo operações de API comuns, autorização, privilégios e processamento de ações confidenciais.

Aceder aos utilizadores

Aceda aos utilizadores através do Microsoft Graph de duas formas:

  • 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

No Microsoft Graph, os utilizadores são representados pelo tipo de recurso de utilizador . A tabela seguinte lista as operações comuns que pode realizar nos utilizadores.

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.
POST /invitations Convidar um convidado como parte da colaboração empresa-empresa (B2B) no ID externa do Microsoft Entra

Autorização e privilégios

O Microsoft Graph suporta permissões delegadas e de aplicação para gerir operações de utilizador. Compreender estas permissões é fundamental para um desenvolvimento de aplicações seguro e eficiente. Para obter mais informações, veja Permissões delegadas vs. Permissões de 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 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 de outros utilizadores, requerem privilégios administrativos concedidos através de outras permissões do Microsoft Graph que apenas os administradores autorizados podem consentir 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. Os membros são criados nativamente no inquilino. Os convidados associam-se ao inquilino ao resgatar o convite e aceder ao inquilino como convidados de colaboração empresa-empresa (B2B).

Os utilizadores no Microsoft Entra ID têm permissões predefinidas que lhes permitem realizar determinadas operações. Este conjunto de permissões predefinidas depende se o utilizador é um membro ou um utilizador convidado e o administrador inquilino pode alterar as definições para estas permissões predefinidas. 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 em inquilinos externos

Também existem permissões predefinidas para clientes em Microsoft Entra ID em inquilinos externos. A tabela seguinte mostra 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

Perfil básico dos utilizadores

A permissão User.ReadBasic.All restringe o acesso da aplicação à leitura de um conjunto limitado de propriedades para as contas escolares ou profissionais de outros utilizadores. Este perfil básico inclui apenas as seguintes propriedades:

  • displayName
  • givenName
  • id
  • Email
  • photo
  • securityIdentifier
  • surname
  • userPrincipalName

Além disso, as seguintes permissões específicas do cenário também permitem que as aplicações leiam o perfil de utilizador básico que contém principalmente propriedades relacionadas com identificadores:

  • User-Mail.ReadWrite.All
  • User-PasswordProfile.ReadWrite.All
  • User-Phone.ReadWrite.All
  • User-LifeCycleInfo.Read.All
  • User-LifeCycleInfo.ReadWrite.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 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.

Para obter detalhes e uma lista de todas as propriedades, veja o objeto de utilizador .

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 utilizadores e grupos para convidados

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.

As seguintes propriedades no objeto de utilizador são armazenadas fora do arquivo de dados main: signInActivity, cloudLicensing, mailboxSettings, deviceEnrollmentLimit, print, aboutMe, birthday, hireDate, interests, mySite, pastProjects, preferredName, responsibilities, schools, skills.

Conclusão

O Microsoft Graph fornece capacidades avançadas para gerir e interagir com dados de utilizador. Ao compreender as diferentes permissões, operações de API comuns e processar ações confidenciais, pode criar aplicações seguras e eficientes. Para obter mais informações, veja as ligações de conteúdo e documentação relacionadas.

Conteúdo relacionado