Namespace: microsoft.graph
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.
Os principais de serviço herdam propriedades específicas dos respetivos registos de aplicações associados. Estas propriedades são sincronizadas a partir do registo de aplicações, mas a sincronização não é imediata ou contínua. Por vezes, a atualização de um principal de serviço pode pedir ao diretório para atualizar as propriedades do registo da aplicação, o que causa atualizações que não fizeram parte do pedido original.
Esta API está disponível nas seguintes implementações de cloud nacionais.
| Serviço global |
US Government L4 |
US Government L5 (DOD) |
China operada pela 21Vianet |
| ✅ |
✅ |
✅ |
✅ |
Permissões
Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.
| Tipo de permissão |
Permissões com menos privilégios |
Permissões com privilégios superiores |
| Delegado (conta corporativa ou de estudante) |
Application.ReadWrite.All |
AgentIdentity.EnableDisable.All, AgentIdentity.ReadWrite.All, AgentIdentityBlueprintPrincipal.EnableDisable.All, Directory.ReadWrite.All |
| Delegado (conta pessoal da Microsoft) |
Sem suporte. |
Sem suporte. |
| Application |
Application.ReadWrite.OwnedBy |
AgentIdentity.EnableDisable.All, AgentIdentity.ReadWrite.All, AgentIdentityBlueprintPrincipal.EnableDisable.All, Application.ReadWrite.All, Directory.ReadWrite.All |
Importante
Em cenários delegados com contas escolares ou profissionais, tem de ser atribuída ao administrador uma função de Microsoft Entra suportada ou uma função personalizada com uma permissão de função suportada. As seguintes funções com menos privilégios são suportadas para esta operação.
- Para aplicações multi-inquilino:
- Administrador de Aplicativos
- Administrador de Aplicativos de Nuvem
- Para aplicações de inquilino único em que o utilizador que chama é um utilizador não administrador, mas é o proprietário da aplicação de apoio, o utilizador tem de ter a função Programador de Aplicações .
Permissões para cenários específicos
- Para atualizar a propriedade customSecurityAttributes :
- Em cenários delegados, tem de ser atribuída ao administrador a função Administrador de Atribuição de Atributos e a aplicação concedeu a permissão delegada CustomSecAttributeAssignment.ReadWrite.All .
- Em cenários apenas de aplicações com permissões do Microsoft Graph, a aplicação tem de ter a permissão de aplicação CustomSecAttributeAssignment.ReadWrite.All .
Solicitação HTTP
Pode abordar o principal de serviço com o respetivo ID ou appId.
O id e o appId são referidos como o ID do Objeto e o ID da Aplicação (Cliente), respetivamente, nos registos de aplicações no centro de administração do Microsoft Entra.
PATCH /servicePrincipals/{id}
PATCH /servicePrincipals(appId='{appId}')
| 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 do pedido mantêm os valores anteriores ou são recalculadas com base em alterações a 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". Isto permite que serviços como o Microsoft 365 chamem a aplicação no contexto de um documento em que o utilizador está a trabalhar. |
| alternativeNames |
Coleção de cadeias de caracteres |
Utilizado para obter principais de serviço por subscrição, identifique o grupo de recursos e os IDs de recursos completos para identidades geridas. |
| appRoleAssignmentRequired |
Booliano |
Especifica se é necessário um appRoleAssignment para um utilizador ou grupo antes de Microsoft Entra ID emitir um utilizador ou token de acesso para a aplicação. Não anulável. |
| appRoles |
appRole collection |
As funções do aplicativo expostas pelo aplicativo associado. Para obter mais informações, veja a definição da propriedade appRoles no recurso da aplicação . 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 esta propriedade em cenários delegados, o principal de chamada tem de ter atribuída a função Administrador de Atribuição de Atributos e a aplicação concedeu a permissão CustomSecAttributeAssignment.ReadWrite.All delegated.Para atualizar esta propriedade em cenários apenas de aplicações com permissões do Microsoft Graph, tem de ser concedida a permissão de aplicaçã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. |
| logoutUrl |
Cadeia de caracteres |
Especifica o URL que será utilizado pelo serviço de autorização da Microsoft para terminar sessão de um utilizador através de protocolos de início de sessão de front-channel, back-channel ou SAML. |
| oauth2PermissionScopes |
coleção permissionScope |
As permissões do escopo OAuth 2.0 expostas pelo aplicativo associado. Para obter mais informações, veja a definição da propriedade oauth2PermissionScopes no recurso da aplicação . Não anulável. |
| preferredSingleSignOnMode |
cadeia de caracteres |
Especifica o modo de logon único configurado para este aplicativo. Microsoft Entra ID utiliza o modo de início de sessão único preferencial para iniciar a aplicação a partir do Microsoft 365 ou do 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. Estes valores podem ser utilizados para identificar as permissões expostas por esta aplicação 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.
- As aplicações cliente podem especificar um URI de recurso baseado nos valores desta propriedade para adquirir um token de acesso, que é o URI devolvido na afirmaçã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, Microsoft Entra ID os tokens de problemas para esta aplicação encriptados com a chave especificada por esta 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://v4.hkg1.meaqua.org/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
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 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://v4.hkg1.meaqua.org/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)
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);
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}')
.update(servicePrincipal);
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();
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 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://v4.hkg1.meaqua.org/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)
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 os utilizadores, consulte Exemplos: Atribuir, atualizar, listar ou remover atribuições de atributos de segurança personalizadas com o microsoft 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://v4.hkg1.meaqua.org/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals["{servicePrincipal-id}"].PatchAsync(requestBody);
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 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://v4.hkg1.meaqua.org/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().ByServicePrincipalId("servicePrincipal-id").Patch(context.Background(), requestBody, nil)
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);
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}')
.update(servicePrincipal);
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();
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.Applications
$params = @{
customSecurityAttributes = @{
Engineering = @{
"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
ProjectDate = "2022-10-01"
}
}
}
Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params
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 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://v4.hkg1.meaqua.org/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)
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.
HTTP/1.1 204 No Content