Update servicePrincipal

Namespace: microsoft.graph

Aktualisieren Sie die Eigenschaften des servicePrincipal-Objekts. Diese API kann auch ein agentIdentityBlueprintPrincipal-Objekt aktualisieren, wenn die @odata.type-Eigenschaft auf #microsoft.graph.agentIdentityBlueprintPrincipalfestgelegt ist, oder ein agentIdentity-Objekt , wenn die @odata.type-Eigenschaft auf #microsoft.graph.agentIdentityfestgelegt ist.

Wichtig

• Die Verwendung von PATCH zum Festlegen vob passwordCredential wird nicht unterstützt. Verwenden Sie die addPassword- und removePassword-Methoden zum Aktualisieren des Kennworts für einen servicePrincipal.

• Dienstprinzipale erben bestimmte Eigenschaften von den zugehörigen App-Registrierungen. Diese Eigenschaften werden von der App-Registrierung synchronisiert, aber die Synchronisierung erfolgt nicht sofort oder kontinuierlich. Manchmal fordert die Aktualisierung eines Dienstprinzipals das Verzeichnis möglicherweise auf, Eigenschaften aus der App-Registrierung zu aktualisieren, was zu Aktualisierungen führt, die nicht Teil der ursprünglichen Anforderung waren.

Diese API ist in den folgenden nationalen Cloudbereitstellungen verfügbar.

Weltweiter Service	US Government L4	US Government L5 (DOD)	China, betrieben von 21Vianet
✅	✅	✅	✅

Berechtigungen

Wählen Sie die Berechtigungen aus, die für diese API als am wenigsten privilegiert markiert sind. Verwenden Sie eine höhere Berechtigung oder Berechtigungen nur, wenn Ihre App dies erfordert. Ausführliche Informationen zu delegierten Berechtigungen und Anwendungsberechtigungen finden Sie unter Berechtigungstypen. Weitere Informationen zu diesen Berechtigungen finden Sie in der Berechtigungsreferenz.

Berechtigungstyp	Berechtigungen mit den geringsten Berechtigungen	Berechtigungen mit höheren Berechtigungen
Delegiert (Geschäfts-, Schul- oder Unikonto)	Application.ReadWrite.All	AgentIdentity.ReadWrite.All, Directory.ReadWrite.All
Delegiert (persönliches Microsoft-Konto)	Nicht unterstützt	Nicht unterstützt
Application	Application.ReadWrite.OwnedBy	AgentIdentity.ReadWrite.All, Application.ReadWrite.All, Directory.ReadWrite.All

Wichtig

Für den delegierten Zugriff mit Geschäfts-, Schul- oder Unikonten muss dem Administrator eine unterstützte Microsoft Entra-Rolle oder eine benutzerdefinierte Rolle zugewiesen werden, die die für diesen Vorgang erforderlichen Berechtigungen erteilt. Dieser Vorgang unterstützt die folgenden integrierten Rollen, die nur die geringstmöglichen Berechtigungen gewähren:

• Für mehrinstanzenfähige Apps:
  • Anwendungsadministrator
  • Cloudanwendungsadministrator
• Bei Einzelmandanten-Apps, bei denen der aufrufende Benutzer kein Administrator ist, aber der Besitzer der zugrunde liegenden Anwendung ist, muss der Benutzer die Rolle Anwendungsentwickler haben.

In delegierten Szenarien mit Geschäfts-, Schul- oder Unikonten werden die folgenden Berechtigungen zum Verwalten von Agentidentitäten und Agentidentitäts-Blaupausenprinzipalen unterstützt:

• Der angemeldete Benutzer ist der Besitzer oder
• Dem angemeldeten Benutzer wird die Rolle " Agent-ID-Administrator" zugewiesen.

Berechtigungen für bestimmte Szenarien

• So aktualisieren Sie die customSecurityAttributes-Eigenschaft :
  • In delegierten Szenarien muss dem Administrator die Rolle des Attributzuweisungsadministrators zugewiesen und der App die delegierte Berechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.
  • In Nur-App-Szenarien mit Microsoft Graph-Berechtigungen muss der App die Anwendungsberechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.

HTTP-Anforderung

Sie können den Dienstprinzipal entweder über seine ID oder appId ansprechen. ID und appId werden bei App-Registrierungen im Microsoft Entra Admin Center als Objekt-ID bzw. Anwendungs-ID (Client-ID) bezeichnet.

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

