Actualizar usuario

Espacio de nombres: microsoft.graph

Actualice las propiedades de un objeto user. Para usar esta API para actualizar un agentUser, especifique una propiedad @odata.type con un valor de en el cuerpo de #microsoft.graph.agentUser la solicitud.

  • Los usuarios miembros o invitados no pueden actualizar todas las propiedades con sus permisos predeterminados sin roles de administrador. Compare los permisos predeterminados de miembro y para ver las propiedades que pueden administrar.
  • Id. externa de Microsoft Entra en inquilinos externos también puede usar esta operación de API para actualizar sus detalles. Consulte Permisos de usuario predeterminados en inquilinos externos para obtener la lista de propiedades que pueden actualizar.
  • Para los usuarios sincronizados, la capacidad de actualizar determinadas propiedades viene determinada adicionalmente por el origen de la autoridad y si la sincronización está habilitada.

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) User.ReadUpdate.All User.ReadWrite.All, Directory.ReadWrite.All
Delegado (cuenta personal de Microsoft) User.ReadWrite No disponible.
Aplicación User.ReadUpdate.All User.ReadWrite.All, Directory.ReadWrite.All

Permisos para escenarios específicos

  • User.ReadWrite es el permiso con privilegios mínimos para actualizar los detalles del usuario que ha iniciado sesión.
  • Su cuenta personal de Microsoft debe estar vinculada a un inquilino de Microsoft Entra para actualizar su perfil con el permiso delegado User.ReadWrite en una cuenta personal de Microsoft.
  • Para actualizar la propiedad employeeLeaveDateTime :
    • En escenarios delegados, el administrador necesita el rol de administrador global ; A la aplicación se le deben conceder los permisos delegados User.Read.All y User-LifeCycleInfo.ReadWrite.All .
    • En escenarios de solo aplicación con permisos de Microsoft Graph, se debe conceder a la aplicación los permisos User.Read.All y User-LifeCycleInfo.ReadWrite.All .
  • 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 CustomSecAttributeAssignment.ReadWrite.All .
    • En escenarios de solo aplicación con permisos de Microsoft Graph, se debe conceder a la aplicación el permiso CustomSecAttributeAssignment.ReadWrite.All .
  • User-Mail.ReadWrite.All es el permiso con privilegios mínimos para actualizar la propiedad otherMails .
  • User-PasswordProfile.ReadWrite.All es el permiso con privilegios mínimos para actualizar la propiedad passwordProfile .
  • User-Phone.ReadWrite.All es el permiso con privilegios mínimos para actualizar las propiedades businessPhones y mobilePhone .
  • User.EnableDisableAccount.All + User.Read.All es la combinación mínima de permisos para actualizar la propiedad accountEnabled .
  • User.ManageIdentities.All es necesario para actualizar la propiedad de identidades .

Solicitud HTTP

Actualice sus propias propiedades de usuario.

Nota:

Para llamar al punto de conexión /me, se requiere un usuario con la sesión iniciada y, por lo tanto, un permiso delegado. Los permisos de aplicación no se admiten al usar el /me punto de conexión.

PATCH /me

Actualizar las propiedades de otro usuario.

PATCH /users/{id | userPrincipalName}

Encabezados de solicitud

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

Cuerpo de la solicitud

En el cuerpo de la solicitud, proporcione solo los valores de las propiedades que se van a actualizar. 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.

En la tabla siguiente se especifican las propiedades que se pueden actualizar.

Para utilizar esta API para actualizar un agentUser, debe especificar el @odata.type como #microsoft.graph.agentUser en el cuerpo de la solicitud.

Propiedad Tipo Descripción
aboutMe String Un campo de entrada de texto de forma libre para que el usuario se describa a sí mismo.
accountEnabled Boolean true si la cuenta está habilitada; en caso contrario, false. Esta propiedad es necesaria cuando se crea un usuario.
  • User.EnableDisableAccount.All + User.Read.All es la combinación mínima de permisos necesarios para actualizar esta propiedad.
  • En escenarios delegados, el Administrador de autenticación con privilegios es el rol con privilegios mínimos que se permite para actualizar esta propiedad para todos los administradores del inquilino. En general, el usuario que ha iniciado sesión debe tener un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • En escenarios de solo aplicación, además de los permisos de Microsoft Graph, se debe asignar a la aplicación un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • ageGroup ageGroup Establece el grupo de edad del usuario. Valores permitidos: null, Minor, NotAdulty Adult. Consulte las definiciones de propiedades del grupo de edad legal para obtener más información.
    birthday DateTimeOffset El cumpleaños del usuario. El tipo de marca de tiempo representa la información de fecha y hora con el formato ISO 8601 y está siempre en hora UTC. Por ejemplo, la medianoche en la zona horaria UTC del 1 de enero de 2014 sería 2014-01-01T00:00:00Z.
    businessPhones Colección string Números de teléfono del usuario. NOTA: Aunque se trata de una colección de cadenas, solo se puede establecer un número para esta propiedad. User-Phone.ReadWrite.All es el permiso con privilegios mínimos para actualizar esta propiedad.
    city Cadena La ciudad en la que se encuentra el usuario.
    CompanyName String Nombre de la empresa con la que está asociado el usuario. Esta propiedad puede ser útil para describir la empresa de la que procede un usuario externo. La longitud máxima es de 64 caracteres.
    consentProvidedForMinor consentProvidedForMinor Determina si se ha obtenido el consentimiento para menores. Valores permitidos: null, Granted, Denied y NotRequired. Consulte las definiciones de propiedades del grupo de edad legal para obtener más información.
    country Cadena País o región en la que se encuentra el usuario; por ejemplo, "US" o "UK".
    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 .
  • department Cadena El nombre del departamento en el que trabaja el usuario.
    displayName Cadena Nombre del usuario que aparece en la libreta de direcciones. Suele ser la combinación del nombre del usuario, la inicial del segundo nombre y el apellido. Esta propiedad es necesaria cuando se crea un usuario y no se puede borrar durante las actualizaciones.
    employeeId Cadena El identificador de empleado asignado al usuario en la organización. La longitud máxima es de 16 caracteres.
    employeeType Cadena Es para capturar el tipo de trabajador de la empresa. Por ejemplo, Employee, Contractor, Consultant o Vendor. Solo se devuelve en $select.
    givenName Cadena El nombre (nombre de pila) del usuario.
    employeeHireDate DateTimeOffset La fecha de contratación del usuario. El tipo de marca de tiempo representa la información de fecha y hora con el formato ISO 8601 y está siempre en hora UTC. Por ejemplo, la medianoche en la zona horaria UTC del 1 de enero de 2014 sería 2014-01-01T00:00:00Z.
    employeeLeaveDateTime DateTimeOffset La fecha y hora en que el usuario abandonó o dejará la organización. El tipo de marca de tiempo representa la información de fecha y hora con el formato ISO 8601 y siempre está en hora UTC. Por ejemplo, la medianoche en la zona horaria UTC del 1 de enero de 2014 sería 2014-01-01T00:00:00Z.
  • Para actualizar esta propiedad, se deben asignar a la aplicación que realiza la llamada los permisos User-LifeCycleInfo.Read.All y User.Read.All .
  • Para actualizar esta propiedad en escenarios delegados, el administrador necesita el rol de administrador global.
  • employeeOrgData employeeOrgData Representa los datos de la organización (por ejemplo, división y costCenter) asociados a un usuario. Incluir ambos valores de propiedad al actualizar employeeOrgData; Si omite alguno, el sistema lo establece en null.
    identidades colección objectIdentity Representa las identidades que se pueden usar para iniciar sesión en esta cuenta de usuario. Puede recibir una identidad de Microsoft, de organizaciones o de proveedores de identidades sociales como Facebook, Google, y vincularla a la cuenta de usuario. Cualquier actualización de identidades reemplaza toda la colección y debe proporcionar la identidad userPrincipalName signInType en la colección.

    NOTA: No se permite agregar una cuenta local B2C a un objeto de usuario existente, a menos que el objeto de usuario ya contenga una identidad de cuenta local.
    interests Colección string Una lista para que el usuario describa sus intereses.
    jobTitle String Puesto del usuario.
    mail Cadena La dirección SMTP del usuario (por ejemplo, la dirección jeff@contoso.com). Los cambios en esta propiedad también actualizan la colección proxyAddresses del usuario para incluir el valor como una dirección SMTP. Para las cuentas de Azure AD B2C, esta propiedad se puede actualizar hasta solo 10 veces con direcciones SMTP únicas. No se puede actualizar a null.
    mailNickname Cadena El alias de correo del usuario. Esta propiedad debe especificarse al crear un usuario.
    mobilePhone String El número de teléfono móvil principal del usuario.
  • User-Phone.ReadWrite.All es el permiso con privilegios mínimos para actualizar esta propiedad.
  • En escenarios delegados, el Administrador de autenticación con privilegios es el rol con privilegios mínimos que se permite para actualizar esta propiedad para todos los administradores del inquilino. En general, el usuario que ha iniciado sesión debe tener un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • En escenarios de solo aplicación, además de los permisos de Microsoft Graph, se debe asignar a la aplicación un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • mySite String La dirección URL del sitio personal del usuario.
    officeLocation String La ubicación de la oficina del lugar de trabajo del usuario.
    onPremisesExtensionAttributes OnPremisesExtensionAttributes Contiene los extensionAttributes 1-15 para el usuario. Los atributos individuales de las extensiones no se pueden seleccionar ni filtrar. Para un usuario de onPremisesSyncEnabled, el origen de autoridad para este conjunto de propiedades es la implementación local y es de solo lectura. Estos atributos de extensión se conocen también como atributos personalizados de Exchange 1-15.
    onPremisesImmutableId Cadena Esta propiedad se usa para asociar una cuenta de usuario de Active Directory local a su objeto de usuario de Microsoft Entra. Esta propiedad debe especificarse al crear una nueva cuenta de usuario en Graph si usa un dominio federado para la propiedad userPrincipalName (UPN) del usuario. Importante: Los $ caracteres y _ no se pueden usar al especificar esta propiedad.
    otherMails Colección string Una lista de direcciones de correo electrónico adicionales para el usuario. Por ejemplo: ["bob@contoso.com", "Robert@fabrikam.com"]. Para actualizar esta propiedad, pase todas las direcciones de correo electrónico que desee que tenga el usuario; De lo contrario, los valores existentes se sobrescriben con los valores especificados. Puede almacenar hasta 250 valores, cada uno con un límite de 250 caracteres.

  • User-Mail.ReadWrite.All es el permiso con privilegios mínimos para actualizar esta propiedad.
  • En escenarios delegados, el Administrador de autenticación con privilegios es el rol con privilegios mínimos que se permite para actualizar esta propiedad para todos los administradores del inquilino. En general, el usuario que ha iniciado sesión debe tener un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • En escenarios de solo aplicación, además de los permisos de Microsoft Graph, se debe asignar a la aplicación un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • passwordPolicies String Especifica las directivas de contraseña del usuario. Este valor es una enumeración con un valor posible que es DisableStrongPassword, el cual permite especificar contraseñas menos seguras que la directiva predeterminada. DisablePasswordExpiration también se puede especificar. Los dos se pueden especificar juntos; Por ejemplo: DisablePasswordExpiration, DisableStrongPassword.
    passwordProfile passwordProfile Especifica el perfil de contraseña del usuario. El perfil contiene la contraseña del usuario. La contraseña del perfil debe cumplir los requisitos mínimos especificados por la propiedad passwordPolicies. De manera predeterminada, se requiere una contraseña segura. Como práctica recomendada, establezca siempre forceChangePasswordNextSignIn en true. Esto no se puede usar para usuarios federados.
  • User-PasswordProfile.ReadWrite.All es el permiso con privilegios mínimos para actualizar esta propiedad.
  • En escenarios delegados, el rol Microsoft Entra administrador deusuarios es el rol de administrador con privilegios mínimos admitido para actualizar esta propiedad para los usuarios que no son administradores. El Administrador de autenticación con privilegios es el rol con privilegios mínimos que se permite para actualizar esta propiedad para todos los administradores del inquilino. En general, el usuario que ha iniciado sesión debe tener un rol de administrador con privilegios superiores, como se indica en Quién puede restablecer contraseñas.
  • En escenarios de solo aplicación, se debe asignar a la aplicación que realiza la llamada un permiso compatible y, como mínimo, el rol Administrador de usuarios:Microsoft Entra.
  • pastProjects Colección string Una lista para que el usuario enumere sus últimos proyectos.
    postalCode String El código postal de la dirección del usuario. El código postal es específico del país o de la región del usuario. En Estados Unidos, este atributo contiene el código postal.
    preferredLanguage String Idioma preferido del usuario. Debe seguir el código ISO 639-1; por ejemplo, en-US.
    responsibilities Colección string Una lista para que el usuario enumere sus responsabilidades.
    schools Colección string Una lista para que el usuario enumere las escuelas a las que asistió.
    skills Colección string Una lista para que el usuario enumere sus aptitudes.
    state Cadena El estado o la provincia de la dirección del usuario.
    streetAddress String La dirección postal del lugar de trabajo del usuario.
    surname Cadena El apellido (o apellidos) del usuario.
    usageLocation Cadena Un código de país de dos letras (norma ISO 3166). Necesario para los usuarios a los que se asignarán licencias debido a un requisito legal para comprobar la disponibilidad de los servicios en países o regiones. Algunos ejemplos son: USJP y GB. No admite valores NULL.
    userPrincipalName Cadena El nombre principal del usuario (UPN) del usuario. El UPN es un nombre de inicio de sesión de estilo Internet para el usuario basado en el estándar de Internet RFC 822. Por convención, se debe asignar al nombre de correo electrónico del usuario. El formato general es alias@dominio, en donde el dominio debe estar presente en la colección de dominios verificados del espacio empresarial. Se puede acceder a los dominios verificados del inquilino desde la propiedad verifiedDomains en organización.
    NOTA: Esta propiedad no puede contener caracteres de acento. Los caracteres siguientes no están permitidos A - Z, a - z, 0 - 9, ' . - _ ! # ^ ~. Para obtener la lista completa de caracteres permitidos, vea directivas de nombre de usuario.
    userType Cadena Un valor de cadena puede utilizarse para clasificar los tipos de usuario en el directorio. Por ejemplo: Member e Guest.

    Nota:

    • Las siguientes propiedades no se pueden actualizar con una app con solo permisos de aplicación: aboutMe, birthday, employeeHireDate, interests, mySite, pastProjects, responsibilities, schools y skills.
    • Para actualizar las siguientes propiedades, debe especificarlas en su propia solicitud PATCH, sin incluir las otras propiedades: aboutMe, birthday, interests, mySite, pastProjects, responsibilities, schools y skills.

    Administración de extensiones y datos asociados

    Use esta API para administrar el directorio, el esquema y las extensiones abiertas y sus datos para los usuarios como se indica a continuación:

    • Agregar, actualizar y almacenar datos en las extensiones para un usuario existente
    • Para las extensiones de directorio y esquema, quite los datos almacenados estableciendo el valor de la propiedad de extensión personalizada en null. Para las extensiones abiertas, use la API Eliminar extensión abierta.

    Respuesta

    Si se ejecuta correctamente, este método devuelve un código de respuesta 204 No Content.

    Ejemplo

    Ejemplo 1: actualice las propiedades del usuario con la sesión iniciada

    Solicitud

    En el ejemplo siguiente se muestra la solicitud.

    PATCH https://graph.microsoft.com/v1.0/me
    Content-type: application/json
    
    {
      "businessPhones": [
        "+1 425 555 0109"
      ],
      "officeLocation": "18/2111"
    }
    

    Respuesta

    En el ejemplo siguiente se muestra la respuesta.

    HTTP/1.1 204 No Content
    

    Ejemplo 2: actualice las propiedades del usuario con la sesión iniciada

    Solicitud

    En el ejemplo siguiente se muestra la solicitud.

    PATCH https://graph.microsoft.com/v1.0/users/{id}
    Content-type: application/json
    
    {
      "businessPhones": [
        "+1 425 555 0109"
      ],
      "officeLocation": "18/2111"
    }
    

    Respuesta

    En el ejemplo siguiente se muestra la respuesta.

    HTTP/1.1 204 No Content
    

    Ejemplo 3: Actualizar el perfil de contraseña de un usuario y restablecer su contraseña

    En el ejemplo siguiente, se muestra una solicitud para restablecer la contraseña de otro usuario. Como práctica recomendada, establezca siempre forceChangePasswordNextSignIn en true.

    • User-PasswordProfile.ReadWrite.All es el permiso con privilegios mínimos para actualizar la propiedad passwordProfile .
    • En escenarios delegados, se debe asignar un permiso compatible a la aplicación que llama y el usuario que ha iniciado sesión debe asignarse el rol compatible de Microsoft Entra.
      • El Administrador de autenticación con privilegios es el rol con privilegios mínimos que se permite para actualizar esta propiedad para todos los administradores del inquilino.
      • En general, el usuario que ha iniciado sesión debe tener un rol de administrador con privilegios superiores, como se indica en Quién puede restablecer contraseñas.
    • En escenarios de solo aplicación que usan permisos de aplicación de Microsoft Graph, User-PasswordProfile.ReadWrite.All es el permiso con privilegios mínimos.

    Solicitud

    PATCH https://graph.microsoft.com/v1.0/users/{id}
    Content-type: application/json
    
    {
      "passwordProfile": {
        "forceChangePasswordNextSignIn": false,
        "password": "xWwvJ]6NMw+bWH-d"
      }
    }
    

    Respuesta

    HTTP/1.1 204 No Content
    

    Ejemplo 4: agregue o actualice los valores de una extensión de esquema para un usuario

    Puede actualizar o asignar un valor a una propiedad única o a todas las propiedades de la extensión.

    Solicitud

    PATCH https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e
    Content-type: application/json
    
    {
        "ext55gb1l09_msLearnCourses": {
            "courseType": "Admin"
        }
    }
    

    Para quitar el valor de la extensión de esquema del objeto de usuario, establezca la propiedad ext55gb1l09_msLearnCourses en null.

    Respuesta

    HTTP/1.1 204 No Content
    

    Ejemplo 5: Asignar un atributo de seguridad personalizado con un valor de cadena a un usuario

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

    • 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 ejemplos de asignaciones de atributos de seguridad personalizados, vea Ejemplos: asignar, actualizar, enumerar o quitar asignaciones de atributos de seguridad personalizados mediante la API de Microsoft Graph API.

    Solicitud

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

    Respuesta

    HTTP/1.1 204 No Content