Actualizar servicePrincipal

Espacio de nombres: microsoft.graph

Actualice las propiedades del objeto servicePrincipal.

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.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global	Gobierno de EE. UU. L4	Us Government L5 (DOD)	China operada por 21Vianet
✅	✅	✅	✅

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Tipo de permiso	Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa)	Application.ReadWrite.All
Delegado (cuenta personal de Microsoft)	No admitida.
Application	Application.ReadWrite.OwnedBy, Application.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 y id. de aplicación (cliente), respectivamente, en los registros de aplicaciones en el Centro de administración 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 la autenticación y la 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 se incluyen 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 el usuario está trabajando.
alternativeNames	Colección de cadenas	Se usa para recuperar entidades de servicio por suscripción, identificar el grupo de recursos y los identificadores de recursos completos para las identidades administradas.
appRoleAssignmentRequired	Booleano	Especifica si se requiere un 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, vea la definición de la 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, 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.
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 los protocolos de cierre de sesión de front-channel, back-channel o SAML.
oauth2PermissionScopes	Colección permissionScope	Los permisos OAuth 2.0 expuestos por la aplicación asociada. Para obtener más información, vea la definición de la propiedad oauth2PermissionScopes en el recurso de 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 de 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 dentro de 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 identificador URI de recurso basado en los valores de esta propiedad para adquirir un token de acceso, que es la dirección URI devuelta 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 cifrada mediante 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.

CLI

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

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

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-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)

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

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)

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: el objeto de respuesta que se muestra aquí puede haberse acortado 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 ver otros ejemplos similares para los usuarios, consulte Ejemplos: Asignación, actualización, lista o eliminación de asignaciones de atributos de seguridad personalizados mediante 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;

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

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.

CLI

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

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

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-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)

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

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)

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