servicePrincipal を更新する

名前空間: microsoft.graph

servicePrincipal オブジェクトのプロパティを更新します。この API は、@odata.type プロパティが #microsoft.graph.agentIdentityBlueprintPrincipal に設定されている場合は agentIdentityBlueprintPrincipal オブジェクトを、@odata.type プロパティが #microsoft.graph.agentIdentity に設定されている場合は agentIdentity オブジェクトを更新することもできます。

重要

PATCH を使用して passwordCredential を設定することはサポートされていません。 servicePrincipal のパスワードまたはシークレットを更新するために addPassword および removePassword メソッドを使用します。
サービスプリンシパルは、関連付けられているアプリの登録から特定のプロパティを継承します。これらのプロパティはアプリの登録から同期されますが、同期は即時または継続的ではありません。場合によっては、サービスプリンシパルを更新すると、ディレクトリでアプリ登録のプロパティを更新するように求められ、元の要求の一部ではない更新が発生することがあります。

この API は、次の国内クラウド展開で使用できます。

グローバルサービス	米国政府機関 L4	米国政府機関 L5 (DOD)	21Vianet が運営する中国
✅	✅	✅	✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類	最小特権アクセス許可	より高い特権のアクセス許可
委任 (職場または学校のアカウント)	Application.ReadWrite.All	AgentIdentity.ReadWrite.All、Directory.ReadWrite.All
委任 (個人用 Microsoft アカウント)	サポートされていません。	サポートされていません。
アプリケーション	Application.ReadWrite.OwnedBy	AgentIdentity.ReadWrite.All、Application.ReadWrite.All、Directory.ReadWrite.All

重要

職場または学校アカウントを使用してアクセスを委任するには、サポートされている Microsoft Entra ロール、またはこの操作に必要なアクセス許可を付与するカスタムロールが管理者に割り当てられている必要があります。この操作では、必要最小限の特権のみを提供する次の組み込みロールがサポートされます。

マルチテナントアプリの場合:
- アプリケーション管理者
- クラウドアプリケーション管理者
呼び出し元ユーザーが管理者以外のユーザーであるが、バックアップアプリケーションの所有者であるシングルテナントアプリの場合、ユーザーは アプリケーション開発者 ロールを持っている必要があります。

職場または学校アカウントを使用する委任されたシナリオでは、エージェント ID とエージェント ID ブループリントプリンシパルを管理するために、次の権限がサポートされます。

サインインしたユーザーが所有者であるか、
サインインしたユーザーには、 エージェント ID 管理者 ロールが割り当てられます。

特定のシナリオのアクセス許可

