Compartir a través de

Actualizar usuario

  • Artículo

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 de un objeto user.

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

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

Nota:

  • Para actualizar propiedades de usuario confidenciales, como accountEnabled, mobilePhone y otrosMails para usuarios con roles de administrador con privilegios:
    • En escenarios delegados, a la aplicación se le debe asignar el permiso delegado Directory.AccessAsUser.All y el usuario que realiza la llamada 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, a la aplicación se le debe asignar un rol de administrador con privilegios superiores, como se indica en Quién puede realizar acciones confidenciales.
  • Su cuenta personal de Microsoft debe estar asociada a un inquilino de Microsoft Entra para actualizar su perfil con el permiso delegado User.ReadWrite en una cuenta microsoft personal.
  • La actualización de la propiedad identities requiere el permiso User.ManageIdentities.All . Además, no se permite agregar una cuenta local B2C a un objeto user existente, a menos que el objeto user ya contenga una identidad de cuenta local.
  • Para actualizar la propiedad employeeLeaveDateTime :
    • En escenarios delegados, el administrador necesita el rol Administrador global ; Se deben conceder a la aplicación los permisos delegados User.Read.All y User-LifeCycleInfo.ReadWrite.All .
    • En escenarios de solo aplicación con permisos de Microsoft Graph, se deben conceder a la aplicación los permisos User.Read.All y User-LifeCycleInfo.ReadWrite.All .
  • 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 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 .

Solicitud HTTP

PATCH /users/{id | userPrincipalName}

Encabezados de solicitud

Encabezado Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la 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 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.

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

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. Un administrador de autenticación con privilegios asignado al permiso delegado Directory.AccessAsUser.All es el rol con privilegios mínimos que puede actualizar el estado accountEnabled de todos los administradores del inquilino.
ageGroup ageGroup Establece el grupo de edad del usuario. Valores permitidos: null, Minor, NotAdult y Adult. Consulte las definiciones de propiedades del grupo de edad legal para obtener más información.
assignedLicenses Colección assignedLicense Las licencias asignadas al usuario. No admite valores NULL.
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.
city Cadena La ciudad en la que se encuentra el usuario.
CompanyName String Nombre de la empresa a 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, Deniedy 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, 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 .
    		•
    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.
    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 Fecha y hora en que el usuario se fue 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 escenarios delegados, el usuario que realiza la llamada debe tener el rol De administrador global y la aplicación que realiza la llamada tiene asignados los permisos delegados User.Read.All y User-LifeCycleInfo.ReadWrite.All .
    employeeOrgData employeeOrgData Representa los datos de la organización (por ejemplo, la división y costCenter) asociados a un usuario.
    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 a toda la colección y debe proporcionar la identidad userPrincipalName signInType en la colección.
    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). En el caso de las cuentas de Azure AD B2C, esta propiedad solo se puede actualizar hasta 10 veces con direcciones SMTP únicas. Los cambios en esta propiedad también actualizan la colección proxyAddresses del usuario para incluir el valor como una dirección SMTP. 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.
    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 de extensión individuales 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 Microsoft Entra objeto de usuario. 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"].
    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 procedimiento recomendado, establezca siempre forceChangePasswordNextSignIntrueen . Esto no se puede usar para usuarios federados.
  • En el acceso delegado, la aplicación que realiza la llamada debe tener asignado el permiso delegado Directory.AccessAsUser.All en nombre del usuario que ha iniciado sesión.
  • En el acceso de solo aplicación, a la aplicación que realiza la llamada se le debe asignar el permiso de aplicación User.ReadWrite.All (con privilegios mínimos) o Directory.ReadWrite.All (privilegios superiores) y al menos el rol Administrador de usuariosMicrosoft 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). Es necesario para los usuarios a los que se asignarán licencias debido a un requisito legal para comprobar la disponibilidad de los servicios en los países. 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 la RFC 822 estándar de Internet. 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 énfasis. 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.

    Dado que el recurso de usuario admite extensiones, puede usar la PATCH operación para agregar, actualizar o eliminar sus propios datos específicos de la aplicación en propiedades personalizadas de una extensión en una instancia de usuario existente.

    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 propiedades siguientes, debe especificarlas en su propia solicitud PATCH, sin incluir las demás propiedades enumeradas en la tabla anterior: 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 de 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/beta/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/beta/users/{id}
Content-type: application/json

{
    "businessPhones": [
        "+1 425 555 0109"
    ],
    "officeLocation": "18/2111",
    "authorizationInfo": {
        "certificateUserIds": [
            "5432109876543210@mil"
        ]
    }
}

    Respuesta

    En el ejemplo siguiente se muestra la respuesta.

    HTTP/1.1 204 No Content

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

    En el ejemplo siguiente se muestra una solicitud que restablece la contraseña de otro usuario. Como procedimiento recomendado, establezca siempre forceChangePasswordNextSignIntrueen .

    • En el acceso delegado, la aplicación que realiza la llamada debe tener asignado el permiso delegado Directory.AccessAsUser.All en nombre del usuario que ha iniciado sesión.
    • En el acceso de solo aplicación, a la aplicación que realiza la llamada se le debe asignar el permiso de aplicación User.ReadWrite.All (con privilegios mínimos) o Directory.ReadWrite.All (privilegios superiores) y al menos el rol Administrador de usuariosMicrosoft Entra.

    Solicitud

    PATCH https://graph.microsoft.com/beta/users/{id}
Content-type: application/json

{
  "passwordProfile": {
    "forceChangePasswordNextSignIn": true,
    "password": "xWwvJ]6NMw+bWH-d"
  }
}

    Respuesta

    HTTP/1.1 204 No Content

    Ejemplo 4: Asignación de 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 personalizadas, vea 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/users/{id}
Content-type: application/json

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

    Respuesta

    HTTP/1.1 204 No Content

    Ejemplo 5: Agregar o actualizar 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/beta/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

    Contenido relacionado