Share via

Obter um servicePrincipal

  • Artigo

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.

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.
Aplicativo 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 $expandparâmetros de consulta OData para ajudar a personalizar a resposta.

Esse método dá suporte aos $countparâmetros de consulta , $expand, $filter, $orderby, $search, $selecte $topOData 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, consulte Recursos avançados 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 $selectconsulta. 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: recuperar uma entidade de serviço por seu 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 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

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
}