people API を使用して、あなたに最も関連する人物についての情報を取得する

  • [アーティクル]

Microsoft Graph では、People API を使用してユーザーに最も関連のある人物を取得できます。 関連性は、ユーザーのコミュニケーションとコラボレーション パターン、およびビジネスのリレーションシップによって決定されます。 ユーザーは、ローカルの連絡先または組織のディレクトリからの連絡先と、最近のコミュニケーションのユーザーにすることができます。

この情報を生成するとともに、People API は、あいまい一致 検索のサポートと、サインインしているユーザーの組織内の別のユーザーに関連するユーザーのリストを取得する機能も提供します。

people API は、メールの作成や会議の作成などのシナリオを選択するユーザーに役立ちます。 たとえば、メール作成のシナリオで People API を使用できます。

関連するユーザーまたは "working-with" として人物を含む

関連するユーザーまたは "working-with" に関連するユーザーを含めるにはDelve のプロファイル所有者、所有者のプロファイル カードに表示する、または people API によって返されるプロファイル所有者は、ユーザーとプロファイル所有者の間にパブリックな関係がある必要があります。 次の図は、ユーザーA、他のユーザー（ユーザーB）との関係性の見出し、およびユーザー関係の一部分を示すパブリックプロファイルを示しています。

関係図構築のイメージ

以下は、登録関係の例です。

  • 組織図で接続されている個人：マネージャー、直属の部下、同僚（同じマネージャーを共有）
  • 30人未満の公開グループまたは配布リストのメンバー。 公開グループは、ディレクトリ内に利用可能なメンバーシップ一覧を持ちます。

プロファイルの所有者が他のユーザーと通信していて、そのユーザーと組織図での接続や共通のグループなどのパブリックの関係がない場合、彼らが通信しているという事実は他のユーザーには見えません。

ユーザーの順位 (つまり、プロファイル所有者のページに表示される順序) は、プロファイル所有者とリスト上のユーザーの間のパブリック通信によって決まります。

公開インタラクションの例は以下のとおりです。

  • 公開グループの一員としての電子メールの送受信
  • グループの一部として、または○○人以上が招待されている場所でユーザーを会議に招待する

一覧は、ユーザーAが誰であるか（他のユーザーのページを見ている人）に基づいて変わることはありません。 一覧は、ユーザーB（プロファイル所有者）とユーザーC（プロファイル所有者リストに表示されている人）の間のインタラクションレベルによって決まります。

ユーザーCが表示されるようにするには、プロファイル所有者が、そのユーザーが公開されている比較的小さなグループ または 配布リストに属している（つまり、メンバーシップリストがディレクトリで利用可能であるということ）必要があります。

organizationの外部にあるPeopleは、プロファイル所有者の一覧に表示されません。 メールを送信したり、会ったりしても、同じorganizationに属していないPeopleは、所有者が作業しているユーザーとして表示されません。

"working-with" を無効にする

管理者は、プロファイル所有者に関連するユーザーの表示または返却を次の 2 つのレベルで管理できます:

  • 組織向け:
    • 組織全体を有効にします。 これは、既定の設定です。
    • プロファイル所有者以外の組織全体に対して無効にします。
  • organizationのMicrosoft Entra グループの場合:
    • 指定したMicrosoft Entra グループに対して無効にします。 これは、Microsoft Entra グループ内のメンバーを除く、organizationに対して "操作中" を有効にする場合に役立ちます。

詳細については、customize people insight privacy controlを参照してください。

Authorization

