Microsoft Graph People API の紹介


こんにちは。

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://outlook.office.com/api/beta/me/people
Accept: application/json
Authorization: Bearer EwB4Aul3BAAUo4xe...

HTTP Response

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('97ccaedf-d86a-4f1a-b822-6fe9a689d51b')/people",
  "value": [
    {
      "id": "97CCAEDF-D...",
      "displayName": "Jiro Demo",
      "givenName": "Jiro",
      "surname": "Demo",
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "emailAddresses": [
        {
          "address": "demouser02@o365directory.onmicrosoft.com",
          "rank": 39.0
        }
      ],
      "phones": [
        
      ],
      "postalAddresses": [
        
      ],
      "webSites": [
        
      ],
      "title": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "sources": [
        {
          "type": "Directory"
        }
      ],
      "mailboxType": "Mailbox",
      "personType": "Person"
    },
    {
      "id": "MkU4MDBGND...",
      "displayName": "tsuyoshi.matsuzaki@gmail.com",
      "givenName": null,
      "surname": null,
      "birthday": "",
      "personNotes": "",
      "isFavorite": false,
      "emailAddresses": [
        {
          "address": "tsuyoshi.matsuzaki@gmail.com",
          "rank": 14.0
        }
      ],
      "phones": [
        
      ],
      "postalAddresses": [
        
      ],
      "webSites": [
        
      ],
      "title": null,
      "companyName": null,
      "yomiCompany": "",
      "department": null,
      "officeLocation": null,
      "profession": "",
      "sources": [
        {
          "type": "Communication History"
        }
      ],
      "mailboxType": "OneOff",
      "personType": "Unknown"
    },
	
    . . . . .
	
  ]
}

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

また、組織内の人 (上記の demouser02@o365directory.onmicrosoft.com) だけでなく、組織外の人 (上記の tsuyoshi.matsuzaki@gmail.com) も表示されています。
取得した人がどのような区分に属するかは、source で判断可能で、種類に応じて下記の通り設定されます。

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

{
  "id": "97CCAEDF-D86A-4F1A-B822-6FE9A689D51B@3C839350-A414-442A-9585-8DB0B0F5F300",
  "displayName": "Jiro Demo",
  "givenName": "Jiro",
  "surname": "Demo",
  "birthday": "",
  "personNotes": "",
  "isFavorite": false,
  "emailAddresses": [
	{
	  "address": "demouser02@o365directory.onmicrosoft.com",
	  "rank": 39.0
	}
  ],
  "phones": [
	
  ],
  "postalAddresses": [
	
  ],
  "webSites": [
	
  ],
  "title": null,
  "companyName": null,
  "yomiCompany": "",
  "department": null,
  "officeLocation": null,
  "profession": "",
  "sources": [
	{
	  "type": "Directory"
	}
  ],
  "mailboxType": "Mailbox",
  "personType": "Person"
}

連絡先 (Contacts) の場合

{
  "id": "AAQkADczYj...",
  "displayName": "Izumi Kosaka",
  "givenName": "Izumi",
  "surname": "Kosaka",
  "birthday": "",
  "personNotes": "",
  "isFavorite": false,
  "emailAddresses": [
    {
      "address": "izumi@outlook.com",
      "rank": 9.0
    }
  ],
  "phones": [
	
  ],
  "postalAddresses": [
	
  ],
  "webSites": [
	
  ],
  "title": null,
  "companyName": null,
  "yomiCompany": null,
  "department": null,
  "officeLocation": null,
  "profession": "",
  "sources": [
    {
      "type": "Outlook Contacts"
    }
  ],
  "mailboxType": "Contact",
  "personType": "Person"
}

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

{
  "id": "MkU4MDBGND...",
  "displayName": "tsuyoshi.matsuzaki@gmail.com",
  "givenName": null,
  "surname": null,
  "birthday": "",
  "personNotes": "",
  "isFavorite": false,
  "emailAddresses": [
    {
      "address": "tsuyoshi.matsuzaki@gmail.com",
      "rank": 14.0
    }
  ],
  "phones": [
	
  ],
  "postalAddresses": [
	
  ],
  "webSites": [
	
  ],
  "title": null,
  "companyName": null,
  "yomiCompany": "",
  "department": null,
  "officeLocation": null,
  "profession": "",
  "sources": [
    {
      "type": "Communication History"
    }
  ],
  "mailboxType": "OneOff",
  "personType": "Unknown"
}

同じ組織内のユーザーの場合、上記の 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/beta/users/{user id}@{tenant id}/people

実際の例 :

https://graph.microsoft.com/beta/users/97CCAEDF-D86A-4F1A-B822-6FE9A689D51B@3C839350-A414-442A-9585-8DB0B0F5F300/people

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

https://graph.microsoft.com/beta/me/people/?$select=DisplayName,EmailAddresses&$Filter=Sources/Any (source: source/Type eq 'Communication History')

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

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('97ccaedf-d86a-4f1a-b822-6fe9a689d51b')/people(displayName,emailAddresses)",
  "value": [
    {
      "id": "MkU4MDBGND...",
      "displayName": "tsuyoshi.matsuzaki@gmail.com",
      "emailAddresses": [
        {
          "address": "tsuyoshi.matsuzaki@gmail.com",
          "rank": 39.0
        }
      ]
    },
    {
      "id": "MkU4MDBGND...",
      "displayName": "LinkedIn\u30e1\u30c3\u30bb\u30fc\u30b8",
      "emailAddresses": [
        {
          "address": "messages-noreply@linkedin.com",
          "rank": 0.0
        }
      ]
    },
    . . .
	
  ]
}

同様にして、下記の通り、組織内のユーザーのみを Relevancy 順に取得することも可能です。

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

Search と Fuzzy Matching

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

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

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

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

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

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

https://graph.microsoft.com/beta/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/beta/me/people/?$search="topic: planning"

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

https://graph.microsoft.com/beta/me/people/?$search="topic: 企画書"
Comments (0)

Skip to main content