通过

获取 servicePrincipal

命名空间：microsoft.graph

检索 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 /applications 和 GET /servicePrincipals 列出租户中的所有应用程序和服务主体。 权限允许此访问范围。
  • 读取 customSecurityAttributes 属性：
    • 在委派方案中，必须为管理员分配 属性分配管理员 角色，并且应用授予 CustomSecAttributeAssignment.Read.All 委托权限。
    • 在使用 Microsoft Graph 权限的仅限应用方案中，必须向应用授予 CustomSecAttributeAssignment.Reade.All 应用程序权限。

HTTP 请求

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

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

可选的查询参数

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

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

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

请求标头

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

为 Accept-Language 标头提供受支持的语言代码（如 es-ES 或 de-DE），将在可用时返回本地化值。 请注意，列表操作不支持标头。

请求正文

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

响应

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

示例

示例 1：按 ID 检索服务主体

请求

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

GET https://graph.microsoft.com/v1.0/servicePrincipals/00063ffc-54e9-405d-b8f3-56124728e051

响应

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

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

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
}

示例 2：检索服务主体的特定属性

请求

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

GET https://graph.microsoft.com/v1.0/servicePrincipals/7408235b-7540-4850-82fe-a5f15ed019e2?$select=id,appId,displayName,appRoles,oauth2PermissionScopes,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"
        }
    ],
    "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"
        }
    ]
}

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

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

属性 #1

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

属性 #2

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

属性 #3

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

属性 #4

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

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

请求

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

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

响应

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

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

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

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

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