ユーザーを更新する

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

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
委任 (個人用 Microsoft アカウント) User.ReadWrite 注意事項なし。
アプリケーション User.ManageIdentities.All User.EnableDisableAccount.All、User.ReadWrite.All、Directory.ReadWrite.All

注:

  • accountEnabled、mobilePhone、otherMails などの機密性の高いユーザー プロパティを更新するには、特権管理者ロールを持つユーザーに対して次の手順を実行します。
    • 委任されたシナリオでは、アプリに Directory.AccessAsUser.All 委任されたアクセス許可を割り当てる必要があり、呼び出し元のユーザーには、機密性の高い アクションを実行できるユーザーに示されているように、より高い特権管理者ロールが必要です。
    • アプリのみのシナリオでは、「機密性の高い アクションを実行できるユーザー」に示されているように、アプリに高い特権管理者ロールを割り当てる必要があります。
  • 個人用 Microsoft アカウントに対する User.ReadWrite 委任されたアクセス許可を使用してプロファイルを更新するには、個人用 Microsoft アカウントをMicrosoft Entra テナントに関連付ける必要があります。
  • ID プロパティを更新するには、User.ManageIdentities.All アクセス許可が必要です。 また、B2C ローカル アカウントを既存の user オブジェクトに追加することは、その user オブジェクトにローカル アカウント ID が既に含まれている場合を除き、許可されていません。

HTTP 要求

PATCH /users/{id | userPrincipalName}

要求ヘッダー

ヘッダー 値
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
Content-Type application/json

要求本文

要求本文で、更新すべきプロパティの値のみを指定します。 要求本文に含まれていない既存のプロパティは、以前の値を維持するか、他のプロパティ値の変更に基づいて再計算されます。

次の表に、更新できるプロパティを示します。

プロパティ 型 説明
aboutMe String ユーザーが自分自身について記述する、フリー フォームのテキスト入力フィールド。
accountEnabled Boolean アカウントが有効な場合は true であり、それ以外の場合は false です。 このプロパティは、ユーザーの作成時に必要です。 Directory. AccessAsUser. All委任されたアクセス許可を割り当てられたグローバル管理者は、テナント内のすべての管理者のaccountEnabled状態を更新できます。
ageGroup ageGroup ユーザーの年齢グループを設定します。 使用できる値: null、Minor、NotAdult、および Adult。 詳細については、「法的年齢グループ プロパティの定義」を参照してください。
assignedLicenses assignedLicense コレクション ユーザーに割り当てられているライセンス。 null 許容ではありません。
birthday DateTimeOffset ユーザーの誕生日。 Timestamp 型は、ISO 8601 形式を使用して日付と時刻の情報を表し、常に UTC 時間です。 たとえば、2014 年 1 月 1 日午前 0 時 (UTC) は、2014-01-01T00:00:00Z です。
businessPhones String collection ユーザーの電話番号。 メモ： これは文字列コレクションですが、このプロパティに設定できる数値は 1 つだけです。
city String ユーザーがいる都市。
CompanyName String ユーザーが関連付けられている会社の名前。 このプロパティは、外部ユーザーが所属する会社を記述するのに役立ちます。 最大の長さは 64 文字です。
consentProvidedForMinor consentProvidedForMinor 未成年者について同意を得ているかどうかを設定します。 使用できる値: null、Granted、Denied、および NotRequired。 詳細については、「法的年齢グループ プロパティの定義」を参照してください。
country String ユーザーがいる国/地域。たとえば、US や UK です。
customSecurityAttributes customSecurityAttributeValue ディレクトリ オブジェクトに割り当てられたカスタム セキュリティ属性の値を保持するオープン複合型。

このプロパティを更新するには、呼び出し元のプリンシパルに属性割り当て管理者の役割を割り当て、CustomSecAttributeAssignment.ReadWrite.All 権限を付与する必要があります。
department String ユーザーが働いている部門の名前。
displayName String アドレス帳に表示されるユーザーの名前。 これは通常、ユーザーの名前、ミドルネームのイニシャル、姓の組み合わせになります。 このプロパティは、ユーザーが作成され、更新中にクリアできない場合に必要です。
employeeId String 組織によりユーザーに割り当てられた従業員 ID。 最大の長さは 16 文字です。
employeeType String エンタープライズ ワーカーの種類を取得します。 たとえば、Employee、Contractor、Consultant、または Vendor です。
givenName String ユーザーの名。
employeeHireDate DateTimeOffset ユーザーの採用日付。 Timestamp 型は、ISO 8601 形式を使用して日付と時刻の情報を表し、常に UTC 時間です。 たとえば、2014 年 1 月 1 日午前 0 時 (UTC) は、2014-01-01T00:00:00Z です。
employeeLeaveDateTime DateTimeOffset ユーザーが退職した日時または退職する予定の日時。 タイムスタンプの種類は、ISO 8601 形式を使用して日付と時刻の情報を表し、常に UTC 時刻です。 たとえば、2014 年 1 月 1 日午前 0 時 (UTC) は、2014-01-01T00:00:00Z です。

委任されたシナリオの場合、呼び出し元のユーザーはグローバル管理者ロールを持ち、呼び出し元アプリに User.Read.All と User-LifeCycleInfo.ReadWrite.All 委任されたアクセス許可が割り当てられている必要があります。
employeeOrgData employeeOrgData ユーザーに関連付けられた組織データ (部署や costCenter など) を表します。
identities objectIdentity コレクション このユーザー アカウントへのサインインに使用できる ID を表します。 ID は、Microsoft、組織、または Facebook、Google、Microsoft などのソーシャル ID プロバイダーによって提供され、ユーザー アカウントに関連付けられます。 ID を更新するとコレクション全体が置き換えられ、コレクション内で userPrincipalName signInType ID を指定する必要があります。
interests String collection ユーザーが自分の関心事を記述する一覧。
jobTitle String ユーザーの役職。
mail String ユーザーの SMTP アドレス (たとえば、jeff@contoso.com)。 Azure AD B2C アカウントの場合、このプロパティは、一意の SMTP アドレスを使用して最大 10 回まで更新できます。 このプロパティを変更すると、ユーザーの proxyAddresses コレクションも更新され、値が SMTP アドレスとして含まれます。 に null更新できません。
mailNickname String ユーザーの電子メール エイリアス。 ユーザーの作成時に、このプロパティを指定する必要があります。
mobilePhone String ユーザーの主な携帯電話の番号。
mySite String ユーザーの個人用サイトの URL。
officeLocation String ユーザーの勤務先の場所。
onPremisesExtensionAttributes onPremisesExtensionAttributes ユーザーの extensionAttribute 1 ～ 15 が含まれています。 個々の拡張属性は、選択またはフィルター処理できません。 onPremisesSyncEnabled ユーザーの場合、このプロパティ セットの権限ソースはオンプレミスで、読み取り専用です。 これらの拡張属性は、Exchange カスタム属性 1-15 とも呼ばれます。
onPremisesImmutableId String このプロパティは、オンプレミスの Active Directory ユーザー アカウントを Microsoft Entra ユーザー オブジェクトに関連付けるために使用されます。 ユーザーの userPrincipalName (UPN) プロパティにフェデレーション ドメインを使用する場合は、Graph で新しいユーザー アカウントを作成する際にこのプロパティを指定する必要があります。 大事な：$および _ 文字は、このプロパティを指定するときに使用できません。
otherMails String collection ユーザーの追加のメール アドレスの一覧 (例: ["bob@contoso.com", "Robert@fabrikam.com"])。
passwordPolicies String ユーザーのパスワード ポリシーを指定します。 この値は列挙値であり、可能な 1 つの値は DisableStrongPassword です。この場合は、既定のポリシーより弱いパスワードを指定できます。 DisablePasswordExpiration を指定することもできます。 2 つを一緒に指定できます。例: DisablePasswordExpiration, DisableStrongPassword。
passwordProfile PasswordProfile ユーザーのパスワード プロファイルを指定します。 プロファイルには、ユーザーのパスワードが含まれています。 プロファイルにあるパスワードは、passwordPolicies プロパティによって指定されている最小要件を満たす必要があります。 既定では、強力なパスワードが必要です。 ベスト プラクティスとして、常に forceChangePasswordNextSignIn を に設定します true。 これは、フェデレーション ユーザーには使用できません。

