Obter um 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.
Recuperar as propriedades e as relações de um objeto servicePrincipal.
Esta API está disponível nas seguintes implementações de cloud nacionais.
Serviço global | US Government L4 | US Government L5 (DOD) | China operada pela 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.
Tipo de permissão | Permissões com menos privilégios | Permissões com privilégios superiores |
---|---|---|
Delegado (conta corporativa ou de estudante) | Application.Read.All | Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Delegado (conta pessoal da Microsoft) | Sem suporte. | Sem suporte. |
Application | Application.Read.All | Application.ReadWrite.OwnedBy, Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All |
Observação
- Uma entidade de serviço pode recuperar seus próprios detalhes de aplicativo e entidade de serviço sem receber nenhuma permissão de aplicativo.
- A permissão Application.ReadWrite.OwnedBy permite que uma aplicação chame
GET /applications
eGET /servicePrincipals
liste todas as aplicações e principais de serviço no inquilino. Este âmbito de acesso foi permitido para a permissão. - Para ler a propriedade customSecurityAttributes :
- Em cenários delegados, tem de ser atribuída ao administrador a função Administrador de Atribuição de Atributos e a aplicação concedeu a permissão delegada CustomSecAttributeAssignment.Read.All .
- Em cenários apenas de aplicações com permissões do Microsoft Graph, a aplicação tem de ter a permissão de aplicação CustomSecAttributeAssignment.Reade.All .
Solicitação HTTP
Pode abordar o principal de serviço com o respetivo ID ou appId. O id e o appId são referidos como o ID do Objeto e o ID da Aplicação (Cliente), respetivamente, nos registos de aplicações no centro de administração do Microsoft Entra.
GET /servicePrincipals/{id}
GET /servicePrincipals(appId='{appId}')
Parâmetros de consulta opcionais
Este método oferece suporte aos $select
e $expand
parâmetros de consulta OData para ajudar a personalizar a resposta.
Este método suporta os $count
parâmetros de consulta , $expand
, $filter
$orderby
, $search
, $select
, e $top
OData para ajudar a personalizar a resposta. Algumas consultas são suportadas 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.
Por padrão, esta API não retorna o valor da chave pública da chave na propriedade keyCredentials a menos que keyCredentials seja especificado em uma $select
consulta.
Por exemplo, $select=id,appId,keyCredentials
.
O uso de $select
para obter keyCredentials para diretores de serviços tem um limite de 150 pedidos por minuto para cada locatário.
Cabeçalhos de solicitação
Nome | Descrição |
---|---|
Autorização | {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização. |
Accept-Language | Código de idioma. Opcional. |
Fornecer o cabeçalho Accept-Language com um código de idioma compatível, como es-ES
ou de-DE
, retornará valores localizados quando disponíveis. Observe que o cabeçalho não é compatível com operações de lista.
Corpo da solicitação
Não forneça um corpo de solicitação para esse método.
Resposta
Se bem-sucedido, este método retorna um código de resposta 200 OK
e um objeto servicePrincipal no corpo da resposta.
Exemplos
Exemplo 1: Obter as propriedades da entidade de serviço especificada
Solicitação
O exemplo a seguir mostra uma solicitação.
GET https://graph.microsoft.com/beta/servicePrincipals/{id}
Resposta
O exemplo a seguir mostra a resposta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 200 OK
Content-type: application/json
{
"id": "59e617e5-e447-4adc-8b88-00af644d7c92",
"deletedDateTime": null,
"accountEnabled": true,
"appDisplayName": "My App",
"appId": "65415bb1-9267-4313-bbf5-ae259732ee12",
"applicationTemplateId": null,
"appOwnerOrganizationId": "1bc1c026-2f7b-48a5-98da-afa2fd8bc7bc",
"appRoleAssignmentRequired": false,
"disabledByMicrosoftStatus": null,
"displayName": "foo",
"errorUrl": null,
"homepage": null,
"loginUrl": null,
"logoutUrl": null,
"notificationEmailAddresses": [],
"preferredSingleSignOnMode": null,
"preferredTokenSigningKeyEndDateTime": null,
"preferredTokenSigningKeyThumbprint": null,
"publisherName": "Contoso",
"replyUrls": [],
"samlMetadataUrl": null,
"samlSingleSignOnSettings": null,
"servicePrincipalNames": [
"f1bd758f-4a1a-4b71-aa20-a248a22a8928"
],
"signInAudience": "AzureADandPersonalMicrosoftAccount",
"tags": [],
"verifiedPublisher": {
"displayName": "publisher_contoso",
"verifiedPublisherId": "9999999",
"addedDateTime": "2021-04-24T17:49:44Z"
},
"addIns": [],
"api": {
"resourceSpecificApplicationPermissions": []
},
"appRoles": [],
"info": {
"termsOfServiceUrl": null,
"supportUrl": null,
"privacyStatementUrl": null,
"marketingUrl": null,
"logoUrl": null
},
"keyCredentials": [],
"publishedPermissionScopes": [],
"passwordCredentials": []
}
Exemplo 2: Obter um principal de serviço pelo appId e apenas propriedades específicas
Solicitação
O exemplo a seguir mostra uma solicitação.
GET https://graph.microsoft.com/beta/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,publishedPermissionScopes,resourceSpecificApplicationPermissions
Resposta
O exemplo a seguir mostra a resposta.
Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(id,appId,displayName,appRoles,publishedPermissionScopes)/$entity",
"id": "7408235b-7540-4850-82fe-a5f15ed019e2",
"appId": "00000003-0000-0000-c000-000000000000",
"displayName": "Microsoft Graph",
"appRoles": [
{
"allowedMemberTypes": [
"Application"
],
"description": "Allows the app to read all class assignments without grades for all users without a signed-in user.",
"displayName": "Read all class assignments without grades",
"id": "6e0a958b-b7fc-4348-b7c4-a6ab9fd3dd0e",
"isEnabled": true,
"origin": "Application",
"value": "EduAssignments.ReadBasic.All"
}
],
"publishedPermissionScopes": [
{
"adminConsentDescription": "Allows the app to see your users' basic profile (e.g., name, picture, user name, email address)",
"adminConsentDisplayName": "View users' basic profile",
"id": "14dad69e-099b-42c9-810b-d002981feec1",
"isEnabled": true,
"type": "User",
"userConsentDescription": "Allows the app to see your basic profile (e.g., name, picture, user name, email address)",
"userConsentDisplayName": "View your basic profile",
"value": "profile"
}
]
}
Exemplo 3: Obter as atribuições de atributos de segurança personalizadas do principal de serviço especificado
O exemplo a seguir obtém os atributos de segurança personalizados da entidade de serviço especificada.
Atributo nº 1
- Conjunto de atributos:
Engineering
- Atributo:
Project
- Tipo de dados de atributo: Coleção de cadeias de caracteres
- Valor do atributo:
["Baker","Cascade"]
Atributo nº 2
- Conjunto de atributos:
Engineering
- Atributo:
CostCenter
- Tipo de dados de atributo: Coleção de inteiros
- Valor do atributo:
[1001]
Atributo nº 3
- Conjunto de atributos:
Engineering
- Atributo:
Certification
- Tipo de dados de atributo: Booliano
- Valor do atributo:
true
Atributo nº 4
- Conjunto de atributos:
Marketing
- Atributo:
Level
- Tipo de dados de atributo: cadeia de caracteres
- Valor do atributo:
"Public"
Para obter atribuições do atributo de segurança personalizadas, a entidade de chamada deve receber a função Leitor de Atribuição de Atributo ou Administrador de Atribuição de Atributo e deve receber a permissão CustomSecAttributeAssignment.Read.All ou CustomSecAttributeAssignment.ReadWrite.All.
Solicitação
GET https://graph.microsoft.com/beta/servicePrincipals/{id}?$select=customSecurityAttributes
Resposta
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
"customSecurityAttributes": {
"Engineering": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Project@odata.type": "#Collection(String)",
"Project": [
"Baker",
"Cascade"
],
"CostCenter@odata.type": "#Collection(Int32)",
"CostCenter": [
1001
],
"Certification": true
},
"Marketing": {
"@odata.type": "#microsoft.graph.customSecurityAttributeValue",
"Level": "Public"
}
}
}
Se não houver atributos de segurança personalizados atribuídos à entidade de serviço ou se a entidade de chamada não tiver acesso, a resposta será semelhante a:
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}