Actualizar servicePrincipal

Espacio de nombres: microsoft.graph

Actualice las propiedades del objeto servicePrincipal. Esta API también puede actualizar un objeto agentIdentityBlueprintPrincipal cuando la propiedad @odata.type se establece en #microsoft.graph.agentIdentityBlueprintPrincipal, o un objeto agentIdentity cuando la propiedad @odata.type se establece en #microsoft.graph.agentIdentity.

Importante

• No es compatible con el uso de PATCH para establecer passwordCredential. Use los métodos addPassword y removePassword para actualizar la contraseña o el secreto de servicePrincipal.

• Las entidades de servicio heredan propiedades específicas de sus registros de aplicaciones asociados. Estas propiedades se sincronizan desde el registro de la aplicación, pero la sincronización no es inmediata ni continua. A veces, la actualización de una entidad de servicio puede pedir al directorio que actualice las propiedades del registro de la aplicación, lo que provoca actualizaciones que no formaban parte de la solicitud original.

Esta API está disponible en las siguientes implementaciones en la nube nacional.

Servicio global	Administración pública de EE. UU.	Gobierno de EE. UU. L5 (DOD)	China operado por 21Vianet
✅	✅	✅	✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use uno o varios permisos con privilegios más altos solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso	Permisos con privilegios mínimos	Permisos con privilegios más altos
Delegado (cuenta profesional o educativa)	Application.ReadWrite.All	AgentIdentity.ReadWrite.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft)	No admitida.	No admitida.
Aplicación	Application.ReadWrite.OwnedBy	AgentIdentity.ReadWrite.All, Application.ReadWrite.All, Directory.ReadWrite.All

Importante

Para el acceso delegado con cuentas profesionales o educativas, el administrador debe tener asignado un rol compatible de Microsoft Entra o un rol personalizado que conceda los permisos necesarios para esta operación. Esta operación admite los siguientes roles integrados, que proporcionan solo el privilegio mínimo necesario:

• Para aplicaciones multiinquilino:
  • Administrador de la aplicación
  • Administrador de aplicaciones en la nube
• Para las aplicaciones de un solo inquilino en las que el usuario que llama es un usuario que no es administrador, pero es el propietario de la aplicación de respaldo, el usuario debe tener el rol de desarrollador de aplicaciones .

En escenarios delegados con cuentas profesionales o educativas, se admiten los siguientes privilegios para administrar identidades de agente y directores del plano técnico de identidad de agente:

• El usuario que ha iniciado sesión es el propietario, o bien
• Al usuario que ha iniciado sesión se le asigna el rol de administrador de ID de agente .

Permisos para escenarios específicos

• Para actualizar la propiedad customSecurityAttributes :
  • En escenarios delegados, se debe asignar al administrador el rol de Administrador de asignación de atributos y a la aplicación se le debe conceder el permiso delegado CustomSecAttributeAssignment.ReadWrite.All .
  • En escenarios de solo aplicación que usan permisos de Microsoft Graph, se debe conceder a la aplicación el permiso de aplicación CustomSecAttributeAssignment.ReadWrite.All .

Solicitud HTTP

Puede dirigirse a la entidad de servicio mediante su id o appId. id y appId se conocen como Id. de objeto e Id. de aplicación (cliente), respectivamente, en los registros de aplicaciones en el Centro de administración de Microsoft Entra.

PATCH /servicePrincipals/{id}
PATCH /servicePrincipals(appId='{appId}')

Encabezados de solicitud

Nombre	Descripción
Authorization	{token} de portador. Obligatorio. Obtenga más información sobre autenticación y autorización.
Content-Type	application/json. Obligatorio.

Cuerpo de solicitud

En el cuerpo de la solicitud, proporcione los valores de los campos relevantes que deben actualizarse. Las propiedades existentes que no están incluidas en el cuerpo de la solicitud mantienen sus valores anteriores o se recalculan en función de los cambios realizados en otros valores de propiedad. Para obtener el mejor rendimiento no debe incluir valores existentes que no hayan cambiado.

