Atualizar servicePrincipal

Artigo
10/18/2023

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Atualizar as propriedades do objeto servicePrincipal.

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.

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

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

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas 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 privilegiadas mais altas
Delegado (conta corporativa ou de estudante)	Application.ReadWrite.All	Directory.ReadWrite.All
Delegado (conta pessoal da Microsoft)	Sem suporte.	Sem suporte.
Aplicativo	Application.ReadWrite.OwnedBy	Application.ReadWrite.All, Directory.ReadWrite.All

Solicitação HTTP

Você pode abordar a entidade de serviço usando sua id ou appId. Id e appId são chamados de ID de 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 em alterações em 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 em que o usuário está trabalhando.
alternativeNames	Coleção de cadeias de caracteres	Usado para recuperar entidades de serviço por assinatura, identificar grupo de recursos e IDs de recursos completos de identidades gerenciadas.
appRoleAssignmentRequired	Booliano	Especifica se um appRoleAssignment para um usuário ou grupo é necessário antes de Microsoft Entra ID emitirá um usuário ou um token de acesso ao 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 este imóvel, o responsável pela chamada deve ser designado como Administrador de Atribuição de Atributos e deve receber a permissão 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.
loginUrl	Cadeia de caracteres	Especifica a URL em que o provedor de serviços redireciona o usuário para Microsoft Entra ID a autenticação. Microsoft Entra ID usa a URL para iniciar o aplicativo do Microsoft 365 ou do Microsoft Entra Meus Aplicativos. Quando em branco, Microsoft Entra ID executa o logon iniciado por IdP para aplicativos configurados com logon único baseado em SAML. O usuário inicia o aplicativo do Microsoft 365, do Microsoft Entra Meus Aplicativos ou da URL do SSO Microsoft Entra.
logoutUrl	Cadeia de caracteres	Especifica a URL que será usada pelo serviço de autorização da Microsoft para fazer logon de um usuário usando protocolos de logon front-channel, back-channel ou SAML.
NotificationEmailAddresses	Coleção de cadeias de caracteres	Especifica a lista de endereços de email em que Microsoft Entra ID envia uma notificação quando o certificado ativo está perto da data de validade. Isso é apenas para os certificados usados para assinar o token SAML emitido para aplicativos da Galeria Microsoft Entra.
publishedPermissionScopes	coleção permissionScope	As permissões OAuth 2.0 expostas pelo aplicativo associado. Para obter mais informações, consulte a definição da propriedade oauth2PermissionScopes no recurso do aplicativo . Não anulável.
preferredSingleSignOnMode	cadeia de caracteres	Especifica o modo de logon único configurado para este aplicativo. Microsoft Entra ID usa o modo de logon único preferencial para iniciar o aplicativo do Microsoft 365 ou do Microsoft Entra Meus Aplicativos. Os valores com suporte são password, saml, external e oidc.
preferredTokenSigningKeyEndDateTime	DateTimeOffset	Especifica a data da expiração do keyCredential usado para a assinatura do token, marcado por preferredTokenSigningKeyThumbprint.
preferredTokenSigningKeyThumbprint	String	Reservado apenas para uso interno. Não escreva ou de outra forma confie nessa propriedade. Pode ser removida em versões futuras.
publisherName	String	O nome de exibição do locatário no qual o aplicativo associado está especificado.
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.
samlSingleSignOnSettings	samlSingleSignOnSettings	A coleção das configurações relacionadas ao logon único do SAML.
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 este aplicativo em 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 baseado 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	String collection	Não anulável.
tokenEncryptionKeyId	Cadeia de caracteres	Especifica a keyId de uma chave pública da coleção keyCredentials. Quando configurado, Microsoft Entra ID emite tokens para este aplicativo criptografados 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.

Exemplos

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

Importante

Os SDKs do Microsoft Graph usam a versão v1.0 da API por padrão e não oferecem suporte a todos os tipos, propriedades e APIs disponíveis na versão beta. Para obter detalhes sobre como acessar a API beta com o SDK, consulte Usar os SDKs do Microsoft Graph com a API beta.

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
  "appRoleAssignmentRequired": true\
}\
'

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewServicePrincipal()
appRoleAssignmentRequired := true
requestBody.SetAppRoleAssignmentRequired(&appRoleAssignmentRequired) 

servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


Import-Module Microsoft.Graph.Beta.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal

graph_client = GraphServiceClient(credentials, scopes)

request_body = ServicePrincipal(
	app_role_assignment_required = True,
)

result = await graph_client.service_principals.by_service_principal_id('servicePrincipal-id').patch(request_body)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Resposta

O exemplo a seguir mostra a resposta. Observação: O objeto de resposta exibido aqui pode ser encurtado para legibilidade.

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 outros exemplos semelhantes para usuários, consulte Exemplos: Atribuir, atualizar, listar ou remover atribuições de atributo de segurança personalizadas usando o microsoft API do Graph.

Solicitação

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;

var requestBody = new ServicePrincipal
{
	CustomSecurityAttributes = new CustomSecurityAttributeValue
	{
		AdditionalData = new Dictionary<string, object>
		{
			{
				"Engineering" , new 
				{
					OdataType = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
					ProjectDate = "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);

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
    "customSecurityAttributes":\
    {\
        "Engineering":\
        {\
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",\
            "ProjectDate":"2022-10-01"\
        }\
    }\
}\
'

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewServicePrincipal()
customSecurityAttributes := graphmodels.NewCustomSecurityAttributeValue()
additionalData := map[string]interface{}{
engineering := graphmodels.New()
projectDate := "2022-10-01"
engineering.SetProjectDate(&projectDate) 
	customSecurityAttributes.SetEngineering(engineering)
}
customSecurityAttributes.SetAdditionalData(additionalData)
requestBody.SetCustomSecurityAttributes(customSecurityAttributes)

servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


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

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


Import-Module Microsoft.Graph.Beta.Applications

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

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.


from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
from msgraph.generated.models.custom_security_attribute_value import CustomSecurityAttributeValue

graph_client = GraphServiceClient(credentials, scopes)

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)

Importante

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider, consulte a documentação do SDK.

Resposta

HTTP/1.1 204 No Content

Atualizar servicePrincipal

Permissões

Solicitação HTTP

Cabeçalhos de solicitação

Corpo da solicitação

Resposta

Exemplos

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

Comentários

Recursos adicionais