Compartir a través de

Obtener servicePrincipal

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

Recupera las propiedades y relaciones de un objeto de servicePrincipal.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Application.Read.All Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación Application.Read.All Application.ReadWrite.OwnedBy, Application.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All

Nota:

  • Una entidad de servicio puede recuperar sus propios detalles de aplicación y entidad de servicio sin que se le concedan permisos de aplicación.
  • El permiso Application.ReadWrite.OwnedBy permite a una aplicación llamar GET /applications y GET /servicePrincipals enumerar todas las aplicaciones y entidades de servicio del inquilino. Este ámbito de acceso se ha permitido para el permiso.
  • Para leer la propiedad customSecurityAttributes :
    • En escenarios delegados, al administrador se le debe asignar el rol Administrador de asignación de atributos y a la aplicación se le concede el permiso delegado CustomSecAttributeAssignment.Read.All .
    • En escenarios de solo aplicación con permisos de Microsoft Graph, se debe conceder a la aplicación el permiso de aplicación CustomSecAttributeAssignment.Reade.All .

Solicitud HTTP

Puede dirigirse a la entidad de servicio mediante su id . o appId. id y appId se conocen como id. de objeto y id. de aplicación (cliente), respectivamente, en los registros de aplicaciones en el Centro de administración Microsoft Entra.

GET /servicePrincipals/{id}
GET /servicePrincipals(appId='{appId}')

Parámetros de consulta opcionales

Este método admite los parámetros de consulta $select y $expandOData para ayudar a personalizar la respuesta.

Este método admite los $countparámetros de consulta , $expand, $filter, $orderby$search, $selecty $top OData para ayudar a personalizar la respuesta. Algunas consultas solo se admiten cuando se usa el encabezado ConsistencyLevel establecido en eventual y $count. Para obtener más información, vea Funcionalidades avanzadas de consulta en objetos de directorio.

De forma predeterminada, esta API no devuelve el valor de la clave pública de la clave en la propiedad keyCredentials, a menos que keyCredentials esté especificada en una consulta $select. Por ejemplo, $select=id,appId,keyCredentials.

El uso de $select para obtener keyCredentials para las entidades de servicio tiene un límite de 150 solicitudes por minuto para cada espacio empresarial.

Encabezados de solicitud

Nombre Descripción
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Accept-Language Código de idioma. Opcional.

Proporcionar el encabezado Accept-Language con un código de idioma compatible, como es-ES o de-DE, devolverá valores localizados cuando esté disponible. Tenga en cuenta que el encabezado no es compatible con las operaciones de lista.

Cuerpo de la solicitud

No proporcione un cuerpo de solicitud para este método.

Respuesta

Si se ejecuta correctamente, este método entrega un código de respuesta 200 OK y un objeto servicePrincipal en el cuerpo de la respuesta.

Ejemplos

Ejemplo 1: Obtener las propiedades de la entidad de servicio especificada

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/servicePrincipals/{id}

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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": []
}

Ejemplo 2: Recuperación de una entidad de servicio por su appId y solo propiedades específicas

Solicitud

En el ejemplo siguiente se muestra la solicitud.

GET https://graph.microsoft.com/beta/servicePrincipals(appId='00000003-0000-0000-c000-000000000000')?$select=id,appId,displayName,appRoles,publishedPermissionScopes,resourceSpecificApplicationPermissions

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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"
        }
    ]
}

Ejemplo 3: Obtención de las asignaciones de atributos de seguridad personalizados de la entidad de servicio especificada

En el ejemplo siguiente se obtienen los atributos de seguridad personalizados de la entidad de servicio especificada.

Atributo n.º 1

  • Conjunto de atributos: Engineering
  • Atributo: Project
  • Tipo de datos de atributo: colección de cadenas
  • Valor de atributo: ["Baker","Cascade"]

Atributo n.º 2

  • Conjunto de atributos: Engineering
  • Atributo: CostCenter
  • Tipo de datos de atributo: colección de enteros
  • Valor de atributo: [1001]

Atributo n.º 3

  • Conjunto de atributos: Engineering
  • Atributo: Certification
  • Tipo de datos de atributo: boolean
  • Valor de atributo: true

Atributo n.º 4

  • Conjunto de atributos: Marketing
  • Atributo: Level
  • Tipo de datos de atributo: Cadena
  • Valor de atributo: "Public"

Para obtener asignaciones de atributos de seguridad personalizadas, se debe asignar a la entidad de seguridad de llamada el rol Lector de asignación de atributos o Administrador de asignación de atributos y se le debe conceder el permiso CustomSecAttributeAssignment.Read.All o CustomSecAttributeAssignment.ReadWrite.All.

Solicitud

GET https://graph.microsoft.com/beta/servicePrincipals/{id}?$select=customSecurityAttributes

Respuesta

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"
        }
    }
}

Si no hay atributos de seguridad personalizados asignados a la entidad de servicio o si la entidad de seguridad de llamada no tiene acceso, la respuesta tendrá el siguiente aspecto:

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}