Namespace: microsoft.graph
Wichtig
Die APIs unter der /beta Version in Microsoft Graph können sich ändern. Die Verwendung dieser APIs in Produktionsanwendungen wird nicht unterstützt. Um festzustellen, ob eine API in v1.0 verfügbar ist, verwenden Sie die Version Selektor.
Erstellen Sie ein neues servicePrincipal-Objekt , falls es nicht vorhanden ist, oder aktualisieren Sie die Eigenschaften eines vorhandenen servicePrincipal-Objekts .
Diese API kann auch ein agentIdentityBlueprintPrincipal-Objekt aus einem agentIdentityBlueprint erstellen, falls dieser nicht vorhanden ist, oder Eigenschaften eines vorhandenen agentIdentityBlueprintPrincipal aktualisieren, wenn die @odata.type-Eigenschaft auf #microsoft.graph.agentIdentityBlueprintPrincipalfestgelegt ist.
Wichtig
Das Hinzufügen von passwordCredential beim Erstellen von servicePrincipals wird nicht unterstützt. Verwenden Sie die addPassword- Methode, um Kennwörter oder Geheimnisse für einen servicePrincipal hinzuzufügen.
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 |
Directory.ReadWrite.All |
| Delegiert (persönliches Microsoft-Konto) |
Nicht unterstützt |
Nicht unterstützt |
| Application |
Application.ReadWrite.OwnedBy |
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.
HTTP-Anforderung
PATCH /servicePrincipals(appId='appId')
| Name |
Beschreibung |
| Authorization |
Bearer {token}. Erforderlich. Erfahren Sie mehr über Authentifizierung und Autorisierung. |
| Content-Type |
application/json. Erforderlich. |
| Prefer |
create-if-missing. Erforderlich für Upsert-Verhalten, andernfalls wird die Anforderung als Update-Vorgang behandelt. |
Anforderungstext
Geben Sie im Anforderungstext eine JSON-Darstellung eines servicePrincipal-Objekts an.
Antwort
Wenn bei erfolgreicher Ausführung kein servicePrincipal oder agentIdentityBlueprintPrincipal mit appId vorhanden ist, gibt diese Methode einen 201 Created Antwortcode und ein neues servicePrincipal - oder agentIdentityBlueprintPrincipal-Objekt im Antworttext zurück.
Wenn bereits ein servicePrincipal oder agentIdentityBlueprintPrincipal mit appId vorhanden ist, aktualisiert diese Methode das servicePrincipal - oder agentIdentityBlueprintPrincipal-Objekt und gibt einen 204 No Content Antwortcode zurück.
Beispiele
Beispiel 1: Erstellen eines neuen servicePrincipal, wenn er nicht vorhanden ist
Im folgenden Beispiel wird ein servicePrincipal erstellt, da kein servicePrincipal mit dem angegebenen appId-Wert vorhanden ist.
Anforderung
Das folgende Beispiel zeigt eine Anfrage.
PATCH https://graph.microsoft.com/beta/servicePrincipals(appId='65415bb1-9267-4313-bbf5-ae259732ee12')
Content-type: application/json
Prefer: create-if-missing
{
"displayName": "My app instance"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new ServicePrincipal
{
DisplayName = "My app instance",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").PatchAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
graphserviceprincipalswithappid "github.com/microsoftgraph/msgraph-beta-sdk-go/serviceprincipalswithappid"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "create-if-missing")
configuration := &graphserviceprincipalswithappid.ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration{
Headers: headers,
}
requestBody := graphmodels.NewServicePrincipal()
displayName := "My app instance"
requestBody.SetDisplayName(&displayName)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Patch(context.Background(), requestBody, configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setDisplayName("My app instance");
ServicePrincipal result = graphClient.servicePrincipalsWithAppId("{appId}").patch(servicePrincipal, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "create-if-missing");
});
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\ServicePrincipals_with_app_id\ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\Beta\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setDisplayName('My app instance');
$requestConfiguration = new ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration();
$headers = [
'Prefer' => 'create-if-missing',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->patch($requestBody, $requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Applications
$params = @{
displayName = "My app instance"
}
Update-MgBetaServicePrincipalByAppId -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.service_principals_with_app_id.service_principals_with_app_id_request_builder import ServicePrincipalsWithAppIdRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
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(
display_name = "My app instance",
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "create-if-missing")
result = await graph_client.service_principals_with_app_id("{appId}").patch(request_body, request_configuration = request_configuration)
Antwort
Das folgende Beispiel zeigt die Antwort.
Hinweis: Das hier gezeigte Antwortobjekt kann zur besseren Lesbarkeit gekürzt werden.
HTTP/1.1 201 Created
Content-type: application/json
{
"@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals/$entity",
"id": "59e617e5-e447-4adc-8b88-00af644d7c92",
"deletedDateTime": null,
"accountEnabled": true,
"appDisplayName": "My App",
"appId": "65415bb1-9267-4313-bbf5-ae259732ee12",
"applicationTemplateId": null,
"appOwnerOrganizationId": "1bc1c026-2f7b-48a5-98da-afa2fd8bc7bc",
"appRoleAssignmentRequired": false,
"displayName": "My app instance",
"errorUrl": null,
"homepage": null,
"loginUrl": null,
"logoutUrl": null,
"notificationEmailAddresses": [],
"preferredSingleSignOnMode": null,
"preferredTokenSigningKeyEndDateTime": null,
"preferredTokenSigningKeyThumbprint": null,
"publisherName": "Contoso",
"replyUrls": [],
"samlMetadataUrl": null,
"samlSingleSignOnSettings": null,
"servicePrincipalNames": [
"f1bd758f-4a1a-4b71-aa20-a248a22a8928"
],
"signInAudience": "AzureADandPersonalMicrosoftAccount",
"tags": [],
"addIns": [],
"api": {
"resourceSpecificApplicationPermissions": []
},
"appRoles": [],
"info": {
"termsOfServiceUrl": null,
"supportUrl": null,
"privacyStatementUrl": null,
"marketingUrl": null,
"logoUrl": null
},
"keyCredentials": [],
"publishedPermissionScopes": [],
"passwordCredentials": []
}
Beispiel 2: Aktualisieren eines vorhandenen servicePrincipal
Im folgenden Beispiel wird der servicePrincipal aktualisiert, da ein servicePrincipal mit dem angegebenen appId-Wert vorhanden ist.
Anforderung
Das folgende Beispiel zeigt eine Anfrage.
PATCH https://graph.microsoft.com/beta/servicePrincipals(appId='65415bb1-9267-4313-bbf5-ae259732ee12')
Content-type: application/json
Prefer: create-if-missing
{
"displayName": "My app instance"
}
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Beta.Models;
var requestBody = new ServicePrincipal
{
DisplayName = "My app instance",
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").PatchAsync(requestBody, (requestConfiguration) =>
{
requestConfiguration.Headers.Add("Prefer", "create-if-missing");
});
// Code snippets are only available for the latest major version. Current major version is $v0.*
// Dependencies
import (
"context"
abstractions "github.com/microsoft/kiota-abstractions-go"
msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
graphserviceprincipalswithappid "github.com/microsoftgraph/msgraph-beta-sdk-go/serviceprincipalswithappid"
//other-imports
)
headers := abstractions.NewRequestHeaders()
headers.Add("Prefer", "create-if-missing")
configuration := &graphserviceprincipalswithappid.ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration{
Headers: headers,
}
requestBody := graphmodels.NewServicePrincipal()
displayName := "My app instance"
requestBody.SetDisplayName(&displayName)
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Patch(context.Background(), requestBody, configuration)
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setDisplayName("My app instance");
ServicePrincipal result = graphClient.servicePrincipalsWithAppId("{appId}").patch(servicePrincipal, requestConfiguration -> {
requestConfiguration.headers.add("Prefer", "create-if-missing");
});
<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\ServicePrincipals_with_app_id\ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\Beta\Generated\Models\ServicePrincipal;
$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);
$requestBody = new ServicePrincipal();
$requestBody->setDisplayName('My app instance');
$requestConfiguration = new ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration();
$headers = [
'Prefer' => 'create-if-missing',
];
$requestConfiguration->headers = $headers;
$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->patch($requestBody, $requestConfiguration)->wait();
Import-Module Microsoft.Graph.Beta.Applications
$params = @{
displayName = "My app instance"
}
Update-MgBetaServicePrincipalByAppId -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.service_principals_with_app_id.service_principals_with_app_id_request_builder import ServicePrincipalsWithAppIdRequestBuilder
from kiota_abstractions.base_request_configuration import RequestConfiguration
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(
display_name = "My app instance",
)
request_configuration = RequestConfiguration()
request_configuration.headers.add("Prefer", "create-if-missing")
result = await graph_client.service_principals_with_app_id("{appId}").patch(request_body, request_configuration = request_configuration)
Antwort
Das folgende Beispiel zeigt die Antwort.
HTTP/1.1 204 No Content