Microsoft Graph でのユーザーの操作

重要

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

Microsoft Graph では、ユーザーと、グループ、メール、予定表、ファイル、管理者ロールなどの他のオブジェクトとの関係に基づいてアプリ エクスペリエンスを構築できます。 一般的な API 操作、承認モデル、権限、機密性の高いアクション処理を通じて、ユーザー データにアクセスして管理できます。

ユーザーへのアクセス

Microsoft Graph を使用してユーザーにアクセスするには、次の 2 つの方法があります。

  • ID または userPrincipalName: /users/{id} または /users/{userPrincipalName}
  • /users/{signed-in user's id} と同じである、サインインしているユーザーの /me エイリアス使用して

一般的な API 操作

Microsoft Graph では、ユーザーは ユーザー リソースの種類によって表されます。 次の表に、ユーザーに対して実行できる一般的な操作を示します。

パス 説明
/me サインインしているユーザーの詳細情報を取得します。
/users 組織内のユーザーを一覧表示します。
/users/{id} ID で特定のユーザーを取得します。
/users/{id}/photo/$value ユーザーのプロフィール写真を取得します。
/users/{id}/manager ユーザーの上司を取得します。
/users/{id}/messages プライマリ受信トレイ内のユーザーの電子メール メッセージを一覧表示します。
/users/{id}/events ユーザーの予定表の今後のイベントを一覧表示します。
/users/{id}/drive ユーザーの OneDrive ファイル ストアを取得します。
/users/{id}/memberOf ユーザーがメンバーであるグループを一覧表示します。
/users/{id}/joinedTeams ユーザーがメンバーである Microsoft Teams を一覧表示します。
POST /invitations 企業間 (B2B) コラボレーションの一環としてゲストを招待する Microsoft Entra 外部 ID

承認と権限

Microsoft Graph では、ユーザー操作を管理するための 委任されたアクセス許可とアプリケーション アクセス許可 がサポートされています。 これらの権限を理解することは、安全で効率的なアプリケーション開発にとって非常に重要です。

一部のユーザー操作は、サインインしたユーザーが自分の詳細情報に対して実行できます。 このような操作の場合、ユーザーは自分の詳細にアクセスするためのアクセス許可をアプリに Microsoft Graph に付与できます。 User.ReadBasic.All、User.Read、および User.ReadWrite のアクセス許可がそのようなアクセス許可です。

他のユーザーの詳細の管理など、その他の操作には、承認された管理者のみが同意できる Microsoft Graph アクセス許可と Microsoft Entra ロールを介して付与された管理者特権が必要です。 さらに、一部の操作は機密性が高いと見なされ、限られた管理者のみが実行できます。 詳細については、「 パスワードをリセットできるユーザー」 および「 機密性の高い属性を更新できるユーザー 」セクションを参照してください。

Microsoft Entra ID の既定のユーザー アクセス許可

Microsoft Entra ID には、メンバーとゲストの 2 種類のユーザーがあります。 メンバーはテナントにネイティブに作成されます。 ゲストは招待状を使用してテナントに参加し、企業間 (B2B) コラボレーション ゲストとしてテナントにアクセスします。

Microsoft Entra ID のユーザーには、特定の操作を実行できる既定のアクセス許可があります。 この既定のアクセス許可のセットは、ユーザーがメンバー ユーザーかゲスト ユーザーかによって異なり、テナント管理者はこれらの既定のアクセス許可の設定を変更できます。 メンバー ユーザーとゲスト ユーザーが実行できる操作の詳細については、「Microsoft Entra ID の既定のユーザー アクセス許可とは」を参照してください。

外部テナントでの既定のユーザー アクセス許可

外部テナントの Microsoft Entra ID には、顧客向けの既定のアクセス許可もあります。 次の表は、お客様が自分のプロファイルを管理するために使用できる API 操作を示しています。

ユーザー ID または userPrincipalName は常に、サインインしているユーザーのものです。

ユーザー操作 API 操作 必要なアクセス許可
プロファイルの読み取り GET /me または GET /users/{id or userPrincipalName} User.Read
プロファイルの更新 PATCH /me または PATCH /users/{id or userPrincipalName}

次のプロパティは更新可能です: city、country、displayName、givenName、jobTitle、postalCode、state、streetAddress、surname、preferredLanguage		 User.ReadWrite
パスワードの変更 POST /me/changePassword Directory.AccessAsUser.All

ユーザーの基本プロファイル プロパティ

User.ReadBasic.All アクセス許可は、他のユーザーの職場または学校アカウントの制限されたプロパティ セットの読み取りにアプリのアクセスを制限します。 この基本プロファイルには、以下のプロパティのみが含まれています。

  • displayName
  • givenName
  • id
  • mail
  • photo
  • securityIdentifier
  • surname
  • userPrincipalName

さらに、次のシナリオ固有のアクセス許可を使用すると、アプリは、主に識別子関連のプロパティを含む基本的なユーザー プロファイルを読み取ることもできます。

  • User-Mail.ReadWrite.All
  • User-PasswordProfile.ReadWrite.All
  • User-Phone.ReadWrite.All
  • User-LifeCycleInfo.Read.All
  • User-LifeCycleInfo.ReadWrite.All

機密性の高いアクション

ユーザー オブジェクトに対する次のアクションは機密性が高いと見なされ、特定の管理者だけにロック ダウンされる場合があります。 すべてのユーザーが機密性の高いプロパティを読み取ることができます。

デリケートなアクション 機密プロパティ名
ユーザーを無効または有効にする accountEnabled
ビジネス電話を更新する businessPhones
携帯電話の更新 mobilePhone
オンプレミスの不変 ID を更新する onPremisesImmutableId
その他のメールを更新する otherMails
パスワード プロファイルの更新 passwordProfile
ユーザー プリンシパル名を更新する userPrincipalName
ユーザーを削除または復元する 該当なし

機密性の高いアクションを実行できるユーザー

次の表の列には、機密性の高いアクションを実行できるロールが示されています。 行には、機密性の高いアクションを実行できるロールが一覧表示されます。

次の表は、テナントのスコープで割り当てられたロールを表しています。 管理単位の範囲で割り当てられたロールには、 さらに制限が適用されます。

重要なアクションを実行できる役割 認証管理 ユーザー管理 特権認証管理 グローバル管理者
認証管理 ✅   ✅ ✅
ディレクトリ閲覧者 ✅ ✅ ✅ ✅
グローバル管理者     ✅ ✅
グループ管理   ✅ ✅ ✅
ゲスト招待元 ✅ ✅ ✅ ✅
ヘルプデスク管理   ✅ ✅ ✅
メッセージ センター閲覧者 ✅ ✅ ✅ ✅
パスワード管理 ✅ ✅ ✅ ✅
特権認証管理     ✅ ✅
特権ロール管理     ✅ ✅
レポート閲覧者 ✅ ✅ ✅ ✅
User
(管理者ロールなし)		 ✅ ✅ ✅ ✅
User
(管理者ロールはないがロール割り当て可能なグループのメンバーまたは所有者)		     ✅ ✅
制限された管理管理単位を対象とするロールを持つユーザー     ✅ ✅
ユーザー管理   ✅ ✅ ✅
使用状況の概要レポート閲覧者 ✅ ✅ ✅ ✅
すべてのカスタム ロール ✅ ✅

パスワードをリセットできるユーザー

次の表の列は、パスワードをリセットして更新トークンを無効にできる役割の一覧です。 行には、ユーザーのパスワードをリセットできる役割が一覧表示されます。 たとえば、パスワード管理者は、ディレクトリ閲覧者、ゲスト招待者、パスワード管理者、および管理者ロールを持たないユーザーのパスワードをリセットできます。 ユーザーに他の役割が割り当てられている場合、パスワード管理者はパスワードをリセットできません。

次の表は、テナントのスコープで割り当てられたロールを表しています。 管理単位の範囲で割り当てられたロールには、 さらに制限が適用されます。

パスワードをリセットできるロール パスワード管理 ヘルプデスク管理 認証管理 ユーザー管理 特権認証管理 グローバル管理者
認証管理     ✅   ✅ ✅
ディレクトリ閲覧者 ✅ ✅ ✅ ✅ ✅ ✅
グローバル管理者         ✅ ✅*
グループ管理       ✅ ✅ ✅
ゲスト招待元 ✅ ✅ ✅ ✅ ✅ ✅
ヘルプデスク管理   ✅   ✅ ✅ ✅
メッセージ センター閲覧者   ✅ ✅ ✅ ✅ ✅
パスワード管理 ✅ ✅ ✅ ✅ ✅ ✅
特権認証管理         ✅ ✅
特権ロール管理         ✅ ✅
レポート閲覧者   ✅ ✅ ✅ ✅ ✅
User
(管理者ロールなし)		 ✅ ✅ ✅ ✅ ✅ ✅
User
(管理者ロールはないがロール割り当て可能なグループのメンバーまたは所有者)		         ✅ ✅
制限された管理管理単位を対象とするロールを持つユーザー         ✅ ✅
ユーザー管理       ✅ ✅ ✅
使用状況の概要レポート閲覧者   ✅ ✅ ✅ ✅ ✅
すべてのカスタム ロール ✅ ✅

パスワードをリセットする機能には、 セルフサービス パスワード リセットに必要な次の機密性の高いプロパティの更新が含まれます。

  • businessPhones
  • mobilePhone
  • otherMails

共通プロパティ

✅ v1.0 にのみ適用されます。

v1.0 でユーザーを取得するとき、またはユーザーを一覧表示するときに返される既定のプロパティ セットを次に示します。 これらは、v1.0 で使用可能なすべてのプロパティのサブセットです。 より多くのユーザー プロパティを取得するには、$select クエリ パラメーターを使用します。 「$select queryパラメーターの使用方法」を学び、「$select queryパラメーターをサポートするプロパティ」を確認してください。

すべてのプロパティの詳細と一覧については、 ユーザー オブジェクトを参照してください。

プロパティ 説明
id ユーザーの一意の識別子。
businessPhones ユーザーの電話番号。
displayName アドレス帳に表示されるユーザーの名前。
givenName ユーザーの名。
jobTitle ユーザーの役職。
mail ユーザーの電子メール アドレス。
mobilePhone ユーザーの携帯電話番号。
officeLocation ユーザーの物理的なオフィスの場所。
preferredLanguage ユーザーの選択言語。
surname ユーザーの姓。
userPrincipalName ユーザーのプリンシパル名。

詳細と全プロパティの一覧は、ユーザー オブジェクトを参照してください。

ゲストのユーザーとグループの検索制限

ユーザーとグループの検索機能を使用すると、/users または /groups リソース セットに対するクエリ (例: https://graph.microsoft.com/v1.0/users) を実行して、アプリで組織のディレクトリ内のユーザーまたはグループを検索できるようになります 管理者とメンバーであるユーザーは、どちらもこの機能を使用できますが、ゲスト ユーザーは使用できません。

サインインしているユーザーがゲスト ユーザーの場合、アプリに付与されたアクセス許可に応じて、特定のユーザーまたはグループ (例: https://graph.microsoft.com/v1.0/users/241f22af-f634-44c0-9a15-c8cd2cea5531) のプロファイルを読み取ることはできますが、複数のリソースを返す可能性のある /users または /groups リソース セットに対してクエリは実行できません。

適切なアクセス許可があるアプリは、ナビゲーション プロパティのリンク (たとえば、/users/{id}/directReports や /groups/{id}/members) に従って取得するユーザーまたはグループのプロファイルの読み取りが可能になります。

既定では返されないプロパティ

ユーザー オブジェクトの一部のプロパティは既定では返されず、 $select クエリ パラメーターで指定する必要があります。 たとえば、 誕生日 や スキルなどです。 ユーザー エンティティのプロパティ テーブルを参照して、$select時にのみ返されるプロパティを特定します。

メイン データ ストアの外部に保存されているプロパティ

ユーザー リソース データは主に Microsoft Entra ID に保存されますが、スキルなどの一部のプロパティは SharePoint Online に保存されます。 ほとんどの場合、これらのプロパティは、他のユーザー プロパティと同じ Create または Update 要求本文で指定することはできません。

メイン データ ストアの外部に保存されているプロパティも、 変更追跡の一部としてサポートされていません。 したがって、これらのプロパティを変更しても、差分クエリ応答にオブジェクトは表示されません。

ユーザー オブジェクトの次のプロパティは、メイン データ ストアの外部に保存されます: signInActivity、 cloudLicensing、 mailboxSettings、 deviceEnrollmentLimit、 print、 aboutMe、 birthday、 hireDate、 interests、 mySite、 pastProjects、 preferredName、 responsibilities、 schools、 skills。

まとめ

Microsoft Graph には、ユーザー データを管理し、ユーザー データを操作するための強力な機能が用意されています。 さまざまなアクセス許可、一般的な API 操作を理解し、機密性の高いアクションを処理することで、安全で効率的なアプリケーションを構築できます。 詳細については、関連するコンテンツとドキュメントのリンクを参照してください。

関連コンテンツ

  • Last updated on