Actualizar servicePrincipal

Artículo
10/02/2024

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

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
✅	✅	✅	✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores 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	Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft)	No admitida.	No admitida.
Aplicación	Application.ReadWrite.OwnedBy	Application.ReadWrite.All, Directory.ReadWrite.All

Nota:

Para actualizar la propiedad customSecurityAttributes :
- En escenarios delegados, al administrador se le debe asignar el rol Administrador de asignación de atributos y a la aplicación se le concede 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 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 las entidades de servicio por suscripción, identificar el grupo de recursos y los ID. de recursos completos para 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 en escenarios delegados, a la entidad de seguridad que realiza la llamada se le debe asignar el rol Administrador de asignación de atributos y a la aplicación se le concede 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.
loginUrl	Cadena	Especifica la dirección URL donde el proveedor de servicios redirige al usuario a Microsoft Entra ID para autenticarse. Microsoft Entra ID usa la dirección URL para iniciar la aplicación desde Microsoft 365 o la Microsoft Entra Aplicaciones. Cuando está en blanco, Microsoft Entra ID realiza el inicio de sesión iniciado por IdP para las aplicaciones configuradas con el inicio de sesión único basado en SAML. El usuario inicia la aplicación desde Microsoft 365, la Microsoft Entra Aplicaciones o la dirección URL de inicio de sesión único de Microsoft Entra.
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.
notificationEmailAddresses	Colección de cadenas	Especifica la lista de direcciones de correo electrónico donde Microsoft Entra ID envía una notificación cuando el certificado activo está cerca de la fecha de expiración. Esto solo es para los certificados que se usan para firmar el token SAML emitido para Microsoft Entra aplicaciones de la Galería.
publishedPermissionScopes	Colección permissionScope	Los permisos de 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 Microsoft Entra Aplicaciones. Los valores compatibles son password, saml, external y oidc.
preferredTokenSigningKeyEndDateTime	DateTimeOffset	Especifica la fecha de caducidad de la keyCredential usada para la firma de tokens, marcada por preferredTokenSigningKeyThumbprint.
preferredTokenSigningKeyThumbprint	Cadena	Reservado solo para uso interno. No escriba ni dependa de esta propiedad. Puede quitarse en versiones futuras.
publisherName	Cadena	El nombre para mostrar del espacio empresarial en el que se especifica la aplicación asociada.
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.
samlSingleSignOnSettings	samlSingleSignOnSettings	La colección de configuraciones relacionadas con el inicio de sesión único de SAML.
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 URI de recurso basado 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 de cadenas	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 un objeto actualizado servicePrincipal en el cuerpo de la respuesta.

Ejemplos

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

Solicitud

En el ejemplo siguiente se muestra la solicitud.

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

Los SDK de Microsoft Graph usan la versión v1.0 de la API de manera predeterminada y no admiten todos los tipos, propiedades y API disponibles en la versión beta. Para obtener más información sobre cómo acceder a la API beta con el SDK, consulte Uso de los SDK de Microsoft Graph con la API beta.

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.



mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
  "appRoleAssignmentRequired": true\
}\
'

Importante

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.



// Code snippets are only available for the latest major version. Current major version is $v0.*

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

Importante

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.


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


const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
  appRoleAssignmentRequired: true
};

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

Importante

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
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\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 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.


Import-Module Microsoft.Graph.Beta.Applications

$params = @{
	appRoleAssignmentRequired = $true
}

Update-MgBetaServicePrincipal -ServicePrincipalId $servicePrincipalId -BodyParameter $params

Importante

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.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.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)

Importante

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

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

Importante

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.



mgc-beta service-principals patch --service-principal-id {servicePrincipal-id} --body '{\
    "customSecurityAttributes":\
    {\
        "Engineering":\
        {\
            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",\
            "ProjectDate":"2022-10-01"\
        }\
    }\
}\
'

Importante

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.



// Code snippets are only available for the latest major version. Current major version is $v0.*

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

Importante

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.


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


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 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
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\ServicePrincipal;
use Microsoft\Graph\Beta\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 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.


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 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.


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.service_principal import ServicePrincipal
from msgraph_beta.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)

Importante

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

HTTP/1.1 204 No Content

Compartir a través de

Actualizar servicePrincipal

Permissions

Solicitud HTTP

Encabezados de solicitud

Cuerpo de solicitud

Respuesta

Ejemplos

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

Solicitud

Respuesta

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

Solicitud

Respuesta

Comentarios

Recursos adicionales