Compartir a través de


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

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

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

    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.

    PATCH https://graph.microsoft.com/v1.0/servicePrincipals/{id}
    Content-type: application/json
    
    {
        "customSecurityAttributes":
        {
            "Engineering":
            {
                "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
                "ProjectDate":"2022-10-01"
            }
        }
    }
    

    Respuesta

    En el ejemplo siguiente se muestra la respuesta.

    HTTP/1.1 204 No Content