Tipo de recurso servicePrincipal
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 uma instância de um aplicativo em um diretório. Herda de directoryObject.
Esse recurso tem suporte para o uso da consulta delta para controlar adições, exclusões e atualizações incrementais oferecendo uma função delta. Esse recurso é um tipo aberto que permite que outras propriedades sejam passadas.
Methods
Método | Tipo de retorno | Descrição |
---|---|---|
List | servicePrincipal collection | Recupere uma lista de objetos servicePrincipal. |
Create | servicePrincipal | Cria um novo objeto servicePrincipal. |
Get | servicePrincipal | Leia as propriedades e as relações do objeto servicePrincipal. |
Atualizar | Nenhum(a) | Atualize o objeto servicePrincipal. |
Upsert | servicePrincipal | Crie um novo servicePrincipal se não existir ou atualize as propriedades de um servicePrincipal existente. |
Delete | Nenhum | Exclua o objeto servicePrincipal. |
Obter delta | servicePrincipal collection | Obtenha alterações incrementais para entidades de serviço. |
Listar objetos criados | directoryObject collection | Obtenha uma coleção de objeto createdObject. |
Listar objetos de propriedade | Coleção directoryObject | Obtenha uma coleção de objeto ownedObject. |
Itens excluídos | ||
List | Coleção directoryObject | Recupere uma lista de objetos servicePrincipal excluídos recentemente. |
Get | directoryObject | Recupere as propriedades de um objeto servicePrincipal excluído recentemente. |
Restaurar | directoryObject | Restaure um objeto servicePrincipal excluído recentemente. |
Excluir permanentemente | Nenhum | Exclua permanentemente um objeto servicePrincipal. |
Atribuição de funções do aplicativo | ||
List appRoleAssignments | appRoleAssignment collection | Obtenha as funções de aplicação atribuídas a este principal de serviço. |
Adicionar uma atribuição de função do aplicativo | appRoleAssignment | Atribuir uma função de aplicativo a essa entidade de serviço. |
Remover uma atribuição de função do aplicativo | Nenhum(a) | Remover uma atribuição de função de aplicativo dessa entidade de serviço. |
Listar appRoleAssignedTo | coleção appRoleAssignment | Obtenha os usuários, grupos e funções de aplicativo atribuídos a essa entidade de serviço. |
Adicionar appRoleAssignedTo | appRoleAssignment | Atribuir uma função de aplicativo dessa entidade de serviço a um usuário, grupo ou entidade de serviço. |
Remover appRoleAssignedTo | Nenhum(a) | Remova uma atribuição de função de aplicativo dessa entidade de serviço de um usuário, grupo ou entidade de serviço. |
Certificados e segredos | ||
Adicionar senha | passwordCredential | Adicione uma senha ou segredo forte a um servicePrincipal. |
Remover senha | passwordCredential | Remova uma senha ou segredo de um servicePrincipal. |
Adicionar chave | keyCredential | Adicione uma credencial de chave a uma servicePrincipal. |
Remover chave | Nenhum(a) | Remova uma credencial de chave de uma servicePrincipal. |
Adicionar certificado de assinatura de token | selfSignedCertificate | Adicione um certificado autoassinado ao principal de serviço. Utilização principal para configurar aplicações SSO baseadas em SAML a partir da galeria de Microsoft Entra. |
Classificações de permissão delegada | ||
List | Coleção delegatedPermissionClassification | Obtenha as classificações de permissão para permissões delegadas expostas por essa entidade de serviço. |
Add | delegatedPermissionClassification | Adicione uma classificação de permissão para uma permissão delegada exposta por essa entidade de serviço. |
Remove | Nenhum | Remova uma classificação de permissão para uma permissão delegada exposta por essa entidade de serviço. |
Concessões de permissão delegadas (OAuth2) | ||
List | oAuth2PermissionGrant collection | Obtenha as concessões de permissão delegadas que autorizam essa entidade de serviço a acessar uma API em nome de um usuário conectado. |
Associação | ||
Listar memberOf | directoryObject collection | Obtenha grupos dos quais essa entidade de serviço é membro direto da propriedade de navegação memberOf. |
Listar membro transitivo de | directoryObject collection | Liste os grupos dos quais essa entidade de serviço é membro. Essa operação é transitiva e inclui os grupos dos quais essa entidade de serviço é um membro aninhado. |
Verificar grupos de membros | Coleção de cadeias de caracteres | Verifique se há associação em uma lista de grupos específica. |
Verificar objetos de membro | Coleção de cadeias de caracteres | Verificar se há afiliação em uma lista de grupo específica, funções de diretório ou objetos de unidade administrativa. |
Obter grupos de membros | Coleção de cadeias de caracteres | Obtenha a lista de grupos dos quais essa entidade de serviço é membro. |
Obter objetos de membros | String collection | Obtenha a lista de grupos e funções de diretório dos quais essa entidade de serviço é membro. |
Owners | ||
List | Coleção directoryObject | Obtenha os proprietários de um principal de serviço. |
Add | directoryObject | Atribuir um proprietário a um principal de serviço. Os proprietários do principal de serviço podem ser utilizadores ou outros principais de serviço. |
Remove | Nenhum | Remover um proprietário de um principal de serviço. Como melhor prática recomendada, os principais de serviço devem ter, pelo menos, dois proprietários. |
Credenciais de início de sessão único baseado em palavra-passe | ||
Create | passwordSingleSignOnCredentialSet | Crie uma credencial definida para o usuário ou grupo especificado no corpo. |
Get | passwordSingleSignOnCredentialSet | Obtenha um conjunto de credenciais para o usuário ou grupo especificado no corpo. |
Atualizar | Nenhum | Atualize um conjunto de credenciais para o usuário ou grupo especificado no corpo. |
Delete | Nenhum | Exclua uma credencial definida para o usuário ou grupo especificado no corpo. |
Propriedades
Importante
O uso específico de $filter
e o parâmetro de consulta $search
é suportado somente quando se usa o cabeçalho ConsistencyLevel definido como eventual
e $count
. Para obter mais informações, veja Capacidades avançadas de consulta em objetos de diretório.
Propriedade | Tipo | Descrição |
---|---|---|
accountEnabled | Booliano |
true se a conta da entidade de serviço estiver habilitada; caso contrário, false . Se estiver definido false como , os utilizadores não poderão iniciar sessão nesta aplicação, mesmo que estejam atribuídos à mesma. Suporta $filter (eq , ne , not , in ). |
addIns | Coleção addIn | Define o comportamento personalizado que um serviço de consumo pode usar para chamar um aplicativo em contextos específicos. Por exemplo, aplicativos que podem renderizar fluxos de arquivo podem definir a propriedade addIns para a funcionalidade "FileHandler". Isto permite que serviços como o Microsoft 365 chamem a aplicação no contexto de um documento em que o utilizador está a trabalhar. |
alternativeNames | Coleção de cadeias de caracteres | Utilizado para obter principais de serviço por subscrição, identifique o grupo de recursos e os IDs de recursos completos para identidades geridas. Suporta $filter (eq , not , ge , le , startsWith ). |
appDescription | String | A descrição exposta pelo aplicativo associado. |
appDisplayName | String | O nome de exibição exposto pelo aplicativo associado. O comprimento máximo é de 256 caracteres. |
appId | String | O identificador exclusivo do aplicativo associado (sua propriedade appId). Chave alternativa. Suporta $filter (eq , ne , not , in , startsWith ). |
applicationTemplateId | Cadeia de caracteres | Identificador exclusivo do applicationTemplate. Suporta $filter (eq , not , ne ). Somente leitura.
null se a aplicação não tiver sido criada a partir de um modelo de aplicação. |
appOwnerOrganizationId | Guid | Contém o ID do inquilino onde a aplicação está registada. Isso é aplicável apenas a entidades de serviço respaldadas por aplicativos. Suporta $filter (eq , ne , NOT , ge , le ). |
appRoleAssignmentRequired | Booliano | Especifica se os usuários ou outras entidade de serviço precisam receber uma atribuição de função de aplicativo para essa entidade de serviço antes que os usuários possam entrar ou os aplicativos possam obter tokens. O valor padrão é false . Não anulável. Suporta $filter (eq , ne , NOT ). |
appRoles | Coleção appRole | As funções expostas pela aplicação, que este principal de serviço representa. Para obter mais informações, veja a definição da propriedade appRoles na entidade da aplicação . Não anulável. |
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. Retornado apenas em $select . Suporta $filter (eq , ne , not , startsWith ). O valor do filtro é sensível às maiúsculas e minúsculas. |
deletedDateTime | DateTimeOffset | A data e a hora em que a entidade de serviço foi excluída. Somente leitura. |
description | String | Campo de texto disponível para fornecer uma descrição voltada para o usuário final interno da entidade de serviço. Os portais do utilizador final, como MyApps , apresentam a descrição da aplicação neste campo. O tamanho máximo permitido é de 1024 carateres. Suporta $filter (eq , ne , not , ge , le , startsWith ) e $search . |
disabledByMicrosoftStatus | Cadeia de caracteres | Especifica se a Microsoft desabilitou o aplicativo registrado. Os valores possíveis são: null (valor padrão), NotDisabled e DisabledDueToViolationOfServicesAgreement (os motivos podem incluir atividades suspeitas, abusivas ou maliciosas ou uma violação do Contrato de Serviços Microsoft). Suporta $filter (eq , ne , not ). |
displayName | String | O nome de exibição da entidade de serviço. Suporte $filter (eq , ne , not , ge , le , in , startsWith , e eq no null valores), $search , e $orderby . |
errorUrl | Cadeia de caracteres | Depreciado. Não usar. |
homepage | Cadeia de caracteres | Página inicial ou página de aterrissagem do aplicativo. |
id | Cadeia de caracteres | O identificador exclusivo da entidade de serviço. Herdado de directoryObject. Chave. Não anulável. Somente leitura. Suporta $filter (eq , ne , not , in ). |
informações | informationalUrl | Informações básicas de perfil do aplicativo adquirido, como marketing, suporte, termos de serviço e URLs de política de privacidade do aplicativo. Os termos de serviço e a política de privacidade são revelados aos usuários por meio da experiência de consentimento do usuário. Para obter mais informações, consulte Como: Adicionar Termos de serviço e declaração de privacidade para aplicações Microsoft Entra registadas. Suporta $filter (eq , ne , not , ge , le e eq em null valores). |
keyCredentials | keyCredential collection | A coleção de credenciais principais associada à entidade de serviço. Não anulável. Suporta $filter (eq , not , ge , le ). |
loginUrl | Cadeia de caracteres | Especifica o URL onde o fornecedor de serviços redireciona o utilizador para Microsoft Entra ID para autenticar. Microsoft Entra ID utiliza o URL para iniciar a aplicação a partir do Microsoft 365 ou do Microsoft Entra Meus Aplicativos. Quando estiver em branco, Microsoft Entra ID efetua o início de sessão iniciado pelo IdP para aplicações configuradas com o início de sessão único baseado em SAML. O utilizador inicia a aplicação a partir do Microsoft 365, do Microsoft Entra Meus Aplicativos ou do URL de SSO Microsoft Entra. |
logoutUrl | Cadeia de caracteres | Especifica o URL que o serviço de autorização da Microsoft utiliza para terminar sessão de um utilizador com os protocolos de front-channel, back-channel ou SAML do OpenId Connect. |
notes | String | Campo de texto disponível para capturar informações sobre o principal do serviço, normalmente usado para fins operacionais. O tamanho máximo permitido é de 1024 carateres. |
NotificationEmailAddresses | Coleção de cadeias de caracteres | Especifica a lista de endereços de e-mail em que Microsoft Entra ID envia uma notificação quando o certificado ativo está perto da data de expiração. Isto destina-se apenas aos certificados utilizados para assinar o token SAML emitido para aplicações da Galeria de Microsoft Entra. |
passwordCredentials | passwordCredential collection | A coleção de credenciais de senha associada à entidade de serviço. Não anulável. |
passwordSingleSignOnSettings | passwordSingleSignOnSettings | A coleção para configurações relacionadas a senha de acesso único. Utilize $select=passwordSingleSignOnSettings para fazer a çeitura da propriedade.. Somente leitura para applicationTemplates com exceção para ApplicationTemplates personalizados. |
preferredSingleSignOnMode | cadeia de caracteres | Especifica o modo de logon único configurado para este aplicativo. Microsoft Entra ID utiliza o modo de início de sessão único preferencial para iniciar a aplicação a partir do Microsoft 365 ou do Microsoft Entra Meus Aplicativos. Os valores com suporte são: password , saml , notSupported , e oidc .
Nota: Este campo pode ser null para aplicações SAML mais antigas e para aplicações OIDC onde não é definido automaticamente. |
permissionGrantPreApprovalPolicies | permissionGrantPreApprovalPolicy collection (coleção permissionGrantPreApprovalPolicy ) | A lista de políticas pré-aprovadas que foram atribuídas ao principal de serviço. |
preferredTokenSigningKeyEndDateTime | DateTimeOffset | Especifica a data da expiração do keyCredential usado para a assinatura do token, marcado por preferredTokenSigningKeyThumbprint. A atualização deste atributo não é atualmente suportada. Para obter detalhes, veja ServicePrincipal property differences (Diferenças de propriedades do ServicePrincipal). |
preferredTokenSigningKeyThumbprint | String | Esta propriedade pode ser utilizada em aplicações SAML (aplicações que têm preferredSingleSignOnMode definido como saml ) para controlar que certificado é utilizado para assinar as respostas SAML. Para aplicações que não são SAML, não escreva ou de outra forma dependa desta propriedade. |
publishedPermissionScopes | coleção permissionScope | As permissões delegadas expostas pelo aplicativo. Para obter mais informações, veja a propriedade oauth2PermissionScopes na propriedade API da entidade da aplicação. Não anulável. Observação: Essa propriedade é chamada oauth2PermissionScopes em v1.0. |
publisherName | String | O nome do inquilino Microsoft Entra que publicou a aplicação. |
replyUrls | String collection | As URLs às quais os tokens de usuário são enviados para entrar com aplicativo associado ou os URIs de redirecionamento aos quais os códigos de autorização do OAuth 2.0 e tokens de acesso são enviados para o aplicativo associado. Não anulável. |
samlMetadataUrl | Cadeia de caracteres | O url em que o serviço expõe os metadados SAML para federação. |
samlSingleSignOnSettings | samlSingleSignOnSettings | A coleção das configurações relacionadas ao logon único do SAML. |
servicePrincipalNames | Coleção de cadeias de caracteres | Contém a lista de identificadoresUris, copiados do aplicativo associado. Mais valores podem ser adicionados a aplicações híbridas. Estes valores podem ser utilizados para identificar as permissões expostas por esta aplicação no Microsoft Entra ID. Por exemplo,
O operador any é obrigatório para expressões de filtro em propriedades de vários valores. Não anulável. Suporta $filter (eq , not , ge , le , startsWith ). |
servicePrincipalType | Cadeia de caracteres | Identifica se a entidade de serviço representa um aplicativo ou uma identidade gerenciada. Esta definição é definida por Microsoft Entra ID internamente. Para uma entidade de serviço que representa um aplicativo, isso é definido como Aplicativo. Para um principal de serviço que representa uma identidade gerida , este é definido como ManagedIdentity. O tipo SocialIdp é para uso interno. |
signInAudience | Cadeia de caracteres | Especifique quais contas Microsoft têm suporte para o aplicativo atual. Somente leitura. Os valores com suporte são:
|
tags | Coleção de cadeias de caracteres | Cadeias de caracteres personalizadas que podem ser usadas para categorizar e identificar a entidade de serviço. Não anulável. O valor é a união de cadeias definida aqui e na propriedade de etiquetas da entidade de aplicação associada. Suporta $filter (eq , not , ge , le , startsWith ). |
tokenEncryptionKeyId | Cadeia de caracteres | Especifica a keyId de uma chave pública da coleção keyCredentials. Quando configurado, Microsoft Entra ID os tokens de problemas para esta aplicação encriptados com a chave especificada por esta propriedade. O código de aplicativo que recebe o token criptografado deve usar a chave privada correspondente para descriptografar o token a fim de que ele possa ser usado para o usuário conectado. |
verifiedPublisher | verifiedPublisher | Especifica o publicador verificado da aplicação que está ligada a este principal de serviço. |
Relações
Importante
A utilização específica do $filter
parâmetro de consulta só é suportada quando utiliza o cabeçalho ConsistencyLevel definido como eventual
e $count
. Para obter mais informações, veja Capacidades avançadas de consulta em objetos de diretório.
Relação | Tipo | Descrição |
---|---|---|
appManagementPolicies | appManagementPolicy collection | O appManagementPolicy aplicado a este principal de serviço. |
appRoleAssignedTo | appRoleAssignment | Atribuições de função de aplicativo para este aplicativo ou serviço, concedidas a usuários, grupos e outras entidades de serviço. Suporta $expand . |
appRoleAssignments | appRoleAssignment collection | Atribuição de função de aplicativo para outro aplicativo ou serviço, concedida a essa entidade de serviço. Suporta $expand . |
claimsMappingPolicies | Conjunto claimsMappingPolicy | O claimsMappingPolicies atribuído a essa entidade de serviço. Suporta $expand . |
claimsPolicy | customClaimsPolicy | Uma política de afirmações que permite aos administradores de aplicações personalizar as afirmações que serão emitidas em tokens afetados por esta política. |
createdObjects | directoryObject collection | Objetos de diretório criados pela entidade de serviço. Somente leitura. Anulável. |
delegatedPermissionClassifications | Conjunto de delegatedPermissionClassification | As classificações de permissão para permissões delegadas expostas pelo aplicativo que essa entidade de serviço representa. Suporta $expand . |
pontos de extremidade | coleção ponto de extremidade | Pontos de extremidade disponíveis para descoberta. Serviços como o Sharepoint preenchem essa propriedade com pontos de extremidade do SharePoint específicos de locatários que outros aplicativos podem descobrir e usar em suas experiências. |
homeRealmDiscoveryPolicies | Conjunto homeRealmDiscoveryPolicy | O homeRealmDiscoveryPolicies atribuído a essa entidade de serviço. Suporta o $expand . |
memberOf | directoryObject collection | Funções das quais essa entidade de serviço é membro. Métodos HTTP: GET somente leitura. Anulável. Suporta o $expand . |
oauth2PermissionGrants | oAuth2PermissionGrant collection | Concessões de permissão delegadas que autorizam essa entidade de serviço a acessar uma API em nome de um usuário conectado. Somente leitura. Anulável. |
ownedObjects | directoryObject collection | Objetos de diretório que pertencem a essa entidade de serviço. Somente leitura. Anulável.
$expand Suporta e $filter (/$count eq 0 , /$count ne 0 , /$count eq 1 , /$count ne 1 ). |
owners | Coleção directoryObject | Objetos de diretório que são proprietários dessa servicePrincipal. Os proprietários são um conjunto de utilizadores não administradores ou servicePrincipals que têm permissão para modificar este objeto. Somente leitura. Anulável.
$expand Suporta e $filter (/$count eq 0 , /$count ne 0 , /$count eq 1 , /$count ne 1 ). |
remoteDesktopSecurityConfiguration | remoteDesktopSecurityConfiguration | O objeto remoteDesktopSecurityConfiguration aplicado a este principal de serviço.
$filter Suporta (eq ) para a propriedade isRemoteDesktopProtocolEnabled. |
sincronização | sincronização | Representa a capacidade de sincronização de identidades Microsoft Entra através do Microsoft API do Graph. |
tokenIssuancePolicies | coleção tokenIssuancePolicy | As tokenIssuancePolicies atribuídas a essa entidade de serviço. Suporta $expand . |
tokenLifetimePolicies | Conjunto tokenLifetimePolicy | O tokenLifetimePolicies atribuído a essa entidade de serviço. Suporta $expand . |
Representação JSON
A representação JSON seguinte mostra o tipo de recurso.
{
"accountEnabled": true,
"addIns": [{"@odata.type": "microsoft.graph.addIn"}],
"alternativeNames": "String",
"appDisplayName": "String",
"appId": "String",
"appOwnerOrganizationId": "Guid",
"applicationTemplateId": "String",
"appRoleAssignmentRequired": true,
"appRoles": [{"@odata.type": "microsoft.graph.appRole"}],
"customSecurityAttributes": {
"@odata.type": "microsoft.graph.customSecurityAttributeValue"
},
"disabledByMicrosoftStatus": "String",
"displayName": "String",
"errorUrl": "String",
"homepage": "String",
"id": "String (identifier)",
"info": {"@odata.type": "microsoft.graph.informationalUrl"},
"keyCredentials": [{"@odata.type": "microsoft.graph.keyCredential"}],
"loginUrl": "String",
"logoutUrl": "String",
"notes": "String",
"notificationEmailAddresses": ["String"],
"publishedPermissionScopes": [{"@odata.type": "microsoft.graph.permissionScope"}],
"passwordCredentials": [{"@odata.type": "microsoft.graph.passwordCredential"}],
"passwordSingleSignOnSettings": {"@odata.type": "microsoft.graph.passwordSingleSignOnSettings"},
"preferredSingleSignOnMode": "String",
"preferredTokenSigningKeyEndDateTime": "DateTime",
"preferredTokenSigningKeyThumbprint": "String",
"publisherName": "String",
"replyUrls": ["String"],
"samlMetadataUrl": "String",
"samlSingleSignOnSettings": "microsoft.DirectoryServices.SamlSingleSignOnSettings",
"servicePrincipalNames": ["String"],
"servicePrincipalType": "String",
"signInAudience": "String",
"tags": ["String"],
"tokenEncryptionKeyId": "String",
"verifiedPublisher": {"@odata.type": "microsoft.graph.verifiedPublisher"}
}