Obter um servicePrincipal
Namespace: microsoft.graph
Recuperar as propriedades e as relações de um objeto servicePrincipal.
Essa API está disponível nas seguintes implantações nacionais de nuvem.
Serviço global | Governo dos EUA L4 | GOVERNO DOS EUA L5 (DOD) | China operada pela 21Vianet |
---|---|---|---|
✅ | ✅ | ✅ | ✅ |
Permissões
Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.
Tipo de permissão | Permissões menos privilegiadas | Permissões privilegiadas mais altas |
---|---|---|
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 um aplicativo chame GET /applications
e GET /servicePrincipals
liste todos os aplicativos e entidades de serviço no locatário. Esse escopo de acesso foi permitido para a permissão.
Solicitação HTTP
Você pode abordar a entidade de serviço usando sua id ou appId. Id e appId são chamados de ID de Objeto e ID do Aplicativo (Cliente), respectivamente, em registros de aplicativo 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.
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: recuperar uma entidade de serviço por sua ID
Solicitação
O exemplo a seguir mostra uma solicitação.
GET https://graph.microsoft.com/v1.0/servicePrincipals/00063ffc-54e9-405d-b8f3-56124728e051
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
{
"accountEnabled": true,
"addIns": [],
"alternativeNames": ["http://contoso/a7770d29-4321-41a6-b863-ca11d6639448"],
"appDisplayName": "My app",
"appId": "appId-value",
"appOwnerOrganizationId": "65415bb1-9267-4313-bbf5-ae259732ee12",
"appRoleAssignmentRequired":true,
"appRoles": [],
"disabledByMicrosoftStatus": null,
"displayName": "My app instance in tenant",
"endpoints": [],
"homepage": null,
"id": "00af5dfb-85da-4b41-a677-0c6b86dd34f8",
"verifiedPublisher": {
"displayName": "publisher_contoso",
"verifiedPublisherId": "9999999",
"addedDateTime": "2021-04-24T17:49:44Z"
},
"info": {
"termsOfServiceUrl": null,
"supportUrl": null,
"privacyStatementUrl": null,
"marketingUrl": null,
"logoUrl": null
},
"keyCredentials": [],
"logoutUrl": null,
"oauth2PermissionScopes": [],
"passwordCredentials": [],
"publisherName": null,
"replyUrls": [],
"resourceSpecificApplicationPermissions": [],
"servicePrincipalNames": [],
"servicePrincipalType": null,
"signInAudience": "AzureADandPersonalMicrosoftAccount",
"tags": [],
"tokenEncryptionKeyId": null
}
Exemplo 2: recuperar as propriedades específicas de uma entidade de serviço
Solicitação
O exemplo a seguir mostra uma solicitação.
GET https://graph.microsoft.com/v1.0/servicePrincipals/7408235b-7540-4850-82fe-a5f15ed019e2?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,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"
}
],
"oauth2PermissionScopes": [
{
"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 atributo de segurança personalizadas da entidade de serviço especificada
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
O exemplo a seguir mostra uma solicitação.
GET https://graph.microsoft.com/v1.0/servicePrincipals/{id}?$select=customSecurityAttributes
Resposta
O exemplo a seguir mostra a resposta.
HTTP/1.1 200 OK
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/v1.0/$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/v1.0/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
"customSecurityAttributes": null
}
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários