次の方法で共有

ユーザーの取得

名前空間: microsoft.graph

ユーザー オブジェクトのプロパティとリレーションシップを取得します。

この操作は既定で各ユーザーで頻繁に使用されるプロパティのサブセットのみを返します。 これらの既定のプロパティは、「プロパティ」セクションに記載されています。 既定で返されないプロパティを取得するには、ユーザーに対して GET 操作を実行し、$select OData クエリ オプションでプロパティを指定します。 ユーザー リソースは拡張機能をサポートしているため、GET 操作を使用して、ユーザー インスタンスでカスタム プロパティと拡張機能データを取得することもできます。

顧客のMicrosoft Entra IDを通じてこの API 操作を使用して詳細を取得することもできます。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、「アクセス許可のリファレンス」を参照してください。

アクセス許可の種類 最小特権アクセス許可 より高い特権のアクセス許可
委任 (職場または学校のアカウント) User.Read User.ReadWrite、User.ReadBasic.All、User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
委任 (個人用 Microsoft アカウント) User.Read User.ReadWrite
アプリケーション User.Read.All User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All

注:

User.Readアクセス許可を使用すると、アプリはプロファイルを読み取り、サインインしているユーザーのグループ メンバーシップ、レポート、マネージャーなどのリレーションシップのみを検出できます。

特定のシナリオのアクセス許可

  • employeeLeaveDateTime プロパティを読み取る方法:
    • 委任されたシナリオでは、サインインしているユーザーには、ライフサイクル ワークフロー管理者 (最小特権)、グローバル 閲覧者の少なくとも 1 つのMicrosoft Entraロールが必要です。アプリには User-LifeCycleInfo.Read.All 委任されたアクセス許可が付与されている必要があります。
    • Microsoft Graph のアクセス許可を持つアプリのみのシナリオでは、アプリに User-LifeCycleInfo.Read.All アクセス許可を付与する必要があります。
  • customSecurityAttributes プロパティを読み取る方法:
    • 委任されたシナリオでは、サインインしているユーザーに 属性割り当て管理者ロールを割り当て 、アプリに CustomSecAttributeAssignment.Read.All アクセス許可が付与されている必要があります。
    • Microsoft Graph のアクセス許可を持つアプリのみのシナリオでは、アプリに CustomSecAttributeAssignment.Read.All アクセス許可を付与する必要があります。
  • User-Mail.ReadWrite.All は、 otherMails プロパティの読み取りと書き込みの最小特権アクセス許可です。また、ユーザー オブジェクトで識別子関連のプロパティを読み取ることもできます。
  • User-PasswordProfile.ReadWrite.All は、パスワード リセット関連のプロパティの読み取りと書き込みの最小特権アクセス許可です。また、ユーザー オブジェクトで識別子関連のプロパティを読み取ることもできます。
  • User-Phone.ReadWrite.All は、businessPhone と mobilePhone のプロパティを読み書きするための最小特権アクセス許可です。また、ユーザー オブジェクトで識別子関連のプロパティを読み取ることもできます。
  • User.EnableDisableAccount.All + User.Read.All は、 accountEnabled プロパティの読み取りと書き込みを行うアクセス許可の最小特権の組み合わせです。

HTTP 要求

特定のユーザー:

GET /me
GET /users/{id | userPrincipalName}

注:

/me エンドポイントの呼び出しにはサインインしているユーザーが必要であり、そのため委任されたアクセス許可が必要です。 /me エンドポイントを使用する場合、アプリケーションのアクセス許可はサポートされません。

ヒント

  • userPrincipalName が $ 文字で始まる場合、 GET 要求の URL 構文 /users/$x@y.com は 400 Bad Request エラー コードで失敗します。 URL が OData URL 規則に違反しているため、要求は失敗します。これは、システム クエリ オプションのプレフィックスに $ 文字のみが含まれる必要があるためです。 回避策として、次のように /users の後のスラッシュ (/) を削除し、userPrincipalName をかっこと単一引用符で囲みます: /users('$x@y.com')。 たとえば、/users('$AdeleVance@contoso.com') などです。
  • userPrincipalName を使用して B2B ユーザーにクエリを実行するには、ハッシュ (#) 文字をエンコードします。 つまり、# 記号を %23 に置き換えます。 たとえば、/users/AdeleVance_adatum.com%23EXT%23@contoso.com などです。

サインイン ユーザー:

GET /me

注:

/me エンドポイントの呼び出しにはサインインしているユーザーが必要であり、そのため委任されたアクセス許可が必要です。 /me エンドポイントを使用する場合、アプリケーションのアクセス許可はサポートされません。

オプションのクエリ パラメーター

このメソッドは、 $selectOData クエリ パラメーター をサポートして、既定で返されないプロパティを含む特定のユーザー プロパティを取得します。

既定では、限定的なプロパティのセットのみが返されます (businessPhones、displayName、givenName、id、jobTitle、mail、mobilePhone、officeLocation、preferredLanguage、surname、userPrincipalName)。

別のプロパティ セットを返すには、OData $select クエリ パラメーターを使用して、目的の user プロパティのセットを指定する必要があります。 たとえば、 displayName、 givenName、 postalCode を返すには、クエリ $select=displayName,givenName,postalCodeに次の式を追加します。

拡張機能プロパティでは、次のようにクエリ パラメーターもサポートされます。

拡張機能の種類 コメント
onPremisesExtensionAttributes 1-15 $select でのみ返されます。
スキーマ拡張機能 $select でのみ返されます。
オープン拡張機能 ［オープン拡張機能を取得する］ 操作でのみ返されます。
ディレクトリ拡張機能 $select でのみ返されます。

要求ヘッダー

ヘッダー 値
Authorization ベアラー {token}。 必須です。 認証と認可についての詳細をご覧ください。

要求本文

このメソッドには、要求本文を指定しません。

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で user オブジェクトを返します。 $select を使用して特定のプロパティを指定していない限り、既定のプロパティを返します。 このメソッドは、要求が正常に処理されたが、サーバーが関連するバックグラウンド処理を完了するのにさらに時間を必要とする場合に 202 Accepted を返します。

ID を持つユーザーが存在しない場合、このメソッドは 404 Not Found エラー コードを返します。

例

例 1:標準的なユーザーの要求

要求

既定では、限定的なプロパティのセットのみが返されます (businessPhones、displayName、givenName、id、jobTitle、mail、mobilePhone、officeLocation、preferredLanguage、surname、userPrincipalName)。 この例では、既定の要求と応答を示します。

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd

応答

HTTP/1.1 200 OK
Content-type: application/json

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

例 2: サインインしているユーザーの要求

/users/{id | userPrincipalName} を /me に置き換えると、サインイン ユーザーのユーザー情報を取得できます。

要求

GET https://graph.microsoft.com/v1.0/me

応答

HTTP/1.1 200 OK
Content-type: application/json

{
  "businessPhones": [
       "+1 425 555 0109"
   ],
   "displayName": "Adele Vance",
   "givenName": "Adele",
   "jobTitle": "Retail Manager",
   "mail": "AdeleV@contoso.com",
   "mobilePhone": "+1 425 555 0109",
   "officeLocation": "18/2111",
   "preferredLanguage": "en-US",
   "surname": "Vance",
   "userPrincipalName": "AdeleV@contoso.com",
   "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
}

例 3: $selectを使用してユーザーの特定のプロパティを取得する

特定のプロパティを取得するには、OData$select クエリ パラメーターを使用します。 たとえば、 displayName、 givenName、 postalCode、 ID を返すには、次のクエリ式をクエリに追加します $select=displayName,givenName,postalCode,identities

要求

GET https://graph.microsoft.com/v1.0/users/87d349ed-44d7-43e1-9a83-5f2406dee5bd?$select=displayName,givenName,postalCode,identities

応答

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,givenName,postalCode,identities)/$entity",
    "displayName": "Adele Vance",
    "givenName": "Adele",
    "postalCode": "98004",
    "identities": [
        {
            "signInType": "userPrincipalName",
            "issuer": "contoso.com",
            "issuerAssignedId": "AdeleV@contoso.com"
        }
    ]
}

例 4: ユーザーのスキーマ拡張の値を取得する

この例では、スキーマ拡張の ID は ext55gb1l09_msLearnCourses です。

要求

GET https://graph.microsoft.com/v1.0/users/4562bcc8-c436-4f95-b7c0-4f8ce89dca5e?$select=ext55gb1l09_msLearnCourses

応答

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(ext55gb1l09_msLearnCourses)/$entity",
    "ext55gb1l09_msLearnCourses": {
        "@odata.type": "#microsoft.graph.ComplexExtensionValue",
        "courseType": "Developer",
        "courseName": "Introduction to Microsoft Graph",
        "courseId": 1
    }
}

例 5: ユーザーのカスタム セキュリティ属性の割り当てを取得する

次の例は、ユーザーのカスタム セキュリティ属性の割り当てを取得する方法を示しています。

属性 #1

  • 属性セット: Engineering
  • 属性: Project
  • 属性データ型: 文字列のコレクション
  • 属性値: ["Baker","Cascade"]

属性 #2

  • 属性セット: Engineering
  • 属性: CostCenter
  • 属性データ型: 整数のコレクション
  • 属性値: [1001]

属性 #3

  • 属性セット: Engineering
  • 属性: Certification
  • 属性データ型: ブール値
  • 属性値: true

属性 #4

  • 属性セット: Marketing
  • 属性: EmployeeId
  • 属性データ型: 文字列
  • 属性値: "QN26904"

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

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

要求

GET https://graph.microsoft.com/v1.0/users/{id}?$select=customSecurityAttributes

応答

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": {
        "Marketing": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "EmployeeId": "QN26904"
        },
        "Engineering": {
            "@odata.type": "#microsoft.graph.customSecurityAttributeValue",
            "Project@odata.type": "#Collection(String)",
            "Project": [
                "Baker",
                "Cascade"
            ],
            "CostCenter@odata.type": "#Collection(Int32)",
            "CostCenter": [
                1001
            ],
            "Certification": true
        }
    }
}

ユーザーに割り当てられたカスタム セキュリティ属性がない場合、または呼び出し元プリンシパルにアクセス権がない場合は、次のブロックに応答が表示されます。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(customSecurityAttributes)/$entity",
    "customSecurityAttributes": null
}