ユーザーを一覧表示する

  • [アーティクル]

名前空間: microsoft.graph

user オブジェクトの一覧を取得します。

メモ: この要求には、最近作成、更新、または削除されたユーザーのレプリケーションの遅延が発生する可能性があります。

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

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

アクセス許可

この API を呼び出すには、次のいずれかのアクセス許可が必要です。 アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。

アクセス許可の種類 アクセス許可 (特権の小さいものから大きいものへ)
委任 (職場または学校のアカウント) User.ReadBasic.All, User.Read.All, User.ReadWrite.All, Directory.Read.All, Directory.ReadWrite.All
委任 (個人用 Microsoft アカウント) サポートされていません。
アプリケーション User.Read.All、User.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All

ゲストはこの API を呼び出すことはできません。 メンバーとゲストのアクセス許可の詳細については、「Microsoft Entra ID の既定のユーザーアクセス許可とは」を参照してください。

HTTP 要求

GET /users

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

このメソッドは、応答のカスタマイズに$count$filter$expand$orderby役立つ、、$search、$select、および$top OData クエリ パラメーターをサポートします。 $skip はサポートされていません。 signInActivity プロパティは既定では返されないため、ユーザーの一覧表示中に または $filter=signInActivity を指定$select=signInActivityする必要があります。

クエリの中には、ConsistencyLevel ヘッダーの設定を eventual および $count に使用した場合にのみサポートされるものもあります。 詳細については、「 ディレクトリ オブジェクトの高度なクエリ機能」を参照してください。 現在、$countおよび$searchパラメーターは Azure AD B2C テナントでは使用できません。

既定では、一部のプロパティのみが返されます (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 でのみ返されます。 $filter (eq、 ne、 および eq の null 値) をサポートします。
スキーマ拡張機能 $select でのみ返されます。 $filter (eq、 ne、 および eq の null 値) をサポートします。
オープン拡張機能 $expand、つまり、users?$expand=extensions でのみ返されます。
ディレクトリ拡張機能 $select でのみ返されます。 $filter (eq、 ne、 および eq の null 値) をサポートします。

特定のプロパティは、ユーザー コレクション内で返すことはできません。 次のプロパティは、 1 人のユーザーを取得する場合にのみサポートされます。 aboutMe、 birthday、 hireDate、 interests、 mySite、 pastProjects、 preferredName、 責任、 学校、 スキル、 mailboxSettings。

次のプロパティは、個人の Microsoft アカウント nullではサポートされていません。 aboutMe、 birthday、 interests、 mySite、 pastProjects、 preferredName、 責任、 学校、 スキル、 streetAddress についてです。

要求ヘッダー

ヘッダー 値
Authorization Bearer {token} (必須)
ConsistencyLevel 最終的。 このヘッダーと $count は、$search を使用する場合、または $filter の特別な使用をする場合に必要です。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

要求本文

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

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文で user オブジェクトのコレクションを返します。 大きいユーザー コレクションが返された場合は、アプリでページングを使用することができます。

コレクションで /users を使用$selectして、ユーザー コレクション内で返されないプロパティ (要求../users?$select=aboutMeなど) を取得しようとすると、エラー コードが501 Not Implemented返されます。

例

例 1: すべてのユーザーを取得する

要求

要求の例を次に示します。

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

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
    "value": [
        {
            "businessPhones": [],
            "displayName": "Conf Room Adams",
            "givenName": null,
            "jobTitle": null,
            "mail": "Adams@contoso.com",
            "mobilePhone": null,
            "officeLocation": null,
            "preferredLanguage": null,
            "surname": null,
            "userPrincipalName": "Adams@contoso.com",
            "id": "6ea91a8d-e32e-41a1-b7bd-d2d185eed0e0"
        },
        {
            "businessPhones": [
                "425-555-0100"
            ],
            "displayName": "MOD Administrator",
            "givenName": "MOD",
            "jobTitle": null,
            "mail": null,
            "mobilePhone": "425-555-0101",
            "officeLocation": null,
            "preferredLanguage": "en-US",
            "surname": "Administrator",
            "userPrincipalName": "admin@contoso.com",
            "id": "4562bcc8-c436-4f95-b7c0-4f8ce89dca5e"
        }
    ]
}

例 2: サインイン名を使用してユーザー アカウントを取得する

要求

要求の例を次に示します。

注:issuerAssignedId をフィルター処理する場合、 issuer と issuerAssignedId の両方を指定する必要があります。 ただし、特定のシナリオでは、issuer 値は無視されます。 ID のフィルター処理の詳細については、「objectIdentity リソースの種類」を参照してください。