customSecurityAttributes プロパティを更新するには:
- 委任されたシナリオでは、管理者に Attribute Assignment Administrator ロールを割り当て、アプリに 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	String コレクション	サブスクリプションによってサービスプリンシパルを取得し、マネージド ID のリソースグループと完全なリソース ID を識別するために使用されます。
appRoleAssignmentRequired	ブール値	Microsoft Entra ID がアプリケーションにユーザーまたはアクセストークンを発行する前に、ユーザーまたはグループに対する appRoleAssignment が必要かどうかを指定します。 null 許容ではありません。
appRoles	appRole コレクション	関連付けられているアプリケーションによって公開されるアプリケーションロール。詳細については、アプリケーションリソースの appRoles プロパティ定義を参照してください。 null 許容ではありません。
customSecurityAttributes	customSecurityAttributeValue	ディレクトリオブジェクトに割り当てられたカスタムセキュリティ属性の値を保持するオープン複合型。委任されたシナリオでこのプロパティを更新するには、呼び出し元プリンシパルに属性割り当て管理者ロールを割り当て、アプリに CustomSecAttributeAssignment.ReadWrite.All 委任されたアクセス許可を付与する必要があります。 Microsoft Graph のアクセス許可を持つアプリ限定のシナリオでこのプロパティを更新するには、アプリに CustomSecAttributeAssignment.ReadWrite.All アプリケーションのアクセス許可を付与する必要があります。
displayName	String	サービスプリンシパルの表示名。
HomePage	String	アプリケーションのホームページまたはランディングページ。
keyCredentials	keyCredential コレクション	サービスプリンシパルに関連付けられているキー資格情報のコレクションです。null 許容型ではありません。 null 許容ではありません。
logoutUrl	String	フロントチャネル、バックチャネル、または SAML ログアウトプロトコルを使用してユーザーをログアウトするために、Microsoft の承認サービスで使用される URL を指定します。
oauth2PermissionScopes	permissionScope コレクション	関連付けられているアプリケーションによって公開される OAuth 2.0 のアクセス許可。詳しくは、アプリケーション・リソースのoauth2PermissionScopesプロパティ定義を参照してください。 null 許容ではありません。
preferredSingleSignOnMode	string	このアプリケーションに構成されているシングルサインオンモードを指定します。 Microsoft Entra ID では、優先シングルサインオンモードを使用して、Microsoft 365 またはマイアプリポータルからアプリケーションを起動します。サポートされている値は `password`、`saml`、`external`、および `oidc` です。
replyUrls	String コレクション	関連付けられたアプリケーションにサインインするためにユーザートークンが送信される URL、または関連付けられたアプリケーションに対して OAuth 2.0 認証コードとアクセストークンが送信されるリダイレクト URI。 null 許容ではありません。
servicePrincipalNames	String コレクション	関連するアプリケーションからコピーされた identifiersUris のリストが含まれています。ハイブリッドアプリケーションに追加の値を追加できます。これらの値を使用して、Microsoft Entra ID 内でこのアプリによって公開されるアクセス許可を識別できます。例えば、このリソースへのアクセス許可を要求するクライアントアプリでは、これらの URI を使用して、アプリケーションマニフェストの requiredResourceAccess プロパティや、アプリ登録エクスペリエンスの "API アクセス許可" ブレードで、必要とするアクセス許可を特定することができます。クライアントアプリは、このプロパティの値に基づくリソース URI を指定して、アクセストークンを取得できます。これは、"aud" クレームで返される URI です。多値プロパティのフィルター式には、any 演算子が必要です。 null 許容ではありません。
tags	String コレクション	アプリケーションを分類および識別するために使用できるカスタム文字列です。 null 許容ではありません。
tokenEncryptionKeyId	文字列	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
}


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

// Dependencies
using Microsoft.Graph.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);



// Code snippets are only available for the latest major version. Current major version is $v1.*

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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)


// 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);


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

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


<?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();


Import-Module Microsoft.Graph.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
	app_role_assignment_required = True,
)

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

応答

次の例は応答を示しています。

HTTP/1.1 204 No Content

例 2: 文字列値を持つカスタムセキュリティ属性をサービスプリンシパルに割り当てる

次の例は、文字列値を持つカスタムセキュリティ属性をサービスプリンシパルに割り当てる方法を示しています。

属性セット: Engineering
属性: ProjectDate
属性データ型: 文字列
属性値: "2022-10-01"

カスタムセキュリティ属性を割り当てるには、呼び出し元のプリンシパルに属性割り当て管理者の役割を割り当て、CustomSecAttributeAssignment.ReadWrite.All 権限を付与する必要があります。

ユーザー向けのその他の同様の例については、「例: Microsoft Graph 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"
        }
    }
}


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

// Dependencies
using Microsoft.Graph.Models;
using Microsoft.Kiota.Abstractions.Serialization;

var requestBody = new ServicePrincipal
{
	CustomSecurityAttributes = new CustomSecurityAttributeValue
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"Engineering" , new UntypedObject(new Dictionary<string, UntypedNode>
				{
					{
						"@odata.type", new UntypedString("#Microsoft.DirectoryServices.CustomSecurityAttributeValue")
					},
					{
						"projectDate", new UntypedString("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);



// Code snippets are only available for the latest major version. Current major version is $v1.*

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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)


// 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);


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}')
	.update(servicePrincipal);


<?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();


Import-Module Microsoft.Graph.Applications

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

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
from msgraph.generated.models.custom_security_attribute_value import CustomSecurityAttributeValue
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
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)

応答

次の例は応答を示しています。

HTTP/1.1 204 No Content

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-17