Поделиться через


Обновление пользователя

Пространство имен: microsoft.graph

Обновление свойств объекта user.

  • Не все свойства могут быть обновлены пользователями-участниками или гостевыми пользователями с разрешениями по умолчанию без ролей администратора. Сравните разрешения по умолчанию для участника и гостя, чтобы узнать, какими свойствами они могут управлять.
  • Клиенты через Microsoft Entra ID для клиентов также могут использовать эту операцию API для обновления своих сведений. Список свойств, которые они могут обновить, см. в статье Разрешения пользователей по умолчанию в клиентах клиентов .
  • Для синхронизированных пользователей возможность обновления определенных свойств дополнительно определяется источником центра и включена ли синхронизация.

Этот API доступен в следующих национальных облачных развертываниях.

Глобальная служба Правительство США L4 Правительство США L5 (DOD) Китай управляется 21Vianet

Разрешения

Выберите разрешение или разрешения, помеченные как наименее привилегированные для этого API. Используйте более привилегированное разрешение или разрешения только в том случае, если это требуется приложению. Дополнительные сведения о делегированных разрешениях и разрешениях приложений см. в разделе Типы разрешений. Дополнительные сведения об этих разрешениях см. в справочнике по разрешениям.

Тип разрешения Разрешения с наименьшими привилегиями Более высокие привилегированные разрешения
Делегированные (рабочая или учебная учетная запись) User.ReadWrite User.ManageIdentities.All, User.EnableDisableAccount.All, User.ReadWrite.All, Directory.ReadWrite.All
Делегированные (личная учетная запись Майкрософт) User.ReadWrite Недоступно.
Приложение User.ManageIdentities.All User.EnableDisableAccount.All, User.ReadWrite.All, Directory.ReadWrite.All

Примечание.

  • Чтобы обновить конфиденциальные свойства пользователей, такие как accountEnabled, mobilePhone и другие сообщения Электронной почты для пользователей с привилегированными ролями администратора, выполните следующие действия:
  • Ваша личная учетная запись Майкрософт должна быть привязана к клиенту Microsoft Entra, чтобы обновить профиль с делегированным разрешением User.ReadWrite для личной учетной записи Майкрософт.
  • Для обновления свойства удостоверений требуется разрешение User.ManageIdentities.All . Кроме того, добавление локальной учетной записи B2C к существующему объекту пользователя не допускается, если только объект пользователя не содержит идентификатор локальной учетной записи.
  • Чтобы обновить свойство employeeLeaveDateTime, выполните следующие действия:
    • В делегированных сценариях администратору требуется роль глобального администратора ; приложению должны быть предоставлены делегированные разрешения User.Read.All и User-LifeCycleInfo.ReadWrite.All .
    • В сценариях только для приложений с разрешениями Microsoft Graph приложению должны быть предоставлены разрешения User.Read.All и User-LifeCycleInfo.ReadWrite.All .
  • Чтобы обновить свойство customSecurityAttributes , выполните следующие действия:
    • В делегированных сценариях администратору должна быть назначена роль администратора назначения атрибутов , а приложению — разрешение CustomSecAttributeAssignment.ReadWrite.All .
    • В сценариях только для приложений с разрешениями Microsoft Graph приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All .

HTTP-запрос

PATCH /users/{id | userPrincipalName}

Заголовки запросов

Заголовок Значение
Авторизация Bearer {token}. Обязательно. Дополнительные сведения о проверке подлинности и авторизации.
Content-Type application/json

Текст запроса

В тексте запроса укажите только значения свойств для обновления. Существующие свойства, которые не включены в текст запроса, сохраняют свои предыдущие значения или пересчитываются на основе изменений других значений свойств.

В следующей таблице указаны свойства, которые можно обновить.

Свойство Тип Описание
aboutMe String Свободное текстовое поле, где пользователь может рассказать о себе.
accountEnabled Логический Если учетная запись обеспечена — true, в противном случае — false. Это свойство обязательно указывать при создании пользователя. Администратор привилегированной проверки подлинности, которому назначено делегированное разрешение Directory.AccessAsUser.All , является наименее привилегированной ролью, которая может обновлять состояние accountEnabled всех администраторов в клиенте.
ageGroup ageGroup Устанавливает возрастную группу пользователя. Допустимые значения: null, Minor, NotAdultи Adult. Дополнительные сведения см. в разделе Определения свойств юридических возрастных групп.
birthday DateTimeOffset День рождения пользователя. Тип Timestamp представляет сведения о времени и дате с использованием формата ISO 8601 (всегда применяется формат UTC). Например, значение полуночи 1 января 2014 г. в формате UTC: 2014-01-01T00:00:00Z.
businessPhones Коллекция строк Номера телефонов пользователя. ПРИМЕЧАНИЕ. Несмотря на то что это коллекция строк, для этого свойства можно задать только один номер.
city String Город, в котором находится пользователь.
CompanyName String Имя компании, с которым связан пользователь. Это свойство может быть полезно для описания компании внешнего пользователя. Максимальная длина: 64 символа.
consentProvidedForMinor consentProvidedForMinor Устанавливает, получено ли согласие для несовершеннолетних. Допустимые значения: null, Granted, Denied и NotRequired. Дополнительные сведения см. в разделе Определения свойств юридических возрастных групп.
country String Страна или регион, в котором находится пользователь, например US или UK.
customSecurityAttributes customSecurityAttributeValue Открытый сложный тип, который содержит значение настраиваемого атрибута безопасности, назначенного объекту каталога.
  • Чтобы обновить это свойство в делегированных сценариях, вызывающему субъекту должна быть назначена роль администратора назначения атрибутов, а приложению предоставлено делегированное разрешение CustomSecAttributeAssignment.ReadWrite.All .
  • Чтобы обновить это свойство в сценариях только для приложений с разрешениями Microsoft Graph, приложению должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All .
  • department String Название отдела, в котором работает пользователь.
    displayName String Имя пользователя, отображаемое в адресной книге. Обычно это сочетание имени, отчества и фамилии пользователя. Это свойство является обязательным при создании пользователя и его невозможно очистить во время обновлений.
    employeeId String Идентификатор сотрудника, назначенный пользователю организацией. Максимальная длина составляет 16 символов.
    employeeType String Фиксирует тип корпоративного работника. Например, Employee, Contractor, Consultant или Vendor. Возвращается только с помощью оператора $select.
    givenName; String Простое имя пользователя.
    employeeHireDate DateTimeOffset Дата найма пользователя. Тип Timestamp представляет сведения о времени и дате с использованием формата ISO 8601 (всегда применяется формат UTC). Например, значение полуночи 1 января 2014 г. в формате UTC: 2014-01-01T00:00:00Z.
    employeeLeaveDateTime DateTimeOffset Дата и время, когда пользователь покинет организацию или покинет ее. Тип метки времени представляет сведения о дате и времени в формате ISO 8601 и всегда находится в формате UTC. Например, значение полуночи 1 января 2014 г. в формате UTC: 2014-01-01T00:00:00Z.

    В делегированных сценариях вызывающий пользователь должен иметь роль глобального администратора , а вызывающему приложению назначены делегированные разрешения User.Read.All и User-LifeCycleInfo.ReadWrite.All .
    employeeOrgData employeeOrgData Представляет данные организации (например, division и costCenter), связанные с пользователем.
    interests; Коллекция строк Список интересов пользователя.
    jobTitle String Должность пользователя.
    mail String SMTP-адрес пользователя, например jeff@contoso.com. Изменения этого свойства также обновят коллекцию proxyAddresses пользователя, чтобы включить значение в качестве SMTP-адреса. Для Azure AD учетных записей B2C это свойство можно обновить до 10 раз с помощью уникальных SMTP-адресов. Не удается обновить до null.
    mailNickname String Почтовый псевдоним для пользователя. Это свойство должно быть указано при создании пользователя.
    mobilePhone String Основной сотовый телефон пользователя.
    mySite String URL-адрес личного сайта пользователя.
    officeLocation String Расположение офиса на месте работы пользователя.
    onPremisesExtensionAttributes onPremisesExtensionAttributes Содержит свойства extensionAttribute 1–15 для пользователя. Отдельные атрибуты расширения не могут быть выбраны или фильтруемы. Для пользователей onPremisesSyncEnabled исходным центром управления для этого набора свойств является локальная среда, и он предназначен только для чтения. Эти атрибуты расширения также называются настраиваемыми атрибутами 1–15 Exchange.
    onPremisesImmutableId String Это свойство используется для связывания учетной записи пользователя локальная служба Active Directory с объектом Microsoft Entra пользователя. Это свойство должно быть указано при создании новой учетной записи пользователя в Graph, если вы используете федеративный домен для свойства userPrincipalName (UPN) пользователя. Важный: Символы $ и _ нельзя использовать при указании этого свойства.
    otherMails Коллекция строк Список дополнительных адресов электронной почты для пользователя. Например: ["bob@contoso.com", "Robert@fabrikam.com"].
    passwordPolicies String Задает политики паролей для пользователя. Это свойство представляет собой перечисление с возможным значением DisableStrongPassword. Оно позволяет использовать менее надежные пароли, чем предусмотрено политикой по умолчанию. Вы также можете указать значение DisablePasswordExpiration. Их можно указать вместе; например: DisablePasswordExpiration, DisableStrongPassword.
    passwordProfile PasswordProfile Задает профиль пароля для пользователя. Профиль содержит пароль пользователя. Пароль в профиле должен соответствовать минимальным требованиям, указанным в свойстве passwordPolicies. По умолчанию требуется надежный пароль. Рекомендуется всегда задавать для параметра forceChangePasswordNextSignIn значение true. Его нельзя использовать для федеративных пользователей.
  • При делегированном доступе вызывающему приложению должен быть назначено делегированное разрешение от имени вошедшего пользователя Directory.AccessAsUser.All.
  • При доступе только к приложению вызывающему приложению необходимо назначить разрешение приложения User.ReadWrite.All (минимальные привилегии) или Directory.ReadWrite.All (более высокие привилегии) и по крайней мере роль администратора пользователейMicrosoft Entra.
  • pastProjects Коллекция строк Список предыдущих проектов пользователя.
    postalCode String Почтовый индекс адреса пользователя. Формат почтового индекса зависит от страны или региона пользователя. В США для этого атрибута используется ZIP-код.
    preferredLanguage String Предпочитаемый язык для пользователя. Он должен быть представлен в формате ISO 639-1, например en-US.
    responsibilities; Коллекция строк Список обязанностей пользователя.
    schools Коллекция строк Список для пользователя для перечисления учебных заведений, которые они посещали.
    skills Коллекция строк Список навыков пользователя.
    state String Область, республика, край или округ в адресе пользователя.
    streetAddress String Почтовый адрес места работы пользователя.
    surname String Фамилия пользователя.
    usageLocation String Двухбуквенный код страны (по стандарту ISO 3166). Необходим для пользователей, которым будут назначены лицензии, в связи с законодательным требованием проверять доступность служб в разных странах. Примеры: US, JP и GB. Значение null не допускается.
    userPrincipalName String Имя участника-пользователя. Имя участника-пользователя — это имя для входа в интернет-стиле для пользователя, основанное на стандарте Интернета RFC 822. В соответствии с соглашением оно должно указывать на имя пользователя для электронной почты. Общий формат: псевдоним@домен. При этом домен должен входить в коллекцию проверенных доменов клиента. Доступ к проверенным доменам клиента можно получить с помощью свойства verifiedDomains объекта organization.
    ПРИМЕЧАНИЕ. Это свойство не может содержать знаки акцента. Разрешены только следующие символы: A - Z, a - z, 0 - 9, ' . - _ ! # ^ ~. Полный список разрешенных символов см. в политиках имен пользователей.
    userType String Строковое значение, с помощью которого можно классифицировать типы пользователей в каталоге, например Member и Guest.

    Примечание.

    • Следующие свойства не могут быть обновлены приложением только с разрешениями приложения: aboutMe, birthday, employeeHireDate, interests, mySite, pastProjects, responsibilities, schools, и skills.
    • Чтобы обновить следующие свойства, необходимо указать их в своем запросе PATCH, не включив другие свойства: aboutMe, день рождения, интересы, mySite, pastProjects, обязанности, учебные заведения и навыки.

    Управление расширениями и связанными данными

    Используйте этот API для управления каталогом, схемой и открытыми расширениями и их данными для пользователей следующим образом:

    • Добавление, обновление и хранение данных в расширениях для существующего пользователя
    • Для расширений каталогов и схем удалите все сохраненные данные, задав для свойства пользовательского расширения значение null. Для открытых расширений используйте API удаления открытых расширений.

    Отклик

    В случае успешного выполнения этот метод возвращает код отклика 204 No Content.

    Пример

    Пример 1. Обновление свойств вошедшего пользователя

    Запрос

    Ниже показан пример запроса.

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

    Отклик

    Ниже показан пример отклика.

    HTTP/1.1 204 No Content
    

    Пример 2. Обновление свойств указанного пользователя

    Запрос

    Ниже показан пример запроса.

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

    Отклик

    Ниже показан пример отклика.

    HTTP/1.1 204 No Content
    

    Пример 3. Обновление passwordProfile пользователя и сброс пароля

    В приведенном ниже примере показан запрос на сброс пароля другого пользователя. Рекомендуется всегда задавать для параметра forceChangePasswordNextSignIn значение true.

    • При делегированном доступе вызывающему приложению должен быть назначено делегированное разрешение от имени вошедшего пользователя Directory.AccessAsUser.All.
    • При доступе только к приложению вызывающему приложению необходимо назначить разрешение приложения User.ReadWrite.All (минимальные привилегии) или Directory.ReadWrite.All (более высокие привилегии) и по крайней мере роль администратора пользователейMicrosoft Entra.

    Запрос

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

    Отклик

    HTTP/1.1 204 No Content
    

    Пример 4. Добавление или обновление значений расширения схемы для пользователя

    Можно обновить или назначить значение одному свойству или всем свойствам в расширении.

    Запрос

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

    Чтобы удалить значение расширения схемы из объекта user, задайте для свойства ext55gb1l09_msLearnCourses значение null.

    Отклик

    HTTP/1.1 204 No Content
    

    Пример 5. Назначение пользовательского атрибута безопасности со строковым значением пользователю

    В следующем примере показано, как назначить пользователю настраиваемый атрибут безопасности со строковым значением.

    • Набор атрибутов: Engineering
    • Атрибут: ProjectDate
    • Тип данных атрибута: строка
    • Значение атрибута: "2022-10-01"

    Чтобы назначить настраиваемые атрибуты безопасности, вызывающему субъекту должна быть присвоена роль администратора назначения атрибутов и должно быть предоставлено разрешение CustomSecAttributeAssignment.ReadWrite.All.

    Примеры назначений настраиваемых атрибутов безопасности см. в разделе Примеры. Назначение, обновление, перечисление или удаление назначений настраиваемых атрибутов безопасности с помощью API Graph Майкрософт.

    Запрос

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

    Отклик

    HTTP/1.1 204 No Content