ユーザーを一覧表示する

名前空間: microsoft.graph

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

アクセス許可

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

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

HTTP 要求

GET /users

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

このメソッドは、応答をカスタマイズするための$search$count、および$filterを含むOData クエリ パラメーターをサポートします。 displayName プロパティで$searchを使用できます。 このリソースのアイテムを追加または更新すると、 $count$search クエリ パラメーターを共に使用するように特別にインデックスが作成されます。 アイテムを追加または更新してから、インデックスで使用できるようになるまでに少し時間がかかる場合があります。 現在、$countおよび$searchパラメーターは Azure AD B2C テナントでは使用できません。

既定では、限定的なプロパティのセットのみが返されます (businessPhonesdisplayNamegivenNameidjobTitlemailmobilePhoneofficeLocationpreferredLanguagesurname、および userPrincipalName)。 別のプロパティ セットを返すには、OData $select クエリ パラメーターを使用して、目的の user プロパティのセットを指定します。 たとえば、displayNamegivenNamepostalCode を返すには、クエリ $select=displayName,givenName,postalCode に次を追加します。

特定のプロパティは、ユーザー コレクションでは返すことができません。単一のユーザーを取得する場合にのみ、aboutMebirthdayhireDateinterestsmySitepastProjectspreferredNameresponsibilitiesschoolsskillsmailboxSettings の各プロパティがサポートされます。

次のプロパティは、個人用の Microsoft アカウントではサポートされていませんnull: aboutMebirthdayinterestsmySitepastProjectspreferredNameresponsibilitiesschoolsskillsstreetAddress

要求ヘッダー

ヘッダー
Authorization Bearer {トークン} (必須)
ConsistencyLevel 最終的。 このヘッダーと $count は、$search を使用する場合、$orderby クエリ パラメーターを使用して $filter を使用する場合、または endsWith 論理演算子を使用して $filter を使用する場合に必要です。 最新の状態に更新されていない可能性があるインデックスを使用しています。

要求本文

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

応答

成功した場合、このメソッドは 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

{
  "value": [
    {
      "displayName":"contoso1",
      "mail":"'contoso1@gmail.com",
      "mailNickname":"contoso1_gmail.com#EXT#",
      "otherMails":["contoso1@gmail.com"],
      "proxyAddresses":["SMTP:contoso1@gmail.com"], 
      "userPrincipalName":"contoso1_gmail.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

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

要求

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

ID でフィルター処理する場合、issuerissuerAssignedId の両方を指定する必要があります。 issuerAssignedId の値は、ユーザー プリンシパル名 (UPN) ではなく、ユーザー アカウントのメール アドレスである必要があります。 UPN が使用されている場合、空のリストが返信されます。

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 'contoso.onmicrosoft.com')

応答

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

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

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

{
  "value": [
    {
      "displayName": "John Smith"
    }
  ]
}

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

要求

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

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 の使用方法の詳細については、「Azure AD ディレクトリ オブジェクトの詳細クエリ機能」を参照してください。

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#",
      "otherMails":["a@contoso.com"],
      "proxyAddresses":["SMTP:a@contoso.com"],
      "userPrincipalName":"a_contoso.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

例 5: $filter を使用して、返されるオブジェクトの数を含む、"a@contoso.com' で終わるメールを持つすべてのユーザーを取得し、userPrincipalName で注文された結果を取得します。

要求

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

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 の使用方法の詳細については、「Azure AD ディレクトリ オブジェクトの詳細クエリ機能」を参照してください。

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",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    }
  ]
}

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

要求

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

GET https://graph.microsoft.com/v1.0/users?$search="displayName:wa" OR "displayName:to"&$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",
      "mailNickname":"oscward",
      "userPrincipalName":"oscarward@contoso.com"
    },
    {
      "displayName":"contoso1",
      "mail":"'contoso1@gmail.com",
      "mailNickname":"contoso1_gmail.com#EXT#",
      "proxyAddresses":["SMTP:contoso1@gmail.com"], 
      "userPrincipalName":"contoso1_gmail.com#EXT#@microsoft.onmicrosoft.com"
    }
  ]
}

例 8: $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"
        }
      ]
    }
  ]
}