委任されたアクセスでは、呼び出し元のアプリに、サインインしているユーザーに代わって Directory.AccessAsUser.All 委任されたアクセス許可を割り当てる必要があります。 アプリケーションのみのアクセスでは、呼び出し元のアプリに User.ReadWrite.All アプリケーションアクセス許可と少なくともユーザー管理者Microsoft Entraロールを割り当てる必要があります。
pastProjects String collection ユーザーが過去のプロジェクトを列挙する一覧。
postalCode String ユーザーの住所の郵便番号。 郵便番号は、ユーザーの国/地域に固有です。 アメリカ合衆国では、この属性には、ZIP コードが含まれます。
preferredLanguage String ユーザーが設定する言語。 ISO 639-1 コードに従う必要があります (例: en-US)。
responsibilities String collection ユーザーが自分の責任の範囲を列挙する一覧。
schools String collection ユーザーが出席した学校を列挙するためのリスト。
skills String collection ユーザーが自分のスキルを列挙する一覧。
state String ユーザーの住所の都道府県。
streetAddress String ユーザーの勤務先の番地。
surname String ユーザーの姓。
usageLocation String 2 文字の国コード (ISO 規格 3166) 国におけるサービスの利用可能性を確認することが法的に義務付けられているため、ライセンスを割り当てられるユーザーには必須です。 たとえば、US、JP、GB などがあります。 null 許容ではありません。
userPrincipalName String ユーザーのユーザー プリンシパル名 (UPN)。 UPN は、インターネット標準 RFC 822 に基づいた、インターネット スタイルのユーザーのサインイン名です。 規則では、これはユーザーの電子メール名にマップされる必要があります。 一般的な形式は alias@domain です。このドメインは、検証済みドメインのテナントのコレクション内に存在している必要があります。 テナントの検証済みドメインには、organization の verifiedDomains プロパティからアクセスできます。
このプロパティにアクセント文字を含めることはできません。 次の文字のみ使用することができます A - Z、a - z、0 - 9、 ' . - _ ! # ^ ~。 許可される文字の完全なリストについては、ユーザー名ポリシーを参照してください。
userType String ディレクトリ内のユーザーの種類を分類するために使用する文字列値 (Member、Guest など)。

ユーザー リソースは拡張機能をサポートしているため、この操作を使用して、既存のPATCHユーザー インスタンスの拡張機能のカスタム プロパティで独自のアプリ固有のデータを追加、更新、または削除できます。

注:

  • 以下のプロパティは、アプリケーションのアクセス許可のみを持つアプリで更新することはできません: aboutMe、birthday、employeeHireDate、interests、mySite、pastProjects、responsibilities、schools、and skills。
  • 以下のプロパティを更新するには、上記の表にリストされている他のプロパティを含めずに、独自の PATCH 要求でそれらを指定する必要があります: aboutMe、birthday、interests、mySite、pastProjects、responsibilities、schools、and skills。

拡張機能と関連データを管理する

次のように、この API を使用して、ディレクトリ、スキーマ、およびユーザーのオープン拡張機能とそのデータを管理します。

  • 既存のユーザーの拡張機能にデータを追加、更新、格納する
  • ディレクトリおよびスキーマ拡張機能の場合は、カスタム拡張プロパティの値を null に設定して、格納されているデータをすべて削除します。 オープン拡張機能の場合は、［オープン拡張機能を削除する］ API を使用します。

応答

成功した場合、このメソッドは 204 No Content 応答コードを返します。

例

例 1: サインインしているユーザーのプロパティを更新する

要求

次の例は要求を示しています。

PATCH https://graph.microsoft.com/beta/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/beta/users/{id}
Content-type: application/json

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

応答

次の例は応答を示しています。

HTTP/1.1 204 No Content

例 3: ユーザーの passwordProfile を更新し、パスワードをリセットする

次の例は、別のユーザーのパスワードをリセットする要求を示しています。 ベスト プラクティスとして、常に forceChangePasswordNextSignIn を に設定します true。

要求

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

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

応答

HTTP/1.1 204 No Content

例 4: 文字列値を持つカスタム セキュリティ属性をユーザーに割り当てる

次の例では、文字列値を持つカスタム セキュリティ属性をユーザーに割り当てる方法を示します。

  • 属性セット: Engineering
  • 属性: ProjectDate
  • 属性データ型: 文字列
  • 属性値: "2022-10-01"

カスタム セキュリティ属性を割り当てるには、呼び出し元のプリンシパルに属性割り当て管理者の役割を割り当て、CustomSecAttributeAssignment.ReadWrite.All 権限を付与する必要があります。

カスタム セキュリティ属性の割り当ての例については、「例: Microsoft Graph APIを使用してカスタム セキュリティ属性の割り当てを割り当て、更新、一覧表示、または削除する」を参照してください。

要求

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

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

応答

HTTP/1.1 204 No Content

例 5: ユーザーのスキーマ拡張機能の値を追加または更新する

拡張機能の単一のプロパティまたはすべてのプロパティに値を更新または割り当てることができます。

要求

PATCH https://graph.microsoft.com/beta/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e
Content-type: application/json

{
    "ext55gb1l09_msLearnCourses": {
        "courseType": "Admin"
    }
}

ユーザー オブジェクトからスキーマ拡張機能の値を削除するには、 ext55gb1l09_msLearnCourses プロパティを に null設定します。

応答

HTTP/1.1 204 No Content

関連コンテンツ