Microsoft Graph で people API を呼び出すには、アプリに適切なアクセス許可が必要です。

  • People.Read - 一般的なプロファイル API の呼び出しに使用します; 例、 https://graph.microsoft.com/v1.0/me/people/。 People.Read には、エンド ユーザーの同意が必要です。
  • People.Read.All - サインインしているユーザーの組織 (https://graph.microsoft.com/v1.0/users/{id}/people) の呼び出しで、特定のユーザーに最も関連性のあるユーザーを取得するために必要です。 People.Read.All には、管理者の同意が必要です。

人物の参照

このセクションの要求では、サインインしているユーザー (/me)、またはサインインしているユーザーのorganization内の特定のユーザーに最も関連性の高いユーザーを取得します。 これらの要求には、Peopleが必要です。読み取りまたはPeople。Read.All のアクセス許可はそれぞれです。 既定では、各応答は 10 個のレコードを返しますが、 $top クエリ パラメーターを使用してこれを変更できます。

関連する人物のコレクションの取得

次に示す要求では、コミュニケーションとコラボレーション パターン、およびビジネスのリレーションシップに基づいて、サインインしているユーザーに最も関連のある人物を取得します (/me)。

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

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これを変更するには、 $top クエリ パラメーターを使用します。 この例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

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

最初の応答に関連のある人物のリストを完全に含められない場合は、追加の情報ページを要求するために、$top と $skip を使用して 2 番目の要求を行うことができます。 前の要求に追加情報が含まれている場合は、次の要求でサーバーから人物についての後続ページを取得します。

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

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これを変更するには、 $top クエリ パラメーターを使用します。 この例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola",
      "givenName": "Felix",
      "surname": "Coppola",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Legal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2109",
      "profession": "",
      "userPrincipalName": "FelixC@contoso.com",
      "imAddress": "sip:FelixC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "FelixC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0104"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland",
      "givenName": "Lenora",
      "surname": "Rowland",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/1106",
      "profession": "",
      "userPrincipalName": "LenoraR@contoso.com",
      "imAddress": "sip:LenoraR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LenoraR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 954 555 0118"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette",
      "givenName": "Manuel",
      "surname": "Collette",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Accountant II",
      "companyName": null,
      "yomiCompany": "",
      "department": "Finance",
      "officeLocation": "98/2202",
      "profession": "",
      "userPrincipalName": "ManuelC@contoso.com",
      "imAddress": "sip:ManuelC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ManuelC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+20 255501070"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

応答の並べ替え

既定では、応答のユーザーはクエリとの関連性によって並べ替えられます。 $orderby パラメーターを使用して、応答のユーザーの順序を変更できます。 このクエリでは、最も関連性の高いユーザーを選択し、 displayName で並べ替え、並べ替えられたリストの最初の 10 人を返します。

GET https://graph.microsoft.com/v1.0/me/people/?$orderby=displayName

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これを変更するには、 $top パラメーターを使用します。 次の例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos",
      "givenName": "Adriana",
      "surname": "Ramos",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "18/2111",
      "profession": "",
      "userPrincipalName": "AdrianaR@contoso.com",
      "imAddress": "sip:AdrianaR@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AdrianaR@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 425 555 0109"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley",
      "givenName": "Alyce",
      "surname": "Cooley",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Marketing Assistant",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "131/1104",
      "profession": "",
      "userPrincipalName": "AlyceC@contoso.com",
      "imAddress": "sip:AlyceC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyceC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 858 555 0110"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke",
      "givenName": "Alyssa",
      "surname": "Clarke",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Corporate Security Officer",
      "companyName": null,
      "yomiCompany": "",
      "department": "Operations",
      "officeLocation": "24/1106",
      "profession": "",
      "userPrincipalName": "AlyssaC@contoso.com",
      "imAddress": "sip:AlyssaC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "AlyssaC@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 262 555 0106"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

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

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

次の例では、 に最も関連性の高い 1,000 人を要求します /me。 要求では、ユーザーの displayName のみを要求することで、サーバーから送信されるデータの量も制限されます。

GET https://graph.microsoft.com/v1.0/me/people/?$top=1000&$Select=displayName

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

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye"
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman"
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey"
    },
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Roscoe Seidel"
    },
    {
      "id": "6BB54D2C-EF20-48DA-ADD9-AE757DD30C4E",
      "displayName": "Alyssa Clarke"
    },
    {
      "id": "818E29A1-E6BB-4EDA-AB20-8230B4B1E290",
      "displayName": "Adriana Ramos"
    },
    {
      "id": "62633BAA-1CB9-4FA2-9B8F-55AB1840B69D",
      "displayName": "Alyce Cooley"
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Wayne Leeper"
    },
    {
      "id": "E7D40AC5-0078-4575-B1F3-F738124C4BC9",
      "displayName": "Jan Travis"
    },
    {
      "id": "6F99D1CC-4FCC-49E4-9160-E8AB01BF3E83",
      "displayName": "Charlotte Delacruz"
    },
    {
      "id": "1F28616D-BDFE-4080-8F06-03366A851688",
      "displayName": "Felix Coppola"
    },
    {
      "id": "8A3FC021-6DBB-44AC-8884-B7B500CC260A",
      "displayName": "Lenora Rowland"
    },
    {
      "id": "032C9919-4DF9-4715-8C46-4D0FAE7B3EB2",
      "displayName": "Manuel Collette"
    }
  ]
}