GET https://graph.microsoft.com/v1.0/users?$select=displayName,id&$filter=identities/any(c:c/issuerAssignedId eq 'j.smith@yahoo.com' and c/issuer eq 'My B2C tenant')

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "value": [
    {
      "displayName": "John Smith",
      "id": "87d349ed-44d7-43e1-9a83-5f2406dee5bd"
    }
  ]
}

例 3: ユーザー数のみを取得する

要求

要求の例を次に示します。 この要求では、$count が要求にあるため、ConsistencyLevel ヘッダーを eventual に設定する必要があります。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

注:$countおよび$searchのクエリパラメーターは、現在 Azure ADB2C テナントでは使用できません。

GET https://graph.microsoft.com/v1.0/users/$count
ConsistencyLevel: eventual

応答

応答の例を下に示します。

HTTP/1.1 200 OK
Content-type: text/plain

893

例 4: $filter と $top を使用して、「a」で始まる表示名のユーザーを 1 人取得する (返されたオブジェクトの数も含む)

要求

要求の例を次に示します。 この要求では、$orderby と $filter の両方のクエリ パラメーターがあるため、ConsistencyLevel ヘッダーを eventual および $count=true クエリ文字列に設定することが必要です。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

注:$countおよび$searchのクエリパラメーターは、現在 Azure ADB2C テナントでは使用できません。

