Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
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.
Representa um subtipo especializado de identidade do usuário no Microsoft Entra ID projetado para aplicativos com tecnologia de IA (agentes) que precisam funcionar como operadores digitais. Os usuários do agente permitem que os agentes acessem APIs e serviços que exigem especificamente identidades de usuário, recebendo tokens com idtyp=user declarações. Os usuários agentes são distintos dos usuários humanos e só estão interligados aos usuários por meio de relacionamentos como proprietário, patrocinador e gerente.
Cada usuário agente mantém um relacionamento um-para-um com uma identidade de agente pai e é autenticado por meio das credenciais desse pai. Os usuários agentes têm recursos semelhantes aos do usuário, como serem adicionados a grupos, atribuir licenças e acessar recursos colaborativos, como caixas de correio e chat, enquanto operam sob restrições de segurança, incluindo sem autenticação de senha, sem atribuições de função de administrador privilegiadas e permissões semelhantes aos usuários convidados.
Herda do usuário.
Esse recurso é um tipo aberto que permite propriedades adicionais além daquelas documentadas aqui.
Métodos
| Método | Tipo de retorno | Descrição |
|---|---|---|
| List | Coleção AgentUser | Obtenha uma lista de objetos agentUser . |
| Create | agentUser | Crie um novo objeto agentUser . |
| Get | agentUser | Leia as propriedades e as relações do objeto agentUser . |
| Atualizar | agentUser | Atualize o objeto agentUser . |
| Delete | Nenhum | Exclua o objeto agentUser . |
| Atribuição de funções do aplicativo | ||
| Listar atribuições de função de aplicativo | appRoleAssignment collection | Obtenha as atribuições de função de aplicativo para este usuário agente. |
| Criar atribuição de função de aplicativo | appRoleAssignment | Crie uma nova atribuição de função de aplicativo para este usuário agente. |
| Itens excluídos | ||
| List | Coleção directoryObject | Recupere uma lista de objetos de usuário do agente excluídos recentemente. |
| Get | directoryObject | Recupere as propriedades de um usuário agente excluído recentemente. |
| Restaurar | directoryObject | Restaurar um usuário agente excluído recentemente. |
| Excluir permanentemente | Nenhum | Excluir permanentemente um usuário agente. |
| Objetos de diretório | ||
| Listar objetos de propriedade | Coleção directoryObject | Obtenha os objetos de diretório pertencentes ao usuário agente. |
| Relações organizacionais | ||
| Listar subordinados diretos | Coleção directoryObject | Obtenha os usuários e contatos que se reportam ao usuário agente. |
| Listar gerente | directoryObject | Obtenha o usuário ou contato que é o gerente do usuário do agente. |
| Adicionar gerente | Nenhum | Atribua o gerente do usuário do agente. |
| Remover gerente | Nenhum | Remova o gerente do usuário do agente. |
| Listar associações diretas | Coleção directoryObject | Obtenha os grupos, funções de diretório e unidades administrativas das quais o usuário agente é membro. |
| Listar associações transitivas | Coleção directoryObject | Obtenha os grupos, funções de diretório e unidades administrativas das quais o usuário agente é membro, incluindo associações de grupo aninhadas. |
| Listar relatórios transitivos | Coleção directoryObject | Obtenha os relatórios transitivos para o usuário agente. |
| Patrocinadores | ||
| Lista de patrocinadores | Coleção directoryObject | Obtenha os usuários e grupos responsáveis pelos privilégios de usuário deste agente. |
| Adicionar patrocinadores | Nenhum | Adicione patrocinadores para o usuário agente. |
| Remover patrocinadores | Nenhum | Remova patrocinadores do usuário agente. |
Propriedades
Importante
Embora esse recurso herde do usuário, algumas propriedades não são aplicáveis e retornam null ou valores padrão. Essas propriedades são excluídas da tabela abaixo.
| Propriedade | Tipo | Descrição |
|---|---|---|
| accountEnabled | Booliano |
true se a conta estiver habilitada; caso contrário, false. Essa propriedade é necessária ao criar o objeto. Herdado do usuário. |
| assignedLicenses | Coleção assignedLicense | As licenças atribuídas ao usuário agente, incluindo licenças herdadas (baseadas em grupo). Esta propriedade não diferencia entre licenças atribuídas diretamente e herdadas. Use a propriedade licenseAssignmentStates para identificar as licenças diretamente atribuídas e herdadas. Não anulável. Herdado do usuário. |
| assignedPlans | Coleção assignedPlan | Os planos atribuídos ao usuário agente. Somente leitura. Não anulável. Herdado do usuário. |
| businessPhones | String collection | Os números de telefone do usuário agente. Somente um número pode ser definido para essa propriedade. Somente leitura para usuários sincronizados do diretório local. Herdado do usuário. |
| city | Cadeia de caracteres | A cidade onde o usuário agente está localizado. O comprimento máximo é de 128 caracteres. Herdado do usuário. |
| nuvemRealtimeCommunicationInfo | nuvemRealtimeCommunicationInfo | Informações de comunicação em tempo real da Microsoft relacionadas ao usuário agente. Herdado do usuário. |
| CompanyName | String | O nome da empresa à qual o usuário agente está associado. Essa propriedade pode ser útil para descrever a empresa de onde procede um usuário externo. O tamanho máximo é de 64 caracteres. Herdado do usuário. |
| country | Cadeia de caracteres | O país ou região onde o usuário agente está localizado; por exemplo, US ou UK. O comprimento máximo é de 128 caracteres. Herdado do usuário. |
| createdDateTime | DateTimeOffset | A data e hora em que o usuário agente foi criado no formato ISO 8601 e UTC. Não é possível modificar o valor e ele é preenchido automaticamente quando a entidade é criada. Anulável. Para usuários locais, o valor representa quando eles foram criados pela primeira vez no Microsoft Entra ID. A propriedade é null para alguns usuários criados antes de junho de 2018 e usuários locais sincronizados com o Microsoft Entra ID antes de junho de 2018. Somente leitura. Herdado do usuário. |
| creationType | String | Somente leitura. Nulo. Herdado do usuário. |
| customSecurityAttributes | customSecurityAttributeValue | Um tipo complexo aberto que contém o valor de um atributo de segurança personalizado atribuído a um objeto do diretório. Anulável. Herdado do usuário. |
| deletedDateTime | DateTimeOffset | A data e hora que o usuário foi excluído. Herdado de directoryObject. |
| department | String | O nome do departamento onde o usuário trabalha. O comprimento máximo é de 64 caracteres. Herdado do usuário. |
| displayName | String | O nome exibido para o usuário no catálogo de endereços. Geralmente o valor é a combinação do nome, da inicial do nome do meio e do sobrenome do usuário. Essa propriedade é necessária quando um usuário é criado e não pode ser limpa durante atualizações. O comprimento máximo é de 256 caracteres. Herdado do usuário. |
| employeeHireDate | DateTimeOffset | A data e hora em que o usuário foi contratado ou começará a trabalhar se houver uma contratação futura. Herdado do usuário. |
| employeeId | String | O identificador de funcionário atribuído ao usuário pela organização. O comprimento máximo é de 16 caracteres. Herdado do usuário. |
| employeeLeaveDateTime | DateTimeOffset | A data e horário em que o usuário deixou ou deixará a organização. Para ler essa propriedade, o aplicativo de chamada deve receber a permissão User-LifeCycleInfo.Read.All . Para gravar essa propriedade, o aplicativo de chamada deve receber as permissões User.Read.All e User-LifeCycleInfo.ReadWrite.All . Para ler essa propriedade em cenários delegados, o administrador precisa de pelo menos uma das seguintes funções do Microsoft Entra: Administrador de Fluxos de Trabalho do Ciclo de Vida (privilégio mínimo), Leitor Global. Para gravar essa propriedade em cenários delegados, o administrador precisa da função de Administrador Global . Para obter mais informações, consulte Configurar a propriedade employeeLeaveDateTime para um usuário. Herdado do usuário. |
| employeeOrgData | employeeOrgData | Representa os dados da organização (por exemplo, divisão e centro de custo) associados a um usuário. Herdado do usuário. |
| employeeType | String | Captura o tipo de trabalhador corporativo. Por exemplo, Employee, Contractor, Consultant ou Vendor. Herdado do usuário. |
| FaxNumber | String | O número de fax do usuário. Herdado do usuário. |
| givenName | String | O nome fornecido (nome) do usuário. O comprimento máximo é de 64 caracteres. Herdado do usuário. |
| id | String | O identificador exclusivo do usuário. Ele deve ser tratado como um identificador opaco. Herdado de directoryObject. Não anulável. Somente leitura. Herda da entidade |
| identityParentId | Cadeia de caracteres | Faz referência à ID do objeto da identidade do agente associado. Essa propriedade é necessária ao criar o objeto e não pode ser desmarcada durante atualizações. Herdado do usuário. |
| imAddresses | String collection | Os endereços SIP (protocolo de iniciação de sessão) IP de voz instantânea (VOIP) para o usuário. Somente leitura. Herdado do usuário. |
| infoCatalogs | Conjunto de cadeias de caracteres | Identifica os segmentos de informações atribuídos ao usuário. Herdado do usuário. |
| isLicenseReconciliationNeeded | Booliano | Indica se o usuário está pendente de uma atribuição de licença da caixa de correio do Exchange. Somente leitura. Herdado do usuário. |
| isManagementRestricted | Booliano |
true se o usuário for membro de uma unidade administrativa de gerenciamento restrita. Caso contrário, o valor padrão será null e o comportamento padrão será false. Somente leitura. Para gerenciar um usuário que é membro de uma unidade administrativa de gerenciamento restrita, o administrador ou aplicativo de chamada deve receber uma função do Microsoft Entra no escopo da unidade administrativa de gerenciamento restrita. Herdado do usuário. |
| isResourceAccount | Boolean | Não use – reservado para uso futuro. Herdado do usuário. |
| jobTitle | String | O cargo do usuário. O comprimento máximo é de 128 caracteres. Herdado do usuário. |
| licenseAssignmentStates | Coleção licenseAssignmentState | Estado das atribuições de licenças para esse usuário. Também indica as licenças atribuídas diretamente e as que o usuário herdou por meio de associações de grupo. Somente leitura. Herdado do usuário. |
| String | O endereço SMTP do usuário, por exemplo, admin@contoso.com. As alterações nessa propriedade também atualizam a coleção proxyAddresses do usuário para incluir o valor como um endereço SMTP. Esta propriedade não pode conter caracteres de acento. OBSERVAÇÃO: não recomendamos atualizar essa propriedade para perfis de usuário do Azure AD B2C. Use em vez da propriedade otherMails. Herdado do usuário. |
|
| mailNickname | String | O alias de email do usuário. Essa propriedade deve ser especificada quando um usuário é criado. O comprimento máximo é de 64 caracteres. Herdado do usuário. |
| mobilePhone | String | O número de celular principal do usuário. Somente leitura para usuários sincronizados do diretório local. Herdado do usuário. |
| officeLocation | String | A localização do escritório no local de trabalho do usuário. O comprimento máximo é de 128 caracteres. Herdado do usuário. |
| otherMails | Coleção String | Uma lista de endereços de email adicional para o usuário; Por exemplo: ["bob@contoso.com", "Robert@fabrikam.com"]. Pode armazenar até 250 valores, cada um com um limite de 250 caracteres. OBSERVAÇÃO: esta propriedade não pode conter caracteres de acento. Herdado do usuário. |
| postalCode | String | O código postal do endereço postal do usuário. O código postal é específico para o país/região do usuário. Nos Estados Unidos, esse atributo contém o CEP. O comprimento máximo é de 40 caracteres. Herdado do usuário. |
| preferredDataLocation | String | O local de dados preferido para o usuário. Para saber mais, confira OneDrive Online Multi-Geo. Herdado do usuário. |
| preferredLanguage | String | O idioma preferencial do usuário. O formato de idioma preferencial é baseado no RFC 4646. O nome combina um código de cultura ISO 639 de duas letras minúsculas associado ao idioma e um código de subcultura ISO 3166 de duas letras maiúsculas associado ao país ou região. Exemplo: "en-US" ou "es-ES". Herdado do usuário. |
| provisionedPlans | coleção provisionedPlan | Os planos que estão provisionados para o usuário. Somente leitura. Não anulável. Herdado do usuário. |
| proxyAddresses | Coleção de cadeias de caracteres | Por exemplo: ["SMTP: bob@contoso.com", "smtp: bob@sales.contoso.com"]. As alterações na propriedade mail também atualizam essa coleção para incluir o valor como um endereço SMTP. Para obter mais informações, consulte propriedades de email e proxyAddresses. O endereço de proxy prefixado com SMTP (maiúsculo) é o endereço de proxy principal, enquanto os prefixados com smtp são os endereços de proxy secundários. Para contas B2C do Azure AD, esta propriedade tem um limite de 10 endereços exclusivos. Somente leitura no Microsoft Graph; você pode atualizar essa propriedade somente por meio do Microsoft 365 de administração. Não anulável. Herdado do usuário. |
| refreshTokensValidFromDateTime | DateTimeOffset | Todos os tokens de atualização ou tokens de sessão (cookies de sessão) emitidos antes desse horário são inválidos, e os aplicativos recebem um erro ao usar um token de atualização ou sessões inválido para adquirir um token de acesso delegado (para acessar APIs como o Microsoft Graph). Se isso acontecer, o aplicativo deverá adquirir um novo token de atualização solicitando o ponto de extremidade autorizado. Somente leitura. Use invalidateAllRefreshTokens para redefinir. Herdado do usuário. |
| securityIdentifier | Cadeia de Caracteres | Identificador de segurança (SID) do usuário, usado em cenários do Windows. Somente leitura. Devolvido por padrão. Herdado do usuário. |
| showInAddressList | Booliano | Não use no Microsoft Graph. Em vez disso, gerencie essa propriedade por meio do Centro de administração do Microsoft 365. Representa se o usuário agente deve ser incluído na lista de endereços global do Outlook. Consulte Problema conhecido. Herdado do usuário. |
| signInSessionsValidFromDateTime | DateTimeOffset | Todos os tokens de atualização ou tokens de sessão (cookies de sessão) emitidos antes desse horário são inválidos, e os aplicativos recebem um erro ao usar um token de atualização ou sessões inválido para adquirir um token de acesso delegado (para acessar APIs como o Microsoft Graph). Se isso acontecer, o aplicativo deverá adquirir um novo token de atualização solicitando o ponto de extremidade autorizado. Somente leitura. Use revokeSignInSessions para redefinir. Herdado do usuário. |
| state | Cadeia de caracteres | O estado ou província no endereço do usuário do agente. O comprimento máximo é de 128 caracteres. Herdado do usuário. |
| streetAddress | String | O endereço do local de negócios do usuário do agente. O comprimento máximo é de 1024 caracteres. Herdado do usuário. |
| surname | String | O sobrenome do usuário (nome de família ou sobrenome). O comprimento máximo é de 64 caracteres. Herdado do usuário. |
| usageLocation | Cadeia de caracteres | Um código de país de duas letras (padrão ISO 3166). Necessário para usuários agentes que recebem licenças devido a requisitos legais para marcar a disponibilidade de serviços em países. Os exemplos incluem:US,JP e GB. Não anulável. Herdado do usuário. |
| userPrincipalName | Cadeia de caracteres | O nome UPN do usuário agente. O UPN é um nome de entrada no estilo da Internet para o usuário com base no padrão da Internet RFC 822. Por convenção, isso deve mapear para o nome de e-mail do usuário do agente. O formato geral é alias@domain, em que o domínio deve estar presente na coleção de domínios verificados do locatário. Essa propriedade é obrigatória quando um usuário é criado. 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 acento. 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. Herdado do usuário. |
| userType | String | Um valor de String que pode ser usado para classificar tipos de usuário de agente em seu diretório. Os valores possíveis são Member e Guest.
OBSERVAÇÃO: Para obter mais informações sobre as permissões para usuários membros e convidados, consulte Quais são as permissões de usuário padrão no Microsoft Entra ID? Herdado do usuário. |
Relações
Importante
Embora esse tipo de recurso herde todas as relações do tipo de recurso usuário , algumas relações não são aplicáveis aos usuários do agente e sempre retornarão null valores ou valores padrão. Essas relações são excluídas da tabela abaixo para maior clareza.
| Relação | Tipo | Descrição |
|---|---|---|
| appRoleAssignments | appRoleAssignment collection | Representa as funções de aplicativo que um usuário agente recebeu para um aplicativo. Herdado do usuário |
| directReports | Coleção directoryObject | Os usuários e contatos que se reportam ao usuário agente. (Os usuários e contatos com suas propriedades de gerente definidas para esse usuário.) Somente leitura. Anulável. Herdado do usuário |
| manager | directoryObject | O usuário ou contato que é o gerente do usuário deste agente. Somente leitura. Herdado do usuário |
| memberOf | Coleção directoryObject | Os grupos, funções de diretório e unidades administrativas das quais o usuário agente é membro. Somente leitura. Anulável. Herdado do usuário |
| ownedObjects | Coleção directoryObject | Objetos de diretório pertencentes ao usuário agente. Somente leitura. Anulável. Herdado do usuário |
| patrocinadores | Coleção directoryObject | Os usuários e grupos responsáveis pelos privilégios do usuário do agente no locatário e mantêm as informações e o acesso do usuário do agente atualizados. (Métodos HTTP: GET, POST, DELETE.). Herdado do usuário |
| transitiveMemberOf | Coleção directoryObject | Os grupos, incluindo grupos aninhados e funções de diretório dos quais o usuário agente é membro. Anulável. Herdado do usuário |
| transitiveReports | Coleção directoryObject | Os relatórios transitivos para um usuário agente. Somente leitura. Herdado do usuário |
Representação JSON
A representação JSON a seguir mostra o tipo de recurso.
{
"@odata.type": "#microsoft.graph.agentUser",
"id": "String (identifier)",
"deletedDateTime": "String (timestamp)",
"accountEnabled": "Boolean",
"assignedLicenses": [
{
"@odata.type": "microsoft.graph.assignedLicense"
}
],
"assignedPlans": [
{
"@odata.type": "microsoft.graph.assignedPlan"
}
],
"businessPhones": [
"String"
],
"city": "String",
"cloudRealtimeCommunicationInfo": {
"@odata.type": "microsoft.graph.cloudRealtimeCommunicationInfo"
},
"companyName": "String",
"country": "String",
"countryCode": "Integer",
"createdDateTime": "String (timestamp)",
"creationType": "String",
"customSecurityAttributes": {
"@odata.type": "microsoft.graph.customSecurityAttributeValue"
},
"department": "String",
"displayName": "String",
"employeeHireDate": "String (timestamp)",
"employeeId": "String",
"employeeOrgData": {
"@odata.type": "microsoft.graph.employeeOrgData"
},
"employeeType": "String",
"employeeLeaveDateTime": "String (timestamp)",
"faxNumber": "String",
"givenName": "String",
"imAddresses": [
"String"
],
"infoCatalogs": [
"String"
],
"isLicenseReconciliationNeeded": "Boolean",
"isManagementRestricted": "Boolean",
"isResourceAccount": "Boolean",
"jobTitle": "String",
"licenseAssignmentStates": [
{
"@odata.type": "microsoft.graph.licenseAssignmentState"
}
],
"mail": "String",
"mailNickname": "String",
"mobilePhone": "String",
"otherMails": [
"String"
],
"officeLocation": "String",
"postalCode": "String",
"preferredDataLocation": "String",
"preferredLanguage": "String",
"provisionedPlans": [
{
"@odata.type": "microsoft.graph.provisionedPlan"
}
],
"proxyAddresses": [
"String"
],
"refreshTokensValidFromDateTime": "String (timestamp)",
"securityIdentifier": "String",
"showInAddressList": "Boolean",
"signInSessionsValidFromDateTime": "String (timestamp)",
"state": "String",
"streetAddress": "String",
"surname": "String",
"usageLocation": "String",
"userPrincipalName": "String",
"userType": "String",
"identityParentId": "String"
}