ユーザーを一覧表示する
名前空間: 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 人の人物の DisplayName と EmailAddress に応答を制限します。
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 パラメーターを組み合わせることで、ユーザーに関連のある人物のカスタム リストを作成し、アプリケーションで必要になるフィールドのみを取得できます。
次に示す例では、指定した名前と等しい表示名を持つ人物の DisplayName と EmailAddress を取得します。 この例では、表示名が "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/
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示