含まれる結果の種類

既定では、Microsoft Graph はメールボックスのみの結果を提供します。これは、保存されている連絡先またはやり取りする可能性が最も高いユーザーです。 組織全体のディレクトリ結果を取得するには、次に示すように HTTP ヘッダーを指定します。

"X-PeopleQuery-QuerySources: Mailbox,Directory”

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

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

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

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これは、$top パラメーターを使用して変更できます。 この例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ]
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

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

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

次のクエリは、class として person、subclass として organizationUser が割り当てられている personType プロパティを持つ person インスタンスへの応答を制限します。

GET https://graph.microsoft.com/v1.0/me/people/?$filter=personType/class eq 'Person' and personType/subclass eq 'OrganizationUser'

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これは、$top パラメーターを使用して変更できます。 この例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "givenName": "Lorrie",
      "surname": "Frye",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Paralegal",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "20/1109",
      "profession": "",
      "userPrincipalName": "LorrieF@contoso.com",
      "imAddress": "sip:LorrieF@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 980 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "5767393D-42BA-4E5C-BEE4-52BB25639CF4",
      "displayName": "Maynard Denman",
      "givenName": "Maynard",
      "surname": "Denman",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Web Marketing Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/1101",
      "profession": "",
      "userPrincipalName": "MaynardD@contoso.com",
      "imAddress": "sip:MaynardD@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "MaynardD@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "914B5191-11FA-4C0B-A354-0FA8C8EFD585",
      "displayName": "Darrel Halsey",
      "givenName": "Darrel",
      "surname": "Halsey",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Attorney",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "14/1102",
      "profession": "",
      "userPrincipalName": "DarrelH@contoso.com",
      "imAddress": "sip:DarrelH@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "DarrelH@contoso.com",
          "relevanceScore": 8
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 205 555 0103"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

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

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

次の例では、表示名が指定した名前と等しいユーザーの displayName と scoredEmailAddresses を取得します。 この例では、表示名が "Lorrie Frye" と等しいユーザーのみが返されます。

GET https://graph.microsoft.com/v1.0/me/people/?$select=displayName,scoredEmailAddresses&$filter=displayName eq 'Lorrie Frye'

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

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

{
  "value": [
    {
      "id": "8CE6E1DE-CB84-4BF5-971D-D3ECF452E2B5",
      "displayName": "Lorrie Frye",
      "scoredEmailAddresses": [
        {
          "address": "LorrieF@contoso.com",
          "relevanceScore": 8
        }
      ]
    }
  ]
}

他のユーザーの関連する人物の参照

次の要求は、「機能の実装」で説明されているように、サインインしたユーザーの組織内の別の人に最も関連性の高い人を取得します。 この要求には People.Read.All アクセス許可が必要です。 上記のセクションで説明されているすべてのクエリ パラメーターに適用されます。

この例では、Roscoe Seidel の関連する人物が表示されます。

GET https://graph.microsoft.com/v1.0/users('roscoes@contoso.com')/people/

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これは、$top パラメーターを使用して変更できます。 次の例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "56155636-703F-47F2-B657-C83F01F49BBC",
      "displayName": "Clifton Clemente",
      "givenName": "Clifton",
      "surname": "Clemente",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Director",
      "companyName": null,
      "yomiCompany": "",
      "department": "Legal",
      "officeLocation": "19/2106",
      "profession": "",
      "userPrincipalName": "CliftonC@contoso.com",
      "imAddress": "sip:CliftonC@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "CliftonC@contoso.com",
          "relevanceScore": 20
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 309 555 0101"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "6BF27D5A-AB4F-4C43-BED0-7DAD9EB0C1C4",
      "displayName": "Sheree Mitchell",
      "givenName": "Sheree",
      "surname": "Mitchell",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "Product Manager",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "20/2107",
      "profession": "",
      "userPrincipalName": "ShereeM@contoso.com",
      "imAddress": "sip:ShereeM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "ShereeM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 918 555 0107"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "B3E5302D-EAF0-4E8B-8C6C-A2AE64B4B163",
      "displayName": "Vincent Matney",
      "givenName": "Vincent",
      "surname": "Matney",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "CVP Engineering",
      "companyName": null,
      "yomiCompany": "",
      "department": "Engineering",
      "officeLocation": "23/2102",
      "profession": "",
      "userPrincipalName": "VincentM@contoso.com",
      "imAddress": "sip:VincentM@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "VincentM@contoso.com",
          "relevanceScore": 10
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 502 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

