トップ > Microsoft Graph > Microsoft Graph API でプレゼンスを操作する

Microsoft Graph API でプレゼンスを操作する

Microsoft Graph

Microsoft Graph API は Microsoft のクラウドリソースに対する多種多様な操作をサポートしています。

本記事では Microsoft Graph API を使用したプレゼンス操作について紹介します。

はじめに

Microsoft Graph API のプレゼンスではユーザーの現在の状態やアクティビティを取得・設定することができます。状態やアクティビティとは「連絡可能」「離席中」「会議中」等、 Microsof Teams のユーザー情報に表示されているマークのことを指します。

本記事では Microsoft Graph API のプレゼンス API について簡単に解説します。

learn.microsoft.com

プレゼンスに関連する権限一覧

まずはプレゼンス操作に必要な権限の一覧を紹介します。

プレゼンス API はアプリケーション用の Presence.ReadWrite.All を除いて、管理者の同意無しで利用することができます。

スコープ名 アプリ用 管理者の同意 説明
Presence.Read ユーザーのプレゼンス情報を読み取る
Presence.Read.All 組織内のすべてのユーザーのプレゼンス情報を読み取る
Presence.ReadWrite ユーザーのプレゼンス情報の読み取りと書き込み
Presence.ReadWrite.All ○ ○ すべてのユーザーのプレゼンス情報の読み取りと書き込み

プレゼンス API エンドポイント一覧

Microsoft Graph API で操作可能なプレゼンス情報は「状態・アクティビティ」「ステータスメッセージ」の2つです。

後者は2023年7月時点では beta バージョンの API でのみ使用可能でしたが、2023年10月時点では正式版として利用可能です。

learn.microsoft.com

ユーザーのプレゼンスの取得

HTTP
メソッド 		エンドポイント
GET /me/presence
GET /users/{id}/presence
GET /communications/presences/{id}

単一ユーザーのプレゼンスを取得するには、自身のプレゼンスであれば /me/presence を、自身以外のプレゼンスであれば /users/{id}/presence または /communications/presences/{id} を使用します。

// API実行
GET https://graph.microsoft.com/v1.0/me/presence
{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#users('00000000-0000-0000-0000-000000000000')/presence/$entity",
  "id": "00000000-0000-0000-0000-000000000000",
  "availability": "Offline",
  "activity": "OffWork",
  "outOfOfficeSettings": {
      "message": "不在メッセージ",
      "isOutOfOffice": true
  },
  "statusMessage": {
      "publishedDateTime": "2023-07-16T12:26:23.0324208Z",
      "message": {
          "content": "ステータスメッセージ",
          "contentType": "text"
      },
      "expiryDateTime": {
          "dateTime": "2023-07-16T13:00:00.0000000",
          "timeZone": "UTC"
      }
  }
}

注意事項として、 プレゼンス取得の API 呼び出しはテナント・アプリケーション単位で30秒あたり1500回まで と制限されています。

多人数のプレゼンス取得を実行する際は次項の複数人ユーザーのプレゼンス取得を利用しましょう。

availability と activity は以下の値が設定されます。この数年間で筆者が知っている値よりもいくつか増えた気がします。

種別 値
availability Available AvailableIdle Away BeRightBack Busy BusyIdle DoNotDisturb Offline PresenceUnknown
activity Available Away BeRightBack Busy DoNotDisturb InACall InAConferenceCall Inactive InAMeeting Offline OffWork OutOfOffice PresenceUnknown Presenting UrgentInterruptionsOnly

外出時の不在メッセージ outOfOfficeSettings はプレゼンスの一部として取得することができますが、これは実はメールボックスのプロパティです。 v1.0 の /users/{id}/mailboxSettings から設定・更新が可能です。

learn.microsoft.com

複数ユーザーのプレゼンスの取得

HTTP
メソッド 		エンドポイント
POST /communications/getPresencesByUserId

複数ユーザーのプレゼンスを取得するには /communications/getPresencesByUserId を使用します。

ただし、単一ユーザー取得時と異なり、ステータスメッセージの設定日時・期限が常に null となってしまう模様です。

// API実行
POST https://graph.microsoft.com/v1.0/communications/getPresencesByUserId

{
  "ids": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]
}
{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#Collection(presence)",
  "value": [
    {
      "@odata.type": "#microsoft.graph.presence",
      "id": "00000000-0000-0000-0000-000000000000",
      "availability": "Offline",
      "activity": "OffWork",
      "outOfOfficeSettings": {
        "message": "不在です",
        "isOutOfOffice": true
      },
      "statusMessage": {
        "publishedDateTime": null,
        "expiryDateTime": null,
        "message": {
          "content": "ステータスメッセージ",
          "contentType": "text"
        }
      }
    },
    {
      "@odata.type": "#microsoft.graph.presence",
      "id": "00000000-0000-0000-0000-000000000000",
      "availability": "Offline",
      "activity": "Offline",
      "statusMessage": null,
      "outOfOfficeSettings": {
        "message": null,
        "isOutOfOffice": false
      }
    }
  ]
}

注意事項として、単一ユーザーのプレゼンス取得と同様ですが プレゼンス取得の API 呼び出しはテナント・アプリケーション単位で30秒あたり1500回まで と制限されています。また API 呼び出しあたり650ユーザーまで とも制限されています。

プレゼンスの設定とクリア

HTTP
メソッド 		エンドポイント
POST /me/presence/setPresence
POST /users/{id}/presence/setPresence
POST /me/presence/clearPresence
POST /users/{id}/presence/clearPresence

ユーザーのプレゼンスを設定するには /me/presence/setPresence または /users/{id}/presence/setPresence を使用します。

