Microsoft Graph でのユーザーの操作
重要
Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。
Microsoft Graph を使用すると、ユーザーとその他のオブジェクトとの関係に基づいて魅力的なアプリ エクスペリエンスを構築できます。 たとえば、他のユーザーやグループとの関係、グループ メンバーシップ、メール、予定表、ファイル、管理ロールなど、アクセスするリソースなどです。
Microsoft Graph から 2 つの方法でユーザーにアクセスすることができます。
- ID または userPrincipalName、
/users/{id}、または/users/{userPrincipalName} -
/users/{signed-in user's id}と同じである、サインインしているユーザーの/meエイリアス使用して
一般的な API 操作
| パス | 説明 |
|---|---|
/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 を一覧表示します。 |
承認と特権
Microsoft Graph では、委任されたアクセス許可とアプリケーションのアクセス許可を使用してユーザー操作を管理できます。 詳細については、「 委任されたアクセス許可とアプリケーションのアクセス許可 」および各操作に必要なアクセス許可に関する対応する API リファレンス ドキュメントを参照してください。
一部のユーザー操作は、サインインしているユーザーが自分の詳細に対して実行できます。 このような操作の場合、ユーザーはアプリに自分の詳細にアクセスするためのアクセス許可を 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には、顧客に対する既定のアクセス許可もあります。 次の表は、顧客が自分のプロファイルを管理できるようにする 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 |
機密性の高いアクション
ユーザー オブジェクトに対する次のアクションは機密性が高いと見なされ、特定の管理者のみにロックダウンされる可能性があります。 すべてのユーザーが機密性の高いプロパティを読み取ることができます。
| 機密性の高いアクション | 機密性の高いプロパティ名 |
|---|---|
| ユーザーを無効または有効にする | accountEnabled |
| ビジネス用電話を更新する | businessPhones |
| 携帯電話の更新 | mobilePhone |
| オンプレミスの変更できない ID を更新する | onPremisesImmutableId |
| 他のメールを更新する | otherMails |
| パスワード プロファイルを更新する | passwordProfile |
| ユーザー プリンシパル名を更新する | userPrincipalName |
| ユーザーを削除または復元する | 該当なし |
機密性の高いアクションを実行できるユーザー
一部の管理者は、一部のユーザーに対して上記の機密アクションを実行できます。
次の表の列には、機密性の高いアクションを実行できるロールが一覧表示されています。 行には、機密性の高いアクションを実行できるロールが一覧表示されます。
次の表は、テナントのスコープで割り当てられたロールを示しています。 管理単位のスコープで割り当てられたロールについては、 さらに制限が適用されます。
| 機密性の高いアクションを実行できるロール | 認証管理 | ユーザー 管理 | Privileged Auth 管理 | グローバル管理者 |
|---|---|---|---|---|
| 認証管理 | ✅ | ✅ | ✅ | |
| ディレクトリ リーダー | ✅ | ✅ | ✅ | ✅ |
| グローバル管理者 | ✅ | ✅ | ||
| グループ 管理 | ✅ | ✅ | ✅ | |
| ゲスト招待者 | ✅ | ✅ | ✅ | ✅ |
| ヘルプデスク 管理 | ✅ | ✅ | ✅ | |
| メッセージ センター リーダー | ✅ | ✅ | ✅ | ✅ |
| パスワード 管理 | ✅ | ✅ | ✅ | ✅ |
| Privileged Auth 管理 | ✅ | ✅ | ||
| 特権ロールの管理 | ✅ | ✅ | ||
| レポート閲覧者 | ✅ | ✅ | ✅ | ✅ |
| ユーザー (管理者ロールなし) |
✅ | ✅ | ✅ | ✅ |
| ユーザー (管理者ロールはありませんが、ロール割り当て可能なグループのメンバーまたは所有者) |
✅ | ✅ | ||
| 制限付き管理管理単位にスコープが設定されたロールを持つユーザー | ✅ | ✅ | ||
| ユーザー 管理 | ✅ | ✅ | ✅ | |
| 使用状況の概要レポート閲覧者 | ✅ | ✅ | ✅ | ✅ |
| すべてのカスタム ロール | ✅ | ✅ |
パスワードをリセットできるユーザー
次の表の列には、パスワードをリセットして更新トークンを無効にできるロールが一覧表示されています。 行には、パスワードをリセットできるロールが一覧表示されます。 たとえば、パスワード管理者は、ディレクトリ リーダー、ゲスト招待者、パスワード管理者、管理者ロールのないユーザーのパスワードをリセットできます。 ユーザーに他のロールが割り当てられている場合、パスワード管理者はパスワードをリセットできません。
次の表は、テナントのスコープで割り当てられたロールを示しています。 管理単位のスコープで割り当てられたロールについては、 さらに制限が適用されます。
| パスワードをリセットできるロール | パスワード 管理 | ヘルプデスク 管理 | 認証管理 | ユーザー 管理 | Privileged Auth 管理 | グローバル管理者 |
|---|---|---|---|---|---|---|
| 認証管理 | ✅ | ✅ | ✅ | |||
| ディレクトリ リーダー | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| グローバル管理者 | ✅ | ✅* | ||||
| グループ 管理 | ✅ | ✅ | ✅ | |||
| ゲスト招待者 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ヘルプデスク 管理 | ✅ | ✅ | ✅ | ✅ | ||
| メッセージ センター リーダー | ✅ | ✅ | ✅ | ✅ | ✅ | |
| パスワード 管理 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Privileged Auth 管理 | ✅ | ✅ | ||||
| 特権ロールの管理 | ✅ | ✅ | ||||
| レポート閲覧者 | ✅ | ✅ | ✅ | ✅ | ✅ | |
| ユーザー (管理者ロールなし) |
✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| ユーザー (管理者ロールはありませんが、ロール割り当て可能なグループのメンバーまたは所有者) |
✅ | ✅ | ||||
| 制限付き管理管理単位にスコープが設定されたロールを持つユーザー | ✅ | ✅ | ||||
| ユーザー 管理 | ✅ | ✅ | ✅ | |||
| 使用状況の概要レポート閲覧者 | ✅ | ✅ | ✅ | ✅ | ✅ | |
| すべてのカスタム ロール | ✅ | ✅ |
パスワードをリセットする機能には、セルフサービス パスワード リセットに必要な次の機密性の高いプロパティを更新する機能が含 まれます。
- businessPhones
- mobilePhone
- otherMails
組織のゲスト ユーザーに対するユーザーとグループの検索の制限事項
ユーザーとグループの検索機能を使用すると、/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 クエリ パラメーターで指定する必要があります。 たとえば、 誕生日 や スキルなどです。
ユーザー エンティティの properties テーブルを参照して、$selectしたときにのみ返されるプロパティを識別します。
メイン データ ストアの外部に格納されているプロパティ
ユーザー リソース データは主にMicrosoft Entra IDに格納されますが、スキルなどのプロパティの一部は SharePoint Online に格納されます。 ほとんどの場合、他のユーザー プロパティと同じ [作成] または [更新] 要求本文でこれらのプロパティを指定することはできません。
メイン データ ストアの外部に格納されたプロパティも、変更追跡の一部としてサポートされていません。 したがって、これらのプロパティのいずれかに変更を加えた場合、デルタ クエリ応答にオブジェクトが表示されることはありません。