こんにちは。

Office 365 などと連携した Application 内で User 一覧を表示する場合、Azure AD Graph を使うことができますが、ここで紹介する People API を使うと、もっと気の利いたユーザー選択を提供できるかもしれません。

例えば、普段 Outlook を使っている方は、アドレス欄に名前をタイプすると、組織内のユーザーだけでなく、普段自分がやりとりしている外部のユーザーも表示されます。

Office 365 では、Office Graph で解説したように、Outlook によるメールの送受信、Skype によるコミュニケーションなど、Signal を検知して常に Learning をおこなっています。
ここで紹介する People API を使うと、こうした Learning の結果を API から利用できます。

Authentication と留意点

People API を使用するには、他の API 同様、OAuth と REST を使用します。
OAuth の処理は、Azure AD (v1) と Azure AD v2.0 endpoint を使う 2 つの方法があり、People REST API も Outlook REST API の endpoint (https://outlook.office.com/api/{version}/) と Microsoft Graph (https://graph.microsoft.com/{version}/) の 2 つの Endpoint があって、いずれも基本的な処理は可能です。(好きな組み合わせで使っていただけます。)

しかしながら、今回紹介する People API では v2 endpoint, Microsoft Graph での組み合わせ (利用) が推奨されています。(この組み合わせでない場合、このあと解説するいくつかの機能が使用できません。) このため、以降も、この組み合わせで解説します。

まず、「v2.0 endpoint の OAuth を使った Client 開発」で紹介した手順で OAuth による認証をおこない、access token を取得します。(本投稿では この手順の説明はしませんので、「v2.0 endpoint の OAuth を使った Client 開発」を参照してください。)
この際、下記の通り、scope に https://graph.microsoft.com/people.read を指定します。

補足 : Outlook REST API (https://outlook.office.com/api/{version}/) を使用した場合、scope には https://outlook.office.com/people.read を指定します。

https://login.microsoftonline.com/common/oauth2/v2.0/authorize  ?response_type=code  &response_mode=query  &client_id=4951ea26-f...  &scope=https%3A%2F%2Fgraph.microsoft.com%2Fpeople.read+offline_access  &redirect_uri=https%3a%2f%2flocalhost%2ftestapp01

また、商用版 Office 365 だけでなく、Microsoft Account (ドメイン : office.com, hotmail.com, live.com., office365.com) も使用可能であり、Outlook.com などの会話も対象にできます。
ただし、Microsoft Account の場合は、New Outlook.com (下図のように、Add-in などの新機能の入った Outlook.com) が展開されたアカウントが必要ですので注意してください。

補足 : 現在、「Office Blog : Outlook.com?out of preview and better than ever」の通り、この Outlook.com を順次 Roll out (展開) 中です。特に、日本のユーザーは、まだ利用できていない方も多いかと思いますが、単なる UI 変更ではなく Server のアーキテクチャ変更 (データ移行など含む) のため、すみませんが、もう少々お待ちください。。。

People API の基礎

People API の Endpoint は、{user}/people です。
例えば、下記は、ログインしているユーザー (自分) に関係する People の一覧を取得します。(Authorization ヘッダーには、上記で取得した access token を設定します。)

補足 : Outlook の Endpoint を使用する場合は、https://outlook.office.com/api/{version}/me/people です。

HTTP Request

GET https://graph.microsoft.com/v1.0/me/peopleAccept: application/jsonAuthorization: Bearer EwB4Aul3BAAUo4xe...

HTTP Response

{  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('fb0d1227-1553-4d71-a04f-da6507ae0d85')/people",  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/people?$skip=10",  "value": [{  "id": "2ffe5979-4e37-4561-84c3-e1dc93ea1092",  "displayName": "Ben Walters",  "givenName": "Ben",  "surname": "Walters",  "birthday": "",  "personNotes": "",  "isFavorite": false,  "jobTitle": "VP Sales",  "companyName": null,  "yomiCompany": "",  "department": "Sales & Marketing",  "officeLocation": "19/3123",  "profession": "",  "userPrincipalName": "BenW@MOD776816.onmicrosoft.com",  "imAddress": "sip:benw@mod776816.onmicrosoft.com",  "scoredEmailAddresses": [{  "address": "BenW@MOD776816.onmicrosoft.com",  "relevanceScore": 131}  ],  "phones": [{  "type": "business",  "number": "+1 732 555 0102"}  ],  "postalAddresses": [],  "websites": [],  "personType": {"class": "Person","subclass": "OrganizationUser"  }},{  "id": "MkU4M...",  "displayName": "Tsuyoshi Matsuzaki",  "givenName": null,  "surname": null,  "birthday": "",  "personNotes": "",  "isFavorite": false,  "jobTitle": null,  "companyName": null,  "yomiCompany": "",  "department": null,  "officeLocation": null,  "profession": "",  "userPrincipalName": "",  "imAddress": null,  "scoredEmailAddresses": [{  "address": "tsuyoshi.matsuzaki@outlook.com",  "relevanceScore": 80}  ],  "phones": [],  "postalAddresses": [],  "websites": [],  "personType": {"class": "Person","subclass": "ImplicitContact"  }},...  ]}

検索結果 (上記の HTTP Response) に注目してください。
Relevance (上記の relevanceScore 参照) が表示され、既定では Relevancy の高い順に表示されています。

また、組織内の人 (上記の BenW@MOD776816.onmicrosoft.com) だけでなく、組織外の人 (上記の tsuyoshi.matsuzaki@outlook.com) も表示されています。
取得した人やグループがどのような区分に属するかは、personType で判断可能で、種類に応じて下記の通り設定されます。(完全なリストは「People API available in Microsoft Graph v1.0」を参照してください。)

組織内ユーザー (Azure AD ユーザー) の場合

{  "id": "2ffe5979-4e37-4561-84c3-e1dc93ea1092",  "displayName": "Ben Walters",  "givenName": "Ben",  ...  "personType": {"class": "Person","subclass": "OrganizationUser"  }}

個人の連絡先 (Contacts) の場合

{  "id": "AAQkA...",  "displayName": "Taro Demo",  "givenName": "Taro",  "surname": "Demo",  ...    "personType": {"class": "Person","subclass": "PersonalContact"  }}

Outlook など過去にやりとりした実績のある人の場合

{  "id": "MkU4M...",  "displayName": "Tsuyoshi Matsuzaki",  "givenName": null,  "surname": null,  ...    "personType": {"class": "Person","subclass": "ImplicitContact"  }}

この属性を使って、下記の通り、組織外のユーザーのみを Relevancy 順に取得できます。

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

同じ組織内のユーザーの場合、上記の id をたどって、さらに別のユーザーの People 一覧を取得できます。(このようにして、People のネットワークをたどっていけます。)
ただし、この場合 (他ユーザーの情報を見る場合)、scope に https://graph.microsoft.com/people.read ではなく https://graph.microsoft.com/user.readbasic.all を使用します。また、Public Signal (他の人に見えて良い Signal) と Private Signal (当事者間だけの Signal) を区別するため、ログインするユーザーによって結果が異なる点にも注意してください。すなわち、ユーザー A でログインした場合のユーザー A の People 一覧と、ユーザー B でログインした場合のユーザー A の People 一覧は、結果が異なります。

https://graph.microsoft.com/v1.0/users/{user id}/people

実際の例 :

https://graph.microsoft.com/v1.0/users/xxxxx@zzzzz.onmicrosoft.com/people

OData による検索や絞り込みも可能です。
例えば、下記は、上述の personType の subclass が「ImplicitContact」となっている People 一覧を取得し、検索結果のうち displayName のみを取得します。

https://graph.microsoft.com/v1.0/me/people?$select=displayName&$filter=personType/subclass eq 'ImplicitContact'

HTTP Response は下記のようになります。(id, displayName のみが返されます。)

{  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('43e8595e-867b-42e1-b72c-5fb5d1786914')/people(displayName)",  "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/people?$select=displayName&$filter=personType%2fsubclass+eq+%27ImplicitContact%27&$skip=10",  "value": [{  "id": "MkU4M.....",  "displayName": "Tsuyoshi Matsuzaki"},{  "id": "MkU4M.....",  "displayName": "Taro Demo"},{  "id": "MkU4M.....",  "displayName": "Jiro Demo"},...  ]}

Search と Fuzzy Matching

People API の検索を使うと、Outlook の Auto complete のような高度な検索と絞り込みを提供できます。

例えば、下記は、givenName, surname, emailAddress が「m」ではじまる人 (Mark, Matsuzaki, など) を取得します。

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

さらに、下記の通り「Marc」で検索してみましょう。
すると、連絡先に登録された Mark Russinovich も検索されます。つまり、Exact Matching でなく、Fuzzy Matching を使って関連する People を検索します。

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

日本語も扱えます。
例えば、下記は「ふ」ではじまるユーザー (ふくだ、ふるた、ふじえ、など) を検索します。(下記の %E3%81%B5 は「ふ」の URL Encode 文字列です。) もちろん、漢字もいけます。

https://graph.microsoft.com/v1.0/me/people/?$search=%E3%81%B5

なお、日本語の場合、残念ながら、現在 (2016/06)、Fuzzy 検索 (例 : 富士榮さんと冨士榮さん) やルビを絡めた検索などはサポートされていません。

Topic 検索

Topic 検索では、その話題に関連する人を検索できます。

例えば、下記は、「Planning」についてメールでやりとりをした人物 (例 : タイトルに「Planning」を含むメールを送受信した相手など) を検索します。
なお、下記は、見やすくするためにそのまま記載していますが、実際には、https://.../?$search=%22topic%3A%20planning%22 のように URL Encode をおこなってください。
また、必ず、Double Quote で区切るようにしてください。(例 “…”)

https://graph.microsoft.com/v1.0/me/people/?$search="topic: planning"

ここでも同様に日本語が使えます。「企画書」に関連したユーザーを検索する場合は、下記の通りです。(上述の通り、実際の使用時は URL Encode をしてください。)

https://graph.microsoft.com/v1.0/me/people/?$search="topic: 企画書"

※ 変更履歴 :

2017/08  Microsoft Graph v1.0 People API のリリースに伴う変更の反映 (Team Blog「People API available in Microsoft Graph v1.0」参照)