Anforderungsheader

Name	Beschreibung
Authorization	Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung.
Content-Type	application/json. Erforderlich.

Anforderungstext

Geben Sie im Anforderungstext die Werte für die relevanten Felder an, die aktualisiert werden sollen. Vorhandene Eigenschaften, die nicht im Anforderungstext enthalten sind, behalten ihre vorherigen Werte bei oder werden basierend auf Änderungen an anderen Eigenschaftswerten neu berechnet. Aus Gründen der Leistung sollten Sie vorhandene Werte, die nicht geändert wurden, nicht angeben.

Eigenschaft	Typ	Beschreibung
accountEnabled	Boolescher Wert	True, wenn das Dienstprinzipalkonto aktiviert ist; andernfalls false.
addIns	addIn	Definiert benutzerdefiniertes Verhalten, das von einem Verbraucherdienst verwendet werden kann, um eine App in bestimmten Kontexten aufzurufen. Beispielsweise können Anwendungen, die Datei-Streams rendern können, die addIns-Eigenschaft für deren "FileHandler"-Funktionalität festlegen. Dadurch können Dienste wie Microsoft 365 die Anwendung im Kontext eines Dokuments aufrufen, an dem der Benutzer arbeitet.
alternativeNames	Zeichenfolgenauflistung	Wird verwendet zum Abrufen von Dienstprinzipalen nach Abonnement, zur Identifizierung von Ressourcengruppen und vollständigen Ressourcen-IDs für verwaltete Identitäten.
appRoleAssignmentRequired	Boolesch	Gibt an, ob eine appRoleAssignment an einen Benutzer oder eine Gruppe erforderlich ist, bevor Microsoft Entra ID ein Benutzer- oder Zugriffstoken für die Anwendung ausstellt. Lässt keine Nullwerte zu.
appRoles	appRole-Auflistung	Die von der verknüpften Anwendung verfügbar gemachten Anwendungsrollen. Weitere Informationen finden Sie in der AppRoles-Eigenschaftsdefinition für die Anwendungsressource . Lässt keine NULL-Werte zu.
customSecurityAttributes	customSecurityAttributeValue	Ein offener komplexer Typ, der den Wert eines benutzerdefinierten Sicherheitsattributs enthält, das einem Verzeichnisobjekt zugewiesen ist. Um diese Eigenschaft in delegierten Szenarien zu aktualisieren, muss dem aufrufenden Prinzipal die Rolle des Attributzuweisungsadministrators zugewiesen und der App die delegierte Berechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden. Um diese Eigenschaft in Nur-App-Szenarien mit Microsoft Graph-Berechtigungen zu aktualisieren, muss der App die Anwendungsberechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.
displayName	Zeichenfolge	Der Anzeigename für den Dienstprinzipal.
homepage	Zeichenfolge	Startseite der Anwendung.
keyCredentials	keyCredential-Auflistung	Die Auflistung der wichtigsten Anmeldeinformationen, die mit dem Dienstprinzipal verknüpft sind. Lässt keine Nullwerte zu.
logoutUrl	Zeichenfolge	Gibt die URL an, die vom Autorisierungsdienst von Microsoft verwendet wird, um einen Benutzer mit Front-Channel-, Rückkanal - oder SAML-Abmeldeprotokollen abzumelden.
oauth2PermissionScopes	permissionScope-Sammlung	Die von der verknüpften Anwendung verfügbar gemachten OAuth 2.0-Berechtigungsbereiche. Weitere Informationen finden Sie in der oauth2PermissionScopes-Eigenschaftsdefinition für die Anwendungsressource . Lässt keine NULL-Werte zu.
preferredSingleSignOnMode	Zeichenfolge	Gibt den Modus für einmaliges Anmelden an, der für diese Anwendung konfiguriert ist. Microsoft Entra ID verwendet den bevorzugten Single Sign-On-Modus, um die Anwendung über Microsoft 365 oder das Portal "Meine Apps" zu starten. Unterstützte Werte sind: password, saml, external und oidc.
replyUrls	Zeichenfolgenauflistung	Die URLs, an die Benutzertoken zur Anmeldung bei der verknüpften Anwendung gesendet werden, oder die Umleitungs-URIs, an die die OAuth 2.0-Autorisierungscodes und Zugriffstoken für die verknüpfte Anwendung gesendet werden. Lässt keine NULL-Werte zu.
servicePrincipalNames	Zeichenfolgenauflistung	Enthält die Liste der identifiersUris-, die aus der zugehörigen Anwendung kopiert werden. Hybridanwendungen können zusätzliche Werte hinzugefügt werden. Diese Werte können verwendet werden, um die Berechtigungen zu identifizieren, die von dieser App innerhalb von Microsoft Entra ID verfügbar gemacht werden. Beispiel: Client-Apps, die Berechtigungen für diese Ressource anfordern, können diese URIs verwenden, um die erforderlichen Berechtigungen in der requiredResourceAccess-Eigenschaft des Anwendungsmanifests oder im Blatt „API-Berechtigungen“ in der App-Registrierungsoberfläche anzugeben. Client-Apps können einen Ressourcen-URI angeben, der auf den Werten dieser Eigenschaft basiert, um ein Zugriffstoken abzurufen, bei dem es sich um den URI handelt, der im "aud"-Anspruch zurückgegeben wird. Der "any"-Operator ist für Filterausdrücke für mehrwertige Eigenschaften erforderlich. Lässt keine NULL-Werte zu.
tags	String-Sammlung	Benutzerdefinierte Zeichenfolgen, die zum Kategorisieren und Identifizieren der Anwendung verwendet werden können. Lässt keine Nullwerte zu.
tokenEncryptionKeyId	Zeichenfolge	Gibt die keyId eines öffentlichen Schlüssels aus der keyCredentials-Sammlung an. Wenn konfiguriert, gibt Microsoft Entra ID Token für diese Anwendung aus, die mit dem durch diese Eigenschaft angegebenen Schlüssel verschlüsselt sind. Der Anwendungscode, der das verschlüsselte Token erhält, muss das Token mit dem zugehörigen privaten Schlüssel entschlüsseln, bevor es für den angemeldeten Benutzer verwendet werden kann.

