次の方法で共有


ユーザーを一覧表示する

名前空間: microsoft.graph

重要

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

ユーザーとの関連性によって順序付けられた 人物 オブジェクトのリストを取得します。これは、 ユーザーのコミュニケーションとコラボレーション のパターン、およびビジネス関係によって決まります。

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

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

アクセス許可

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

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) People.Read People.Read.All
委任 (個人用 Microsoft アカウント) People.Read 注意事項なし。
アプリケーション People.Read.All 注意事項なし。

HTTP 要求

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

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

このメソッドは、応答のカスタマイズに役立つ次の OData クエリ パラメーターをサポートします。

名前 説明
$filter string 応答を、指定した条件に等しいレコードを持つ人物のみに制限します。
$orderby string 既定では、応答に含まれる人物は、クエリとの関連性で並べ替えられます。 応答に含まれる人物の順序は、$orderby パラメーターを使用することで変更できます。
$search string 名またはエイリアスで人物を検索します。 ファジー マッチをサポートします。 パラメーターは、サインインしたユーザーの関連人物を検索するためにのみ機能し、他のユーザーに関連する人物を検索するためには機能しません。 その人とのメール会話から抽出されたトピックに基づいて人を見つける topic キーワードもサポートします。 詳細と例については、「People API を使用して最も関連性の高いユーザーに関する情報を取得する」の「あいまい検索の実行」セクションを参照してください。
$select string 応答に含めるプロパティを示すコンマ区切りのリスト。 最適なパフォーマンスを得るには、必要なプロパティのサブセットのみを選択します。
$skip int ページングに役立つ最初の n 個の結果をスキップします。 $searchを使用する場合、スキップはサポートされていません。
$top int 結果ページで返される結果の最大数。 詳細については、top パラメーターに関する ページを参照してください。

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
承諾 application/json

要求本文

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

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文の person オブジェクトのコレクションを返します。

参照

このセクションの要求では、コミュニケーション、コラボレーション、ビジネス関係に基づいて、サインインしているユーザー () に最も関連性の高いユーザーを/me取得します。

既定では、応答ごとに 10 件のレコードが返されます。ただし、$top パラメーターを使用することで、これを変更できます。 これらの要求には、Peopleが必要です。読み取りアクセス許可。

要求

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

GET https://graph.microsoft.com/beta/me/people

応答

次の例は応答を示しています。

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

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

{
    "value": [
        {
            "id": "33b43a5b-87d6-41ec-91f8-a2610048105f",
            "displayName": "Marketing",
            "givenName": null,
            "surname": null,
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": null,
            "companyName": null,
            "yomiCompany": "",
            "department": null,
            "officeLocation": null,
            "profession": "",
            "mailboxType": "GroupMailbox",
            "personType": "ModernGroup",
            "userPrincipalName": "",
            "emailAddresses": [
                {
                    "address": "Marketing@contoso.com",
                    "rank": 30
                }
            ],
            "phones": [],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        },
        {
            "id": "e3d0513b-449e-4198-ba6f-bd97ae7cae85",
            "displayName": "Isaiah Langer",
            "givenName": "Isaiah",
            "surname": "Langer",
            "birthday": "",
            "personNotes": "",
            "isFavorite": false,
            "title": "Web Marketing Manager",
            "companyName": null,
            "yomiCompany": "",
            "department": "Sales & Marketing",
            "officeLocation": "20/1101",
            "profession": "",
            "mailboxType": "Mailbox",
            "personType": "Person",
            "userPrincipalName": "IsaiahL@contoso.com",
            "emailAddresses": [
                {
                    "address": "IsaiahL@contoso.com",
                    "rank": 20
                }
            ],
            "phones": [
                {
                    "type": "business",
                    "number": "+1 918 555 0101"
                }
            ],
            "postalAddresses": [],
            "websites": [],
            "sources": [
                {
                    "type": "Directory"
                }
            ]
        }
    ]
}

人物の続きのページの要求

最初の応答に関連するユーザーの完全な一覧が含まれていない場合は、 $top$skip を使用して 2 番目の要求を行って、より多くの情報ページを要求できます。 前の要求に追加情報が含まれている場合は、次の要求でサーバーから人物についての後続ページを取得します。

GET https://graph.microsoft.com/beta/me/people/?$top=10&$skip=10

応答の並べ替え

既定では、応答に含まれる人物は、クエリとの関連性で並べ替えられます。 応答に含まれる人物の順序は、$orderby パラメーターを使用することで変更できます。 このクエリでは、自分に最も関連のある人物を選択し、その人物を表示名で並べ替えてから、最初の 10 人の人物を並べ替え済みのリストで返します。

GET https://graph.microsoft.com/beta/me/people/?$orderby=DisplayName

返される人物の数と返されるフィールドの変更

応答で返される人物の数は、$top パラメーターを設定することで変更できます。

次の例では、 に最も関連性の高い 1,000 人を要求します /me。 また、この要求では、人物の表示名のみを要求することで、サーバーから返されるデータの量も制限しています。

GET https://graph.microsoft.com/beta/me/people/?$top=1000&$select=DisplayName

返されるフィールドの選択

サーバーから返されるデータの量は、1 つ以上のフィールドを選択する $select パラメーターを使用することで制限できます。 @odata.id フィールドは常に返されます。

次に示す例では、最も関連のある 10 人の人物の DisplayNameEmailAddress に応答を制限します。

GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses

フィルターを使用した応答の制限

$filter パラメーターを使用すると、指定した条件に等しいレコードを持つ人物のみに応答を制限できます。

次のクエリは、ソース "ディレクトリ" を持つユーザーへの応答を制限します。

GET https://graph.microsoft.com/beta/me/people/?$filter=Sources/Any (source: source/Type  eq 'Directory')

フィルター処理された応答で返されるフィールドを選択する

$select パラメーターと $filter パラメーターを組み合わせることで、ユーザーに関連のある人物のカスタム リストを作成し、アプリケーションで必要になるフィールドのみを取得できます。

次に示す例では、指定した名前と等しい表示名を持つ人物の DisplayNameEmailAddress を取得します。 この例では、表示名が "Nestor Kellum" と等しい人物のみが返されます。

+GET https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$filter=DisplayName eq 'Nestor Kellum'

人物の検索

このセクションの要求では、サインインしているユーザー (/me) に最も関連性の高いユーザーも取得します。 Search要求には、Peopleが必要です。読み取りアクセス許可。

検索による人物の選択

$search パラメーターを使用して、特定の条件セットを満たす人物を選びます。

次の検索クエリは、 /me GivenName または Surname が文字 "j" で始まるユーザーを返します。

GET https://graph.microsoft.com/beta/me/people/?$search=j

検索による関連するトピックの指定

次の要求は、名前に /me "ma" が含まれており、"機能計画" と関連付けているユーザーに関連するユーザーを返します。

GET https://graph.microsoft.com/beta/me/people/?$search="ma topic: feature planning"

次の要求では、"Hermaini Hall" という名前のユーザーを検索します。サインインしているユーザーに関連する "Herminia Hull" という名前のユーザーが存在するため、"Herminia Hull" の情報が返されます。

GET https://graph.microsoft.com/beta/me/people/?$search="hermaini hall"

次の要求は、ユーザーのorganization内の他のユーザーに最も関連性の高いユーザーを取得します。 この要求には、Peopleの User.ReadBasic.All が必要です。Read.All アクセス許可。 この例では、Nestor Kellum の関連するユーザーが表示されます。

GET https://graph.microsoft.com/beta/users('nestork@contoso.com')/people/