GET https://graph.microsoft.com/v1.0/users?$filter=startswith(displayName,'a')&$orderby=displayName&$count=true&$top=1
ConsistencyLevel: eventual

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":1,
  "value":[
    {
      "displayName":"a",
      "mail":"a@contoso.com",
      "mailNickname":"a_contoso.com#EXT#",
      "userPrincipalName":"a_contoso.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

例 5: $filterを使用して、返されたオブジェクトの数を含め、'a@contoso.com' で終わるメールを持つすべてのユーザーを取得し、userPrincipalName によって順序付けされた結果を取得します

要求

要求の例を次に示します。 この要求では、$orderby と $filter の両方のクエリ パラメーター、および endsWith 演算子があるため、ConsistencyLevel ヘッダーを eventual および $count=true クエリ文字列に設定することが必要です。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

注:$countおよび$searchのクエリパラメーターは、現在 Azure ADB2C テナントでは使用できません。

GET https://graph.microsoft.com/v1.0/users?$filter=endswith(mail,'a@contoso.com')&$orderby=userPrincipalName&$count=true
ConsistencyLevel: eventual

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count": 1,
  "value": [
    {
      "displayName": "Grady Archie",
      "givenName": "Grady",
      "jobTitle": "Designer",
      "mail": "GradyA@contoso.com",
      "userPrincipalName": "GradyA@contoso.com",
      "id": "e8b753b5-4117-464e-9a08-713e1ff266b3"
      }
    ]
}

例 6: $search を使用して、表示名に「wa」の文字が含まれるユーザーを取得します (返されたオブジェクトの数も含む)

要求

要求の例を次に示します。 この要求では、$search が要求にあるため、ConsistencyLevel ヘッダーを eventual に設定する必要があります。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

注:$countおよび$searchのクエリパラメーターは、現在 Azure ADB2C テナントでは使用できません。

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa"&$orderby=displayName&$count=true
ConsistencyLevel: eventual

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

例 7: $search を使用して、表示名に「wa」または「ad」の文字が含まれるユーザーを取得します (返されたオブジェクトの数も含む)

要求

要求の例を次に示します。 この要求では、$search が要求にあるため、ConsistencyLevel ヘッダーを eventual に設定する必要があります。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

注:$countおよび$searchのクエリパラメーターは、現在 Azure ADB2C テナントでは使用できません。

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa" OR "displayName:ad"&$orderbydisplayName&$count=true
ConsistencyLevel: eventual

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users",
  "@odata.count":7,
  "value":[
    {
      "displayName":"Oscar Ward",
      "givenName":"Oscar",
      "mail":"oscarward@contoso.com",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contosoAdmin1",
      "givenName":"Contoso Administrator",
      "mail":"'contosoadmin1@fabrikam.com",
      "userPrincipalName":"contosoadmin1_fabrikam.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

例 8: userPrincipalName によって特定のテナントまたはドメインからゲスト (B2B) ユーザーを取得する

要求

要求の例を次に示します。 ゲスト (B2B コラボレーション) ユーザーの userPrincipalName 値には、常に "#EXT#" 識別子が含まれます。 たとえば、ホーム テナント内のユーザーの userPrincipalName は です AdeleV@adatum.com。 テナントで共同作業するようにユーザーを招待すると、 contoso.com、テナント内の userPrincipalName は "AdeleV_adatum.com#EXT#@contoso.com" になります。

要求には endsWith 演算子が含まれているため、この要求には ConsistencyLevel ヘッダーが に eventual 設定され $count=true 、クエリ文字列が必要です。 ConsistencyLevel と $countの使用の詳細については、「ディレクトリ オブジェクトに対する高度なクエリ機能」を参照してください。

メモ： userPrincipalName 値の予約文字 "#" は、要求 URL の "%23" としてエンコードする必要があります。 詳細については、「 特殊文字のエンコード」を参照してください。

GET https://graph.microsoft.com/v1.0/users?$select=id,displayName,mail,identities&$filter=endsWith(userPrincipalName,'%23EXT%23@contoso.com')&$count=true
ConsistencyLevel: eventual

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,displayName,mail,identities)",
    "@odata.count": 2,
    "value": [
        {
            "id": "39807bd1-3dde-48f3-8165-81ddd4e46de0",
            "displayName": "Adele Vance",
            "mail": "AdeleV@adatum.com",
            "identities": [
                {
                    "signInType": "userPrincipalName",
                    "issuer": "contoso.com",
                    "issuerAssignedId": "AdeleV_adatum.com#EXT#@cntoso.com"
                }
            ]
        }
    ]
}

例 9: $filterを使用して、特定のライセンスが割り当てられているユーザーを取得する

要求

要求の例を次に示します。

GET https://graph.microsoft.com/v1.0/users?$select=id,mail,assignedLicenses&$filter=assignedLicenses/any(u:u/skuId eq cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46)

応答

応答の例を下に示します。

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(id,mail,assignedLicenses)",
  "value": [
    {
      "id": "cb4954e8-467f-4a6d-a8c8-28b9034fadbc",
      "mail": "admin@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    },
    {
      "id": "81a133c2-bdf2-4e67-8755-7264366b04ee",
      "mail": "DebraB@contoso.com",
      "assignedLicenses": [
        {
          "disabledPlans": [],
          "skuId": "cbdc14ab-d96c-4c30-b9f4-6ada7cdc1d46"
        }
      ]
    }
  ]
}

例 10: すべてのユーザーのスキーマ拡張機能の値を取得する

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

要求

GET https://graph.microsoft.com/v1.0/users?$select=ext55gb1l09_msLearnCourses

応答

次の応答では、スキーマ拡張プロパティ ext55gb1l09_msLearnCourses が 2 つのユーザー オブジェクトで割り当てられていません。

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

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

注: スキーマ拡張プロパティに $filter を適用して、コレクション内のプロパティが指定された値と一致するオブジェクトを取得することもできます。 構文は /users?$filter={schemaPropertyID}/{propertyName} eq 'value' です。 たとえば、「 GET /users?$select=ext55gb1l09_msLearnCourses&$filter=ext55gb1l09_msLearnCourses/courseType eq 'Developer' 」のように入力します。 eq および not 演算子がサポートされています。

例 11: 最後のサインイン時間を含むユーザーを取得する

要求

要求の例を次に示します。 signInActivity プロパティの詳細には、Microsoft Entra ID P1 または P2 ライセンスと AuditLog.Read.All アクセス許可が必要です。

メモ：ユーザーの一覧表示中に または $filter=signInActivity を指定$select=signInActivityした場合の最大ページ サイズ$topは 120 です。 120 を超える設定の $top 要求では、最大 120 人のユーザーのページが返されます。 signInActivity は $filter (eq、、、ge) leをサポートしていますが、nenot他のフィルター可能なプロパティではサポートされていません。

GET https://graph.microsoft.com/v1.0/users?$select=displayName,userPrincipalName,signInActivity

応答

応答の例を下に示します。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users(displayName,userPrincipalName,signInActivity)",
  "value": [
    {
      "displayName": "Adele Vance",
      "userPrincipalName": "AdeleV@contoso.com",
      "id": "1aecaf40-dc3a-461f-88a8-d06994e12898",
      "signInActivity": {
        "lastSignInDateTime": "2021-06-17T16:41:33Z",
        "lastSignInRequestId": "d4d31c40-4c36-4775-ad59-7d1e6a171f00",
        "lastNonInteractiveSignInDateTime": "0001-01-01T00:00:00Z",
        "lastNonInteractiveSignInRequestId": ""
      }
    },
    {
      "displayName": "Alex Wilber",
      "userPrincipalName": "AlexW@contoso.com",
      "id": "f0662ee5-84b1-43d6-8338-769cce1bc141",
      "signInActivity": {
        "lastSignInDateTime": "2021-07-29T15:53:27Z",
        "lastSignInRequestId": "f3149ee1-e347-4181-b45b-99a1f82b1c00",
        "lastNonInteractiveSignInDateTime": "2021-07-29T17:53:42Z",
        "lastNonInteractiveSignInRequestId": "868efa6a-b2e9-40e9-9b1c-0aaea5b50200"
      }
    }
  ]
}