Executar upsert servicePrincipal

Namespace: microsoft.graph

Crie um novo objeto servicePrincipal se ele não existir ou atualize as propriedades de um objeto servicePrincipal existente.

Essa API também pode criar um objeto agentIdentityBlueprintPrincipal de um agentIdentityBlueprint , se ele não existir, ou atualizar as propriedades de um agentIdentityBlueprintPrincipal existente, quando a propriedade @odata.type for definida como #microsoft.graph.agentIdentityBlueprintPrincipal.

Importante

Não há suporte para a adição de passwordCredential durante a criação de servicePrincipals. Use o método addPassword para adicionar senhas ou segredos para um servicePrincipal.

Essa API está disponível nas seguintes implantações de nuvem nacional.

Serviço global	Governo dos EUA L4	US Government L5 (DOD)	China operada pela 21Vianet
✅	✅	✅	✅

Permissões

Escolha a(s) permissão(s) marcada(s) como menos privilegiada(s) para essa API. Use uma permissão ou permissões com privilégios mais altos somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão	Permissões menos privilegiadas	Permissões com privilégios mais elevados
Delegado (conta corporativa ou de estudante)	Application.ReadWrite.All	Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.	Sem suporte.
Application	Application.ReadWrite.OwnedBy	Application.ReadWrite.All, Directory.ReadWrite.All

Importante

Para acesso delegado usando contas corporativas ou de estudante, o administrador deve receber uma função do Microsoft Entra com suporte ou uma função personalizada que conceda as permissões necessárias para esta operação. Esta operação dá suporte às seguintes funções internas, que fornecem apenas o menor privilégio necessário:

Para aplicativos multilocatário:
- Administrador de Aplicativos
- Administrador de Aplicativos de Nuvem
Para aplicativos de locatário único em que o usuário que está chamando é um usuário não administrador, mas é o proprietário do aplicativo de apoio, o usuário deve ter a função Desenvolvedor de Aplicativos .

Em cenários delegados usando contas corporativas ou de estudante, os seguintes privilégios têm suporte para o gerenciamento de identidades de agente e entidades de segurança de blueprint de identidade de agente:

O usuário conectado é o proprietário ou
O usuário conectado recebe a função de Administrador de ID de Agente .

Solicitação HTTP

PATCH /servicePrincipals(appId='appId')

Cabeçalhos de solicitação

Nome	Descrição
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Content-Type	application/json. Obrigatório.
Preferir	`create-if-missing`. Necessário para o comportamento de upsert, caso contrário, a solicitação será tratada como uma operação de atualização.

Corpo da solicitação

No corpo da solicitação, forneça uma representação JSON de um objeto servicePrincipal.

Resposta

Se for bem-sucedido, se um servicePrincipal ou agentIdentityBlueprintPrincipal com appId não existir, esse método retornará um código de 201 Created resposta e um novo objeto servicePrincipal ou agentIdentityBlueprintPrincipal no corpo da resposta.

Se já existir um servicePrincipal ou agentIdentityBlueprintPrincipal com appId , esse método atualizará o objeto servicePrincipal ou agentIdentityBlueprintPrincipal e retornará um código de 204 No Content resposta.

Exemplos

Exemplo 1: Criar uma nova servicePrincipal se ela não existir

O exemplo a seguir cria um servicePrincipal porque não existe um servicePrincipal com o valor appId especificado.

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/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.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 $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  graphserviceprincipalswithappid "github.com/microsoftgraph/msgraph-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\GraphServiceClient;
use Microsoft\Graph\Generated\ServicePrincipals_with_app_id\ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\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.Applications

$params = @{
	displayName = "My app instance"
}

Update-MgServicePrincipalByAppId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.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.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)

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$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": []
}

Exemplo 2: atualizar um servicePrincipal existente

O exemplo a seguir atualiza o servicePrincipal porque existe um servicePrincipal com o valor appId especificado.

Solicitação

O exemplo a seguir mostra uma solicitação.

PATCH https://graph.microsoft.com/v1.0/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.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 $v1.*

// Dependencies
import (
	  "context"
	  abstractions "github.com/microsoft/kiota-abstractions-go"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  graphserviceprincipalswithappid "github.com/microsoftgraph/msgraph-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\GraphServiceClient;
use Microsoft\Graph\Generated\ServicePrincipals_with_app_id\ServicePrincipalsWithAppIdRequestBuilderPatchRequestConfiguration;
use Microsoft\Graph\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.Applications

$params = @{
	displayName = "My app instance"
}

Update-MgServicePrincipalByAppId -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.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.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)

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Comentários

Esta página foi útil?

Last updated on 2026-08-24

Executar upsert servicePrincipal

Permissões

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

Exemplo 1: Criar uma nova servicePrincipal se ela não existir

Solicitação

Resposta

Exemplo 2: atualizar um servicePrincipal existente

Solicitação

Resposta

Comentários

Recursos adicionais