更新 servicePrincipal

项目
03/15/2024

命名空间：microsoft.graph

重要

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

更新 servicePrincipal 对象的属性。

重要

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

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

权限

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

权限类型	最低特权权限	更高特权权限
委派（工作或学校帐户）	Application.ReadWrite.All	Directory.ReadWrite.All
委派（个人 Microsoft 帐户）	不支持。	不支持。
应用程序	Application.ReadWrite.OwnedBy	Application.ReadWrite.All、Directory.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 权限。
displayName	String	服务主体的显示名称。
homepage	String	应用程序的主页或登录页面。
keyCredentials	keyCredential 集合	与服务帐户关联的密钥凭据集合。不可为 null。
loginUrl	String	指定服务提供商将用户重定向到Microsoft Entra ID进行身份验证的 URL。 Microsoft Entra ID使用 URL 从 Microsoft 365 或Microsoft Entra 我的应用启动应用程序。如果为空，Microsoft Entra ID对配置了基于 SAML 的单一登录的应用程序执行 IdP 发起的登录。用户从 Microsoft 365、Microsoft Entra 我的应用或Microsoft Entra SSO URL 启动应用程序。
logoutUrl	String	指定 Microsoft 授权服务将用于使用前端、后端通道或 SAML 注销协议注销用户的 URL。
notificationEmailAddresses	字符串集合	指定在活动证书接近到期日期时，Microsoft Entra ID发送通知的电子邮件地址列表。这仅适用于用于对 Microsoft Entra 库应用程序颁发的 SAML 令牌进行签名的证书。
publishedPermissionScopes	permissionScope 集合	关联应用程序的 OAuth 2.0 权限。有关详细信息，请参阅应用程序资源上的 oauth2PermissionScopes 属性定义。不可为 null。
preferredSingleSignOnMode	string	指定为此应用程序配置的单一登录模式。 Microsoft Entra ID使用首选的单一登录模式从 Microsoft 365 或 Microsoft Entra 我的应用启动应用程序。支持的值有 password、saml、external 和 oidc。
preferredTokenSigningKeyEndDateTime	DateTimeOffset	指定用于令牌签名的 keyCredential 的到期日期，由 preferredTokenSigningKeyThumbprint 标记。
preferredTokenSigningKeyThumbprint	String	仅供内部使用。请勿写入或以其他方式依赖此属性。可能会在未来版本中删除。
publisherName	String	在其中指定关联应用程序的租户的显示名称。
replyUrls	String 集合	向其发送用户令牌以使用关联应用程序登录的 URL，或者为关联应用程序向其发送 OAuth 2.0 authorization 代码和访问令牌的重定向 URL。不可为 null。
samlSingleSignOnSettings	samlSingleSignOnSettings	有关 saml 单一登录的设置的集合。
servicePrincipalNames	字符串集合	包含从关联的应用程序中复制的 identifiersUris 列表。可以将其他值添加到混合应用程序。这些值可用于标识此应用在Microsoft Entra ID中公开的权限。例如，请求对此资源的权限的客户端应用可以使用这些 URI 在其应用程序清单的 requiredResourceAccess 属性中或在应用注册体验的“API 权限”边栏选项卡中指定所需的权限。客户端应用可以指定一个资源 URI，该 URI 基于此属性的值来获取访问令牌，即在“aud”声明中返回的 URI。需要多值属性筛选器表达式的 any 运算符。不可为空。
标记	String collection	不可为空。
tokenEncryptionKeyId	String	指定 keyCredentials 集合中的公共密钥的 keyId。配置后，Microsoft Entra ID为此应用程序颁发使用此属性指定的密钥加密的令牌。接收加密令牌的应用程序代码必须先使用匹配的私钥来解密该令牌，然后才能将该令牌用于登录用户。

响应

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

示例

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

请求

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

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

{
  "appRoleAssignmentRequired": true
}


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new ServicePrincipal
{
	AppRoleAssignmentRequired = true,
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);

重要

Microsoft Graph SDK 默认使用 v1.0 版本的 API，并且不支持 beta 版本中提供的所有类型、属性和 API。有关使用 SDK 访问 beta API 的详细信息，请参阅将 Microsoft Graph SDK 与 beta API 配合使用。

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
  "appRoleAssignmentRequired": true\
}\
'

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewServicePrincipal()
appRoleAssignmentRequired := true
requestBody.SetAppRoleAssignmentRequired(&appRoleAssignmentRequired) 

servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppRoleAssignmentRequired(true);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

await client.api('/servicePrincipals/{id}')
	.version('beta')
	.update(servicePrincipal);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ServicePrincipal();
$requestBody->setAppRoleAssignmentRequired(true);

$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


Import-Module Microsoft.Graph.Beta.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal

graph_client = GraphServiceClient(credentials, scopes)

request_body = ServicePrincipal(
	app_role_assignment_required = True,
)

result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

响应

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

HTTP/1.1 204 No Content

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

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

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

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

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

请求

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

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


// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new ServicePrincipal
{
	CustomSecurityAttributes = new CustomSecurityAttributeValue
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"Engineering" , new 
				{
					OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
					ProjectDate = "2022-10-01",
				}
			},
		},
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
    "customSecurityAttributes":\
    {\
        "Engineering":\
        {\
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",\
            "ProjectDate":"2022-10-01"\
        }\
    }\
}\
'

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewServicePrincipal()
customSecurityAttributes := graphmodels.NewCustomSecurityAttributeValue()
additionalData := map[string]interface{}{
engineering := graphmodels.New()
projectDate := "2022-10-01"
engineering.SetProjectDate(&projectDate) 
	customSecurityAttributes.SetEngineering(engineering)
}
customSecurityAttributes.SetAdditionalData(additionalData)
requestBody.SetCustomSecurityAttributes(customSecurityAttributes)

servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
CustomSecurityAttributeValue customSecurityAttributes = new CustomSecurityAttributeValue();
HashMap<String, Object> additionalData = new HashMap<String, Object>();
 engineering = new ();
engineering.setOdataType("#Microsoft.DirectoryServices.CustomSecurityAttributeValue");
engineering.setProjectDate("2022-10-01");
additionalData.put("Engineering", engineering);
customSecurityAttributes.setAdditionalData(additionalData);
servicePrincipal.setCustomSecurityAttributes(customSecurityAttributes);
ServicePrincipal result = graphClient.servicePrincipals().byServicePrincipalId("{servicePrincipal-id}").patch(servicePrincipal);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
    customSecurityAttributes: 
    {
        Engineering: 
        {
            '@odata.type':'#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
            ProjectDate: '2022-10-01'
        }
    }
};

await client.api('/servicePrincipals/{id}')
	.version('beta')
	.update(servicePrincipal);

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;
use Microsoft\Graph\Generated\Models\CustomSecurityAttributeValue;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new ServicePrincipal();
$customSecurityAttributes = new CustomSecurityAttributeValue();
$additionalData = [
	'Engineering' => [
		'@odata.type' => '#Microsoft.DirectoryServices.CustomSecurityAttributeValue',
		'projectDate' => '2022-10-01',
	],
];
$customSecurityAttributes->setAdditionalData($additionalData);
$requestBody->setCustomSecurityAttributes($customSecurityAttributes);

$result = $graphServiceClient->servicePrincipals()->byServicePrincipalId('servicePrincipal-id')->patch($requestBody)->wait();

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


Import-Module Microsoft.Graph.Beta.Applications

$params = @{
	customSecurityAttributes = @{
		Engineering = @{
			"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
			ProjectDate = "2022-10-01"
		}
	}
}

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。


from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
from msgraph.generated.models.custom_security_attribute_value import CustomSecurityAttributeValue

graph_client = GraphServiceClient(credentials, scopes)

request_body = ServicePrincipal(
	custom_security_attributes = CustomSecurityAttributeValue(
		additional_data = {
				"engineering" : {
						"@odata_type" : "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
						"project_date" : "2022-10-01",
				},
		}
	),
)

result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)

重要

有关如何将 SDK 添加到项目并创建 authProvider 实例的详细信息，请参阅 SDK 文档。

响应

HTTP/1.1 204 No Content

更新 servicePrincipal

权限

HTTP 请求

请求标头

请求正文

响应

示例

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

请求

响应

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

请求

响应

反馈

反馈

其他资源