Antwort

Wenn die Methode erfolgreich verläuft, werden der Antwortcode 204 No Content und ein aktualisiertes servicePrincipal-Objekt im Antworttext zurückgegeben.

Beispiel

Beispiel 1: Aktualisieren der Eigenschaften des angegebenen Dienstprinzipals

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

HTTP

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

{
  "appRoleAssignmentRequired": true
}

C#

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

OK

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Java

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PHP

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PowerShell

Import-Module Microsoft.Graph.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Python

# 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)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Antwort

Das folgende Beispiel zeigt die Antwort.

Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.

HTTP/1.1 204 No Content

Beispiel 2: Zuweisen eines benutzerdefinierten Sicherheitsattributs mit einem Zeichenfolgenwert zu einem Dienstprinzipal

Das folgende Beispiel zeigt, wie einem Dienstprinzipal ein benutzerdefiniertes Sicherheitsattribut mit einem Zeichenfolgenwert zugewiesen wird.

• Attributsatz: Engineering
• Attribut: ProjectDate
• Attributdatentyp: Zeichenfolge
• Attributwert: "2022-10-01"

Um benutzerdefinierte Sicherheitsattribute zuzuweisen, muss dem aufrufenden Prinzipal die Rolle "Attributzuweisungsadministrator" zugewiesen werden, und dem aufrufenden Prinzipal muss die Berechtigung CustomSecAttributeAssignment.ReadWrite.All erteilt werden.

Weitere ähnliche Beispiele für Benutzer finden Sie unter Beispiele: Zuweisen, Aktualisieren, Auflisten oder Entfernen benutzerdefinierter Sicherheitsattributzuweisungen mithilfe der Microsoft Graph-API.

Anforderung

Das folgende Beispiel zeigt eine Anfrage.

HTTP

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

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

C#

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

OK

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Java

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

JavaScript

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PHP

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

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

PowerShell

Import-Module Microsoft.Graph.Applications

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

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Python

# 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)

Einzelheiten darüber, wie Sie das SDK zu Ihrem Projekt hinzufügen und eine authProvider-Instanz erstellen, finden Sie in der SDK-Dokumentation.

Antwort

Das folgende Beispiel zeigt die Antwort.

HTTP/1.1 204 No Content