後者では全てのユーザーのプレゼンスを設定することが可能ですが、自身以外のプレゼンスを設定するには管理者の同意が必要な Presence.ReadWrite.All が必要です。設定したプレゼンスを削除するには /me/presence/clearPresence または /users/{id}/presence/clearPresence を使用します。

プレゼンスの設定はユーザーに対して Teams のデスクトップクライアント、モバイルクライアント、 Web クライアントなど、アプリケーション単位でそれぞれ設定されます。複数のアプリケーションからプレゼンスが設定されている状態では、それらのプレゼンスを集約した状態になります。

また、プレゼンスにはタイムアウトと期限切れが存在します。どのアプリケーションからもプレゼンスが送信されない場合、5分単位で「連絡可能」→「一時退席中」→「不在」とステータスが自動で変化します。

アプリケーションから送信されたプレゼンスにはそれぞれ有効期限があり、それを超えると期限切れとなってクリアされます。プレゼンスを更新するアプリを実装する際はタイムアウト・期限切れとなる前にプレゼンスの再送信が必要となります。

// API実行
POST https://graph.microsoft.com/v1.0/me/presence/setPresence

{
  "sessionId": "00000000-0000-0000-0000-000000000000", // アプリケーションID
  "availability": "Available",
  "activity": "Available",
  "expirationDuration": "PT1H"
}

// ※レスポンスなし
// API実行
POST https://graph.microsoft.com/v1.0/me/presence/clearPresence

{
  "sessionId": "00000000-0000-0000-0000-000000000000" // アプリケーションID
}

// ※レスポンスなし

プレゼンスの更新 API で指定可能な availability / activity の組み合わせは以下のみに制限されています。これ以外の組み合わせを送信するとエラーになります。

availability activity 状態
Available Available 連絡可能
Busy InACall 通話中
Busy InAConferenceCall （不明）
Away Away 退席中
DoNotDisturb Presenting 応答不可（発表中）

優先プレゼンスの設定とクリア

HTTP
メソッド 		エンドポイント
POST /me/presence/setUserPreferredPresence
POST /users/{id}/presence/setUserPreferredPresence
POST /me/presence/clearUserPreferredPresence
POST /users/{id}/presence/clearUserPreferredPresence

アプリケーション毎のプレゼンスの設定では。複数のアプリケーションから設定された際にそれらを集約した状態となりますが、ユーザーを指定のプレゼンスとしたい場合は優先プレゼンスを設定します。

ただし、何らかのプレゼンスが設定されている状態で無いと効果はありません。

// API実行
POST https://graph.microsoft.com/v1.0/me/presence/setUserPreferredPresence

{
  "availability": "Available",
  "activity": "Available",
  "expirationDuration": "PT1H"
}

// ※レスポンスなし
// API実行
POST https://graph.microsoft.com/v1.0/me/presence/clearUserPreferredPresence

// ※レスポンスなし

優先プレゼンスの更新 API で指定可能な availability / activity の組み合わせは以下のみに制限されています。

プレゼンスの更新では「通話中」など現在の活動状態を指定する組み合わせでしたが、優先プレゼンスでは自身の状態の意思表示を指定する組み合わせとなっています。

availability activity 状態
Available Available 連絡可能
Busy Busy 取り込み中
DoNotDisturb DoNotDisturb 応答不可
BeRightBack BeRightBack 一時退席中
Away Away 退席中表示
Offline OffWork オフライン表示

ステータスメッセージの設定

HTTP
メソッド 		エンドポイント
POST /me/presence/setStatusMessage
POST /users/{id}/presence/setStatusMessage

ユーザーに対してステータスメッセージを設定するには /me/presence/setStatusMessage または /users/{id}/presence/setStatusMessage を使用します。ステータスメッセージとは Teams クライアントで設定できるもので、設定されているとプロフィールカードにも表示されます。

// API実行
POST https://graph.microsoft.com/v1.0/me/presence/setStatusMessage

{
  "statusMessage": {
    "message": {
      "content": "Status Message Text",
      "contentType": "text"
    },
    "expiryDateTime": {
      "dateTime": "2023-07-17T20:00:00",
      "timeZone": "Tokyo Standard Time"
    }
  }
}

// ※レスポンスなし

ステータスメッセージを削除する API はありません。有効期限を過去の日付とすることで自動的に期限切れとなり削除されます。

Teams クライアントでステータスメッセージ設定時に改行を入れるとメッセージには <br> タグが設定されていました。コンテンツ種別はテキストが設定されていますが HTML のタグが認識されているようですので、設定する際は HTML タグのエスケープ処理を必ず実施しましょう。

ちなみに、 Teams クライアントからステータスメッセージを設定する際に「他のユーザーが自分にメッセージを送るときに表示する」にチェックを入れると他のユーザーに対して自身のステータスメッセージを表示する事ができます。このチェックをオンにすると何らかのプロパティにフラグが立つのではなくメッセージの最後に <pinnednote></pinnednote> が付与されていました。

もちろん、 API 経由で <pinnednote></pinnednote> をメッセージの最後に設定すると Teams クライアントから設定した場合と同様の効果が得られます。

おわりに

Microsoft Graph API のプレゼンス API についてでした。

本記事を執筆するきっかけとなったのは、先日久しぶりに API ドキュメントを眺めていた時にステータスメッセージの設定が beta として登場していたことでした。

API の変更履歴ドキュメントいわく2022年12月頃に登場した様です。たまにドキュメントを眺めると欲しかった API が新設されていたりして夢が広がります。

執筆担当者プロフィール
中谷 大造

中谷 大造（日本ビジネスシステムズ株式会社）

情報システム部の中谷です。社内用スクラッチアプリの開発をしています。

担当記事一覧