名前空間: microsoft.graph
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
servicePrincipal オブジェクトのプロパティを更新します。 この API は、@odata.type プロパティが #microsoft.graph.agentIdentityBlueprintPrincipal に設定されている場合に agentIdentityBlueprintPrincipal オブジェクトを更新することもできます。
重要
PATCH を使用して passwordCredential を設定することはサポートされていません。 servicePrincipal のパスワードまたはシークレットを更新するために addPassword および removePassword メソッドを使用します。
サービス プリンシパルは、関連付けられているアプリの登録から特定のプロパティを継承します。 これらのプロパティはアプリ登録から同期されますが、同期は即時または継続的ではありません。 場合によっては、サービス プリンシパルを更新すると、ディレクトリにアプリの登録からプロパティを更新するように求め、元の要求に含まれなかった更新が発生することがあります。
この API は、次の国内クラウド展開で使用できます。
| グローバル サービス |
米国政府機関 L4 |
米国政府機関 L5 (DOD) |
21Vianet が運営する中国 |
| ✅ |
✅ |
✅ |
✅ |
アクセス許可
この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。
アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。
| アクセス許可の種類 |
最小特権アクセス許可 |
より高い特権のアクセス許可 |
| 委任 (職場または学校のアカウント) |
Application.ReadWrite.All |
AgentIdentity.EnableDisable.All、AgentIdentity.ReadWrite.All、AgentIdentityBlueprintPrincipal.EnableDisable.All、Directory.ReadWrite.All |
| 委任 (個人用 Microsoft アカウント) |
サポートされていません。 |
サポートされていません。 |
| アプリケーション |
Application.ReadWrite.OwnedBy |
AgentIdentity.EnableDisable.All、AgentIdentity.ReadWrite.All、AgentIdentityBlueprintPrincipal.EnableDisable.All、Application.ReadWrite.All、Directory.ReadWrite.All |
重要
職場または学校アカウントを使用する委任されたシナリオでは、管理者にサポートされているMicrosoft Entraロールまたはサポートされているロールのアクセス許可を持つカスタム ロールを割り当てる必要があります。 この操作では、次の最小特権ロールがサポートされています。
- マルチテナント アプリの場合:
- アプリケーション管理者
- クラウド アプリケーション管理者
- 呼び出し元のユーザーが管理者以外のユーザーであり、バッキング アプリケーションの所有者であるシングルテナント アプリの場合、ユーザーは アプリケーション開発者 ロールを持っている必要があります。
特定のシナリオのアクセス許可
-
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 |
String コレクション |
サブスクリプションによってサービスプリンシパルを取得し、管理された ID のリソースグループと完全なリソース ID を識別するために使用されます。 |
| appRoleAssignmentRequired |
ブール値 |
ユーザーまたはグループに対して appRoleAssignment が必要かどうかを指定Microsoft Entra ID、アプリケーションにユーザーまたはアクセス トークンを発行します。 null 許容ではありません。 |
| appRoles |
appRole コレクション |
関連付けられているアプリケーションによって公開されるアプリケーション ロール。 詳細については、アプリケーション リソースの appRoles プロパティ定義に関するページを参照してください。 null 許容ではありません。 |
| customSecurityAttributes |
customSecurityAttributeValue |
ディレクトリ オブジェクトに割り当てられたカスタム セキュリティ属性の値を保持するオープン複合型。 委任されたシナリオでこのプロパティを更新するには、呼び出し元プリンシパルに属性割り当て管理者ロールが割り当てられ、アプリに CustomSecAttributeAssignment.ReadWrite.All 委任されたアクセス許可が付与されている必要があります。Microsoft Graph のアクセス許可を持つアプリのみのシナリオでこのプロパティを更新するには、アプリに CustomSecAttributeAssignment.ReadWrite.All アプリケーションアクセス許可が付与されている必要があります。 |
| displayName |
String |
サービス プリンシパルの表示名。 |
| HomePage |
String |
アプリケーションのホームページまたはランディングページ。 |
| isDisabled |
ブール型 |
テナント内またはマルチテナント アプリのテナント間のアプリのサービス プリンシパルが、新しいアクセス トークンを取得できるか、保護されたリソースにアクセスできるかを指定します。
trueに設定すると、既存のトークンは、構成された有効期間に基づいて有効期限が切れるまで有効なままであり、アプリは Enterprise アプリの一覧に表示されたままですが、アプリケーションが非アクティブ化 (無効) の場合、ユーザーは trueサインインできません(無効)、それ以外の場合はfalse。 |
| keyCredentials |
keyCredential コレクション |
サービス プリンシパルに関連付けられているキー資格情報のコレクションです。null 許容型ではありません。 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 |
フロント チャネル、バック チャネル、または SAML ログアウト プロトコルを使用してユーザーをログアウトするために Microsoft の承認サービスによって使用される URL を指定します。 |
| notificationEmailAddresses |
String コレクション |
アクティブな証明書が有効期限の近くにあるときにMicrosoft Entra IDが通知を送信する電子メール アドレスの一覧を指定します。 これは、ギャラリー アプリケーションに対して発行された SAML トークンの署名に使用Microsoft Entra証明書に対してのみ行われます。 |
| publishedPermissionScopes |
permissionScope コレクション |
関連するアプリケーションによって公開されている OAuth 2.0 のアクセス許可。 詳細については、アプリケーション リソースの oauth2PermissionScopes プロパティ定義を参照してください。 null 許容ではありません。 |
| preferredSingleSignOnMode |
string |
このアプリケーションに構成されているシングルサインオンモードを指定します。 Microsoft Entra IDは、優先シングル サインオン モードを使用して、Microsoft 365 またはMicrosoft Entra マイ アプリからアプリケーションを起動します。 サポートされている値は、password、saml、external、および oidc です。 |
| preferredTokenSigningKeyEndDateTime |
DateTimeOffset |
preferredTokenSigningKeyThumbprintによってマークされたトークンの署名に使用される keyCredential の有効期限を指定します。 |
| preferredTokenSigningKeyThumbprint |
String |
内部使用専用に予約済みです。 書き込みしないか、このプロパティに依存しないでください。 将来のバージョンで削除される可能性があります。 |
| publisherName |
String |
関連付けられたアプリケーションが指定されているテナントの表示名。 |
| replyUrls |
String コレクション |
関連付けられたアプリケーションにサインインするためにユーザー トークンが送信される URL、または関連付けられたアプリケーションに対して OAuth 2.0 認証コードとアクセス トークンが送信されるリダイレクト URI。 null 許容ではありません。 |
| samlSingleSignOnSettings |
samlSingleSignOnSettings |
saml シングルサインオンに関連する設定のコレクション。 |
| servicePrincipalNames |
String コレクション |
関連するアプリケーションからコピーされた identifiersUris のリストが含まれています。 ハイブリッドアプリケーションに追加の値を追加できます。 これらの値は、Microsoft Entra ID内でこのアプリによって公開されるアクセス許可を識別するために使用できます。 例えば、- このリソースへのアクセス許可を要求するクライアント アプリでは、これらの URI を使用して、アプリケーション マニフェストの requiredResourceAccess プロパティや、アプリ登録エクスペリエンスの "API アクセス許可" ブレードで、必要とするアクセス許可を特定することができます。
- クライアント アプリでは、このプロパティの値に基づいてリソース URI を指定して、アクセス トークンを取得できます。これは"aud" 要求で返される URI です。
多値プロパティのフィルター式には、any 演算子が必要です。 null 許容ではありません。 |
| tags |
String collection |
null 許容ではありません。 |
| tokenEncryptionKeyId |
文字列 |
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);
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-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}')
.version('beta')
.update(servicePrincipal);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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.Beta.Applications
$params = @{
appRoleAssignmentRequired = $true
}
Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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/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;
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 $v0.*
// Dependencies
import (
"context"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-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}')
.version('beta')
.update(servicePrincipal);
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\ServicePrincipal;
use Microsoft\Graph\Beta\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.Beta.Applications
$params = @{
customSecurityAttributes = @{
Engineering = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
ProjectDate = "2022-10-01"
}
}
}
Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params
# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.service_principal import ServicePrincipal
from msgraph_beta.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