获取 servicePrincipal

命名空间:microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用,请使用 版本 选择器。

检索 servicePrincipal对象的属性和关系。

此 API 可用于以下国家级云部署

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时,才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息,请参阅权限类型。 要了解有关这些权限的详细信息,请参阅 权限参考

权限类型 最低特权权限 更高特权权限
委派(工作或学校帐户) Application.Read.All Application.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
委派(个人 Microsoft 帐户) 不支持。 不支持。
应用程序 Application.Read.All Application.ReadWrite.OwnedBy、Application.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All

注意

  • 服务主体可以检索自己的应用程序和服务主体详细信息,而无需授予任何应用程序权限。
  • Application.ReadWrite.OwnedBy 权限允许应用调用 GET /applicationsGET /servicePrincipals 列出租户中的所有应用程序和服务主体。 权限允许此访问范围。
  • 读取 customSecurityAttributes 属性:
    • 在委派方案中,必须为管理员分配 属性分配管理员 角色,并且应用授予 CustomSecAttributeAssignment.Read.All 委托权限。
    • 在使用 Microsoft Graph 权限的仅限应用方案中,必须向应用授予 CustomSecAttributeAssignment.Reade.All 应用程序权限。

HTTP 请求

可以使用服务主体 IDappId 来寻址服务主体。 idappId 在 Microsoft Entra 管理中心 中的应用注册中分别称为“对象 ID”和“应用程序 (客户端) ID”。

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

可选的查询参数

此方法支持使用 $select$expandOData 查询参数,以帮助自定义响应。

此方法支持 $count、、$expand$filter$orderby$search$select$topOData 查询参数来帮助自定义响应。 只有将 ConsistencyLevel 标头设置为 eventual$count 时,才支持某些查询。 有关详细信息,请参阅 目录对象的高级查询功能

默认情况下,此 API 不会返回 keyCredentials 属性中 密钥 的公钥值,除非已在 $select 查询中指定了 keyCredentials。 例如,$select=id,appId,keyCredentials

对于每个租户,使用 $select 获取服务主体的 keyCredentials 限制为每分钟 150 个请求。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权
Accept-Language 语言代码。 可选。

Accept-Language 标头提供受支持的语言代码(如 es-ESde-DE),将在可用时返回本地化值。 请注意,列表操作不支持标头。

请求正文

请勿提供此方法的请求正文。

响应

如果成功,此方法在响应正文中返回 200 OK 响应代码和 servicePrincipal 对象。

示例

示例 1:获取指定服务主体的属性

请求

以下示例显示了一个请求。

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

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

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

示例 2:按 appId 和仅特定属性检索服务主体

请求

以下示例显示了一个请求。

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

响应

以下示例显示了相应的响应。

注意:为了提高可读性,可能缩短了此处显示的响应对象。

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

示例 3:获取指定服务主体的自定义安全属性分配

以下示例获取指定服务主体的自定义安全属性。

属性 #1

  • 属性集:Engineering
  • 属性:Project
  • 属性数据类型:字符串集合
  • 属性值:["Baker","Cascade"]

属性 #2

  • 属性集:Engineering
  • 属性:CostCenter
  • 属性数据类型:整数集合
  • 属性值:[1001]

属性 #3

  • 属性集:Engineering
  • 属性:Certification
  • 属性数据类型:布尔
  • 属性值:true

属性 #4

  • 属性集:Marketing
  • 属性:Level
  • 属性数据类型:字符串
  • 属性值:"Public"

若要获取自定义安全属性分配,必须为调用主体分配“属性分配读取者”或“属性分配管理员”角色,并且必须被授予 CustomSecAttributeAssignment.Read.AllCustomSecAttributeAssignment.ReadWrite.All 权限。

请求

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

响应

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

如果没有为服务主体分配自定义安全属性,或者调用主体没有访问权限,响应将如下所示:

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

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