人物の検索

このセクションの要求を使用すると、サインインしているユーザー (/me) とサインインしているユーザーのorganization内の他のユーザーに関連するユーザーを検索できます。 これらの要求には、Peopleが必要です。読み取りアクセス許可(Peopleが必要な他のユーザーの関連ユーザーを検索する場合を除く)。Read.All。 既定では、各応答は 10 個のレコードを返しますが、 $top パラメーターを使用して変更できます。

検索による人物の選択

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

次の検索クエリは、/meそれらにdisplayName または emailAddress に文字「j」で始まる単語がある、に関連する人物を返します。

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

次の例は応答を示しています。 既定では、各応答は 10 個のレコードを返します。 これは、$top パラメーターを使用して変更できます。 この例では 、$top を使用して応答を 3 つのレコードに制限します。

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

{
  "value": [
    {
      "id": "E3C5B235-DE15-4566-B7B1-7A8E32426540",
      "displayName": "Jan Travis",
      "givenName": "Jan",
      "surname": "Travis",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": "VP Sales",
      "companyName": null,
      "yomiCompany": "",
      "department": "Sales & Marketing",
      "officeLocation": "19/3123",
      "profession": "",
      "userPrincipalName": "JanT@contoso.com",
      "imAddress": "sip:JanT@contoso.com",
      "scoredEmailAddresses": [
        {
          "address": "JanT@contoso.com",
          "relevanceScore": -12.297347783416837
        }
      ],
      "phones": [
        {
          "type": "Business",
          "number": "+1 732 555 0102"
        }
      ],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    },
    {
      "id": "C43BF05E-5B6B-4DCF-B2FC-0837B09E0FA9",
      "displayName": "Jacob Cazares (TAILSPIN)",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JacobC@tailspintoys.com",
          "relevanceScore": -12.298154282019846
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "PersonalContact"
      }
    },
    {
      "id": "6BB9CC1F-418D-4DDF-AB0C-6A1C4ABCDBF4",
      "displayName": "Jewell Montgomery",
      "givenName": "Jewell",
      "surname": "Montgomery",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "jobTitle": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "userPrincipalName": "JewellM@contoso.com",
      "imAddress": null,
      "scoredEmailAddresses": [
        {
          "address": "JewellM@contoso.com",
          "relevanceScore": -12.531408487977451
        }
      ],
      "phones": [],
      "postalAddresses": [],
      "websites": [],
      "personType": {
        "class": "Person",
        "subclass": "OrganizationUser"
      }
    }
  ]
}

検索は、あいまい一致のアルゴリズムを実装します。 完全一致に基づく結果と、検索の意図に関する推論にも基づいて結果が返されます。 たとえば、表示名が "Tyler Lee"、電子メールアドレスtylerle@example.comが、サインインユーザーのpeople集団に属しているとします。 次の検索はすべて、このユーザー Tyler を結果の 1 つとして返します。

GET https://graph.microsoft.com/v1.0/me/people?$search="tyler"                //matches both Tyler's name and email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle"              //matches Tyler's email
GET https://graph.microsoft.com/v1.0/me/people?$search="tylerle@example.com"  //matches Tyler's email. Note the quotes to enclose '@'.
GET https://graph.microsoft.com/v1.0/me/people?$search="tiler"                //fuzzy match with Tyler's name
GET https://graph.microsoft.com/v1.0/me/people?$search="tyler lee"            //matches Tyler's name. Note the quotes to enclose the space.