通过

更新 servicePrincipal

命名空间：microsoft.graph

更新 servicePrincipal 对象的属性。

重要

  • 不支持使用 PATCH 设置 passwordCredential。 使用 addPassword 和 removePassword 方法更新 servicePrincipal 的密码或密钥。

  • 服务主体从其关联的应用注册继承特定属性。 这些属性从应用注册同步，但同步不是立即或连续的。 有时，更新服务主体可能会提示目录从应用注册刷新属性，从而导致不属于原始请求的更新。

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

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

权限

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

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

注意

  • 更新 customSecurityAttributes 属性：
    • 在委派方案中，必须为管理员分配 属性分配管理员 角色，并且应用授予 CustomSecAttributeAssignment.ReadWrite.All 委托权限。
    • 在使用 Microsoft Graph 权限的仅限应用方案中，必须向应用授予 CustomSecAttributeAssignment.ReadWrite.All 应用程序权限。

HTTP 请求

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

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

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。
Content-Type application/json. 必需。

请求正文

在请求正文中，提供应更新的相关字段的值。 请求正文中未包含的现有属性会保留其以前的值，或者根据对其他属性值的更改重新计算。 为了实现最佳性能，不得添加未变化的现有值。

属性 类型 说明
accountEnabled Boolean 如果服务主体帐户已启用，则为 true；否则，为 false。
addIns addIn 定义使用服务可用于调用特定上下文中的应用的自定义行为。 例如，呈现文件流的应用程序可能会为其“FileHandler”功能设置 addIns 属性。 这样，Microsoft 365 等服务就可以在用户正在处理的文档上下文中调用应用程序。
alternativeNames 字符串集合 用于按订阅检索服务主体，标识 托管标识的资源组和完整资源 ID。
appRoleAssignmentRequired Boolean 指定在Microsoft Entra ID向应用程序颁发用户或访问令牌之前是否需要用户或组的 appRoleAssignment。 不可为 null。
appRoles appRole 集合 关联应用程序公开的应用程序角色。 有关详细信息，请参阅应用程序资源上的 appRoles 属性定义。 不可为空。
customSecurityAttributes customSecurityAttributeValue 保留分配给目录对象的自定义安全属性的值的开放式复杂类型。
  • 若要在委托方案中更新此属性，必须为调用主体分配“属性分配管理员”角色，并且应用被授予 CustomSecAttributeAssignment.ReadWrite.All 委托权限。
  • 若要在仅限应用的情况下使用 Microsoft Graph 权限更新此属性，必须向应用授予 CustomSecAttributeAssignment.ReadWrite.All 应用程序权限。
    		•
    displayName String 服务主体的显示名称。
    homepage String 应用程序的主页或登录页面。
    keyCredentials keyCredential 集合 与服务帐户关联的密钥凭据集合。 不可为空。
    logoutUrl String 指定Microsoft授权服务将使用的 URL，以便使用前端、后端通道或 SAML 注销协议注销用户。
    oauth2PermissionScopes permissionScope 集合 关联应用程序公开的 OAuth 2.0 权限范围。 有关详细信息，请参阅应用程序资源上的 oauth2PermissionScopes 属性定义。 不可为 null。
    preferredSingleSignOnMode string 指定为此应用程序配置的单一登录模式。 Microsoft Entra ID使用首选的单一登录模式从 Microsoft 365 或 我的应用 门户启动应用程序。 支持的值是：password、saml、external 和 oidc。
    replyUrls String 集合 向其发送用户令牌以使用关联应用程序登录的 URL，或者为关联应用程序向其发送 OAuth 2.0 authorization 代码和访问令牌的重定向 URL。 不可为空。
    servicePrincipalNames 字符串集合 包含从关联的应用程序中复制的 identifiersUris 列表。 可以将其他值添加到混合应用程序。 这些值可用于标识此应用在Microsoft Entra ID中公开的权限。 例如，
    • 请求对此资源的权限的客户端应用可以使用这些 URI 在其应用程序清单的 requiredResourceAccess 属性中或在应用注册体验的“API 权限”边栏选项卡中指定所需的权限。
    • 客户端应用可以指定一个资源 URI，该 URI 基于此属性的值来获取访问令牌，即在“aud”声明中返回的 URI。

    需要多值属性筛选器表达式的 any 运算符。 不可为空。
    标记 String 集合 可用于分类和标识应用程序的自定义字符串。 不可为空。
    tokenEncryptionKeyId String 指定 keyCredentials 集合中的公共密钥的 keyId。 配置后，Microsoft Entra ID为此应用程序颁发使用此属性指定的密钥加密的令牌。 接收加密令牌的应用程序代码必须先使用匹配的私钥来解密该令牌，然后才能将该令牌用于登录用户。

    响应

    如果成功，此方法将在响应正文中返回 204 No Content 响应代码和更新的 servicePrincipal 对象。

    示例

    示例 1：更新指定服务主体的属性

    请求

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

    PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
  "appRoleAssignmentRequired": true
}

    响应

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

    HTTP/1.1 204 No Content

    示例 2：将具有字符串值的自定义安全属性分配给服务主体

    下面的示例演示如何将具有字符串值的自定义安全属性分配给服务主体。

    • 属性集： Engineering
    • 属性：ProjectDate
    • 属性数据类型：字符串
    • 属性值： "2022-10-01"

    若要分配自定义安全属性，必须为调用主体分配"属性分配管理员"角色，并且必须授予CustomSecAttributeAssignment.ReadWrite.All 权限。

    有关用户的其他类似示例，请参阅示例：使用Microsoft图形 API分配、更新、列出或删除自定义安全属性分配。

    请求

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

    PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

    响应

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

    HTTP/1.1 204 No Content