Propiedad	Tipo	Descripción
accountEnabled	Booleano	true si la entidad de servicio está habilitada; en caso contrario, false.
addIns	addIn	Permite definir el comportamiento personalizado que un servicio que consume puede usar para llamar a una aplicación en contextos específicos. Por ejemplo, las aplicaciones que pueden representar secuencias de archivo pueden establecer la propiedad addIns para su funcionalidad "FileHandler". Esto permite que servicios como Microsoft 365 llamen a la aplicación en el contexto de un documento en el que está trabajando el usuario.
alternativeNames	Colección de cadenas	Se usa para recuperar las entidades de servicio por suscripción, identificar el grupo de recursos e identificadores de recursos completos para las identidades administradas.
appRoleAssignmentRequired	Booleano	Especifica si se requiere una appRoleAssignment para un usuario o grupo antes de que Microsoft Entra ID emita un token de usuario o de acceso a la aplicación. No admite valores NULL.
appRoles	Colección appRole	Las funciones de aplicación que expone la aplicación asociada. Para obtener más información, consulte la definición de propiedad appRoles en el recurso de la aplicación . No admite valores NULL.
customSecurityAttributes	customSecurityAttributeValue	Un tipo complejo abierto que contiene el valor de un atributo de seguridad personalizado que se asigna a un objeto de directorio. Para actualizar esta propiedad en escenarios delegados, se debe asignar a la entidad de seguridad que realiza la llamada el rol de administrador de asignación de atributos y a la aplicación se le debe conceder el permiso delegado CustomSecAttributeAssignment.ReadWrite.All . Para actualizar esta propiedad en escenarios de solo aplicación con permisos de Microsoft Graph, se debe conceder a la aplicación el permiso de aplicación CustomSecAttributeAssignment.ReadWrite.All .
displayName	Cadena	El nombre para mostrar de la entidad de servicio.
homepage	String	La página de inicio o la página de aterrizaje de la aplicación.
keyCredentials	Colección keyCredential	El conjunto de credenciales clave asociadas con la entidad de servicio. No admite valores NULL.
logoutUrl	Cadena	Especifica la dirección URL que usará el servicio de autorización de Microsoft para cerrar la sesión de un usuario mediante protocolos de cierre de sesión de canal frontal, posterior o SAML.
oauth2PermissionScopes	Colección permissionScope	Los permisos OAuth 2.0 expuestos por la aplicación asociada. Para obtener más información, consulte la definición de propiedad oauth2PermissionScopes en el recurso de la aplicación . No admite valores NULL.
preferredSingleSignOnMode	cadena	Especifica el modo de inicio de sesión único configurado para esta aplicación. Microsoft Entra ID usa el modo de inicio de sesión único preferido para iniciar la aplicación desde Microsoft 365 o el portal Mis Aplicaciones. Los valores admitidos son: password, saml, external y oidc.
replyUrls	Colección de cadenas	Las direcciones URL a las que se envía los tokens de usuario para iniciar sesión con la aplicación asociada o el URI de redireccionamiento al que se envían los códigos de autorización de OAuth 2.0 y los tokens de acceso de la aplicación asociada. No admite valores NULL.
servicePrincipalNames	Colección de cadenas	Contiene la lista de identifiersUris, copiada desde la aplicación asociada. Se pueden agregar valores adicionales a las aplicaciones híbridas. Estos valores se pueden usar para identificar los permisos expuestos por esta aplicación en Microsoft Entra ID. Por ejemplo, Las aplicaciones cliente que soliciten permisos para este recurso pueden usar estos URI para especificar los permisos necesarios en la propiedad requiredResourceAccess del manifiesto de la aplicación o en la hoja "permisos de la API" en la experiencia de los registros de la aplicación. Las aplicaciones cliente pueden especificar un URI de recurso que se basa en los valores de esta propiedad para adquirir un token de acceso, que es el URI devuelto en la notificación "aud". El operador any es necesario para las expresiones de filtro en las propiedades de varios valores. No admite valores NULL.
tags	Colección string	Cadenas personalizadas que pueden usarse para clasificar por categorías e identificar aplicaciones. No admite valores NULL.
tokenEncryptionKeyId	Cadena	Especifica el valor keyId de una clave pública de la colección keyCredentials. Cuando se configura, Microsoft Entra ID emite tokens para esta aplicación cifrados con la clave especificada por esta propiedad. El código de aplicación que recibe el token cifrado debe usar la clave privada coincidente para descifrar el token a fin de poder usarlo para el usuario que ha iniciado sesión.

Respuesta

Si se ejecuta correctamente, este método devuelve un código de respuesta 204 No Content y el objeto servicePrincipal en el cuerpo de la respuesta.

Ejemplo

Ejemplo 1: Actualizar las propiedades de la entidad de servicio especificada

Solicitud

En el ejemplo siguiente se muestra la solicitud.

HTTP

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
  "appRoleAssignmentRequired": true
}

C#

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Ir

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Java

// 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

PHP

<?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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Python

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Respuesta

En el ejemplo siguiente se muestra la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 204 No Content

Ejemplo 2: Asignar un atributo de seguridad personalizado con un valor de cadena a una entidad de servicio

En el ejemplo siguiente se muestra cómo asignar un atributo de seguridad personalizado con un valor de cadena a una entidad de servicio.

• Conjunto de atributos: Engineering
• Atributo: ProjectDate
• Tipo de datos de atributo: Cadena
• Valor de atributo: "2022-10-01"

Para asignar atributos de seguridad personalizados, a la entidad de seguridad de llamada, se le debe asignar el rol Administrador de asignación de atributos y conceder el permiso CustomSecAttributeAssignment.ReadWrite.All.

Para obtener otros ejemplos similares para usuarios, vea Ejemplos: asignar, actualizar, enumerar o quitar asignaciones de atributos de seguridad personalizados mediante la API de Microsoft Graph API.

Solicitud

En el ejemplo siguiente se muestra la solicitud.

HTTP

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
Content-type: application/json

{
    "customSecurityAttributes":
    {
        "Engineering":
        {
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
            "ProjectDate":"2022-10-01"
        }
    }
}

C#

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Ir

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Java

// 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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

JavaScript

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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

PHP

<?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 obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

PowerShell

Import-Module Microsoft.Graph.Applications

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

Update-MgServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Python

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

Para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider, consulte la documentación del SDK.

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No Content