修正
2020/7/19 : presenceのβ公開時期を2020年6月から2019年12月に修正しました。
(@karamem0さんご指摘ありがとうございました!)
2020/8/2:presenceのSubscriptionのドキュメントが公開されたので反映しました。
はじめに
2020年7月時点のMicrosoft Graphを使用した記事となります。
また記事で扱うpresenceは2020年7月段階でβ状態なので
参照されるタイミングによっては仕様が変更されている可能性がありますのでご留意ください。
presence
2019年12月に取得WebAPIがβ公開され、2020年7月に変更通知がサポートされました。
presenceとは具体的になんなのでしょうか。
めちゃくちゃかんたんに説明すると👇コレです。
presenceの取得
Graphの変更履歴の7月からのリンクは404なのですがドキュメントは確認できます。
presenceのデータを取得するのは下記のWebAPIで取得します。
※今はβしか公開されていないのでhttps://graph.microsoft.com/beta/
エンドポイントからしかアクセスできません。
GET /me/presence GET /users/{id}/presence GET /communications/presences
GET /communications/presences
と記載されていますが素直に使用しても複数人取得できず404になりました。
ユーザーid指定が必須のようなので、/communications/presences/{id}
が正しいと思います。
複数人のpresenceの取得はgetPresencesByUserIdです。
POSTで取得したいユーザーのidをBodyに指定するので、ちょっと違和感がありますね。
POST communications/getPresencesByUserId { "ids": ["<UserId>", "<UserId>"] }
presenceで取得するプロパティについて
取得するプロパティは少なく、id
、activity
、availability
の3種だけです。
👆のドキュメントはめったくそややこしいですが、動作させて確認したところこれで正しいようです。
(user's availabilityがavailibityじゃないんだ…的な)
Presenceの状態については、Teams でのユーザーのプレゼンスで確認できます。
availabilityとactivityの対応は下図の通りの認識です。
presenceの変更通知
2020年7月に変更通知に対応されました。
CreateSubscriptionにはリソースの明記はありませんが、OverViewによると/communications/presences
のようです。
presences
の取得から考えると単一ユーザー指定の/communications/presences/{id}
の指定になるようです。
IDなしやカンマ区切りの複数指定は400になりました。
また、Subscriptionの作成では有効期限を指定する必要があります。
ドキュメントに記載の通り、1時間のようです。
サブスクリプションの作成は他のリソースのときと同様、下記のようなJSONをPOSTすることで作成できます。
{ "changeType": "updated", "notificationUrl": "<エンドポイントURL>", "resource": "communications/presences/<user id>", "expirationDateTime": "<有効期限>" }
複数指定する場合は$filter
を使用して下記のように指定するようです。
"resource": "communications/presences$filter=id in ('<userid>', '<userid>'...)",
他のリソースのSubscriptionを作成する時とそこまで大きく変わるところはありませんね。
変更通知で通知される内容
Subscriptionを作成して内容を確認した結果、下記のようなデータが取得できました。
{ "value": [ { "subscriptionId": "cc87f8f1-45aa-4b33-9dd3-660bbaf3ed57", "clientState": null, "changeType": "updated", "resource": "communications/presences('<userid>')", "subscriptionExpirationDateTime": "2020-07-18T23:03:50.4305891-07:00", "resourceData": { "@odata.type": "#Microsoft.Graph.presence", "@odata.id": "communications/presences('<userid>')", "id": null, "activity": "InACall", "availability": "Busy" }, "tenantId": "<tenantid>" } ] }
activity
もavailability
も取得できているので、TeamsやEventのように別途WebAPIでリソースデータの取得などをする必要はなさそうです。
おわりに
β公開中のpresence
の取得と変更通知の使い方を見ていきました。
第 1 回 Japan M365 Dev User Group 勉強会ではこれをネタにLTする予定です。
よろしくおねがいします。