Atualizar servicePrincipal

Namespace: microsoft.graph

Atualizar as propriedades do objeto servicePrincipal. Essa API também pode atualizar um objeto agentIdentityBlueprintPrincipal quando a propriedade @odata.type é definida como #microsoft.graph.agentIdentityBlueprintPrincipal, ou um objeto agentIdentity quando a propriedade @odata.type é definida como #microsoft.graph.agentIdentity.

Importante

Não há suporte para o uso do PATCH para definir passwordCredential. Use os métodos addPassword e removePassword para atualizar a senha ou segredo de um servicePrincipal.
As entidades de serviço herdam propriedades específicas de seus registros de aplicativo associados. Essas propriedades são sincronizadas do registro do aplicativo, mas a sincronização não é imediata ou contínua. Às vezes, a atualização de uma entidade de serviço pode solicitar que o diretório atualize as propriedades do registro do aplicativo, causando atualizações que não faziam parte da solicitação original.

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 .

Permissões para cenários específicos

Para atualizar a propriedade customSecurityAttributes :
- Em cenários delegados, o administrador deve receber a função de Administrador de Atribuição de Atributo e o aplicativo deve receber a permissão delegada CustomSecAttributeAssignment.ReadWrite.All .
- Em cenários somente de aplicativo usando permissões do Microsoft Graph, o aplicativo deve receber a permissão de aplicativo CustomSecAttributeAssignment.ReadWrite.All .

Solicitação HTTP

Você pode endereçar a entidade de serviço usando sua id ou appId. id e appId são chamados de ID do Objeto e ID do Aplicativo (Cliente), respectivamente, em registros de aplicativo no centro de administração do Microsoft Entra.

PATCH /servicePrincipals/{id}
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.

Corpo da solicitação

No corpo da solicitação, forneça os valores para os campos relevantes que devem ser atualizados. As propriedades existentes que não estão incluídas no corpo da solicitação mantêm seus valores anteriores ou são recalculadas com base nas alterações de outros valores de propriedade. Para obter um melhor desempenho, não inclua valores existentes que não foram alterados.

Propriedade	Tipo	Descrição
accountEnabled	Boolean	True se a entidade de serviço estiver habilitada; caso contrário, false.
addIns	addIn	Define o comportamento personalizado que um serviço de consumo pode usar para chamar um aplicativo em contextos específicos. Por exemplo, aplicativos que podem renderizar fluxos de arquivo podem definir a propriedade addIns para a funcionalidade "FileHandler". Isso permite que serviços como o Microsoft 365 chamem o aplicativo no contexto de um documento no qual o usuário está trabalhando.
alternativeNames	Coleção de cadeias de caracteres	Usado para recuperar entidades de serviço por assinatura, identificar IDs de recursos completas e de grupo de recursos para identidades gerenciadas.
appRoleAssignmentRequired	Booliano	Especifica se um appRoleAssignment para um usuário ou grupo é necessário antes que o Microsoft Entra ID emita um token de usuário ou de acesso para o aplicativo. Não anulável.
appRoles	appRole collection	As funções do aplicativo expostas pelo aplicativo associado. Para obter mais informações, consulte a definição de propriedade appRoles no recurso de aplicativo . Não anulável.
customSecurityAttributes	customSecurityAttributeValue	Um tipo complexo aberto que contém o valor de um atributo de segurança personalizado atribuído a um objeto de diretório. Para atualizar essa propriedade em cenários delegados, a entidade de chamada deve receber a função de Administrador de Atribuição de Atributo e o aplicativo deve receber a permissão delegada CustomSecAttributeAssignment.ReadWrite.All . Para atualizar essa propriedade em cenários somente de aplicativo com permissões do Microsoft Graph, o aplicativo deve receber a permissão de aplicativo CustomSecAttributeAssignment.ReadWrite.All .
displayName	String	O nome de exibição da entidade de serviço.
homepage	Cadeia de caracteres	Página inicial ou página de aterrissagem do aplicativo.
keyCredentials	keyCredential collection	A coleção de credenciais principais associada à entidade de serviço. Não anulável.
logoutUrl	Cadeia de caracteres	Especifica a URL que será usada pelo serviço de autorização da Microsoft para desconectar um usuário usando protocolos de logout SAML, de canal frontal, de canal traseiro ou SAML.
oauth2PermissionScopes	coleção permissionScope	As permissões do escopo OAuth 2.0 expostas pelo aplicativo associado. Para obter mais informações, consulte a definição da propriedade oauth2PermissionScopes no recurso de aplicativo . Não anulável.
preferredSingleSignOnMode	cadeia de caracteres	Especifica o modo de logon único configurado para este aplicativo. O Microsoft Entra ID usa o modo de logon único preferencial para iniciar o aplicativo no Microsoft 365 ou no portal Meus Aplicativos. Os valores com suporte são: `password`, `saml`, `external`, e `oidc`.
replyUrls	String collection	As URLs às quais os tokens de usuário são enviados para entrar com aplicativo associado ou os URIs de redirecionamento aos quais os códigos de autorização do OAuth 2.0 e tokens de acesso são enviados para o aplicativo associado. Não anulável.
servicePrincipalNames	Coleção de cadeias de caracteres	Contém a lista de identificadoresUris, copiados do aplicativo associado. É possível adicionar valores adicionais aos aplicativos híbridos. Esses valores podem ser usados para identificar as permissões expostas por esse aplicativo no Microsoft Entra ID. Por exemplo, Os aplicativos cliente solicitando permissões para este recurso podem usar esses URIs para especificar as permissões necessárias na propriedade requiredResourceAccess do manifesto do aplicativo, ou na lâmina "permissões de API" na experiência de registros de aplicativos. Os aplicativos cliente podem especificar um URI de recurso com base nos valores dessa propriedade para adquirir um token de acesso, que é o URI retornado na declaração "aud". O operador any é obrigatório para expressões de filtro em propriedades de vários valores. Não anulável.
tags	Coleção String	Sequências personalizadas que podem ser usadas para categorizar e identificar o aplicativo. Não anulável.
tokenEncryptionKeyId	Cadeia de caracteres	Especifica a keyId de uma chave pública da coleção keyCredentials. Quando configurado, o Microsoft Entra ID emite tokens para esse aplicativo criptografado usando a chave especificada por essa propriedade. O código de aplicativo que recebe o token criptografado deve usar a chave privada correspondente para descriptografar o token a fim de que ele possa ser usado para o usuário conectado.

Resposta

Se bem-sucedido, este método retorna um código de resposta 204 No Content e um objeto atualizado servicePrincipal no corpo da resposta.

Exemplo

Exemplo 1: Propriedades de atualização do princípio de serviço especificado

Solicitação

O exemplo a seguir mostra uma solicitação.

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)

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 204 No Content

Exemplo 2: atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a um principal de serviço

O exemplo a seguir mostra como atribuir um atributo de segurança customizado com um valor de cadeia de caracteres a um principal de serviço.

Conjunto de atributos: Engineering
Atributo: ProjectDate
Tipo de dados de atributo: cadeia de caracteres
Valor do atributo: "2022-10-01"

Para atribuir atributos de segurança personalizados, o principal de chamada deve ser atribuído à função de Administrador de Atribuição de Atributo e deve receber a permissão CustomSecAttributeAssignment.ReadWrite.All.

Para obter outros exemplos semelhantes para usuários, consulte Exemplos: atribuir, atualizar, listar ou remover atribuições de atributos de segurança personalizados usando a API do Graph.

Solicitação

O exemplo a seguir mostra uma solicitação.

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)

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

Atualizar servicePrincipal

Permissões

Permissões para cenários específicos

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplo

Exemplo 1: Propriedades de atualização do princípio de serviço especificado

Solicitação

Resposta

Exemplo 2: atribuir um atributo de segurança personalizado com um valor de cadeia de caracteres a um principal de serviço

Solicitação

Resposta

Comentários

Recursos adicionais