Windows Info 第94回

Microsoft Graphの中身を詳しく見る

　Microsoft Graphは、Office 365と関連のクラウドサービスに対して、統一的なAPIを提供するものだ。マイクロソフトは、過去にHailStorm（.NET Services）で同様のことを行なおうとしていたが、当時は、マイクロソフトが提唱したXML Webサービスをベースにしたものが想定されていた。しかし、Microsoft Graphは、現在の状況に合わせ、URLで機能にアクセスし、JSONで応答を返すという「モダン」な作りになっている。

マイクロソフトのサイト上にあるMicrosoft Graphの文書ページ。ややわかりにくいがページ左上の横向きの矢印をクリックするとMicrosft Graphの解説文書の目次が開く

　ただし、Microsoft Graphは発展途上にある。たとえば、ExcelとOneNoteにはアクセスできるが、WordやPowerPointのファイルにはアクセスできない。これらにアクセスするには、WordやPowerPointのVBAなどを使う必要がある。

　Microsoft Graphは、単にクラウド側の情報へのアクセスだけでなく、AI機能などを使った「推論」機能なども用意される。たとえば、OneDrive上にあるExcelのセルやOneNoteのページ、Outlook.comのメールなどにアクセスでき、さらに他のユーザーとのメールやメッセージングのやりとりなどから頻度の高いキーワードを得るといったことまで可能になっている。

　また、条件を指定した情報の取得なども可能で、たとえば、特定のファイルを最後に変更したユーザーを調べるといったことも可能。特に単一のアプリケーションのAPI（たとえば、OfficeアプリケーションにはVBAでアクセスが可能）では困難な、Office365を使う組織内のユーザーやグループ、共有ファイルなどのリソースを対象にできるため、共同作業用のアプリケーションなどを開発しやすくなる。

　Microsoft Graphの基本的な情報は、

https://developer.microsoft.com/ja-jp/graph/docs

にある。

　簡単に言えば、Microsoft Graphは「https://graph.microsoft.com/」で始まるURLが機能を表し、このURLに対してHTTPコマンドであるGET、POST、PUT、DELETEを使うことで、クラウド側にある情報にアクセスや編集をする。また、このとき、JSONと呼ばれる形式のデータで結果を得る。

　たとえば、自分が受信したメールを読み出す場合「https://graph.microsoft.com/v1.0/me/messages/」というURLに対してHTTP GETコマンドを送る。結果はJSON形式で表現される。GETコマンドは、WebブラウザでURLを開いた場合に使われてるため、イメージ的には、Microsoft GraphのAPI呼び出しは、ブラウザでウェブページを開くのに似ている。

　また、ODataと呼ばれるURL指定により、戻す情報にフィルターをかけて応答数を制限したり、検索機能で条件を満たすものだけを戻すといったことも可能。

　JSONは、構造を持つ情報を表現できるため、たとえば、メールであれば、タイトルや送信者、送信日時などの情報を個別に取り出すことができる。このため、「ユーザーのメールのタイトルだけ」といった応答を得ることも可能だ。

　また、大量の応答をまとめて返すのではなく、一定数に区切って、返す仕組みもある。これは、Googleで検索した結果がページに分かれて表示されるのと似ている。

　以下の表にMicrosoft Graphが扱う機能、情報（リソース）の概要を示す。ここに示した対象に対して、それぞれ個別のパスを持つAPIがある。

　また多くの機能は、ユーザー個別の項目であり、実際にアクセスする場合には、ユーザーを特定してMicrosoft Graphを呼び出す。具体的には、URLを

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

などとする。また、自分自身は、「me」で表現でき、この場合には

https://graph.microsoft.com/v1.0/me/calendars

などとしてAPIを呼び出せる。

　たとえば、Outlookのカレンダー機能では、複数の「予定表」があり、その中に「イベント」が登録されている。また、個々のイベントには、開始時間や場所、タイトルといった情報がある。自分の予定すべてに関しては、

https://graph.microsoft.com/v1.0/me/events

というURLがあり、すべての予定表の一覧は

https://graph.microsoft.com/v1.0/me/calendars

で得られる。

　なお、Microsoft GraphのURLでは、複数形が対象全体を表す。たとえば、「me/calendars」は、自分の予定表すべてを意味し、「me/calendar」は自分のデフォルトの予定表となる。

　こうしたURLに対するGETコマンドでは、応答としてJSON形式データが戻される。JSONとは「JavaScript Object Notation」の略で、元々はJavaScript用に作られた交換用データ表現形式である。イメージ的には、CSVのようにアプリケーション、サービス間でデータを交換する場合に利用する。表形式に特化したCSVと違い、JSONは、オブジェクトを表現できる。現在では、さまざまな言語から利用でき、インターネットのWeb APIでは標準的なデータ表現形式として使われている。

　たとえば、以下のようなものがJSONによるオブジェクトの表現だ。

{
　　"value": [
　　　　{
　　　　　　"originalStartTimeZone": "TZ-value",
　　　　　　"responseStatus": {
　　　　　　"response": "",
　　　　　　"time": "datetime-value"
　　　　　　},
　　　　　　"reminderMinutesBeforeStart": 99,
　　　　　　"isReminderOn": true
　　　　}
　　]
}

　JSONでは、ダブルクオートで囲まれたものが「文字列」、ダブルクオートがなく数字と数値用の記号（「+」や「-」、カンマ、ピリオド、指数表記用のEなど）からなるのが「数値」である。また、「"reminderMinutesBeforeStart": 99」のような表記を「メンバー」といい、“{”と“}”で囲まれたオブジェクトの要素となる。そのほか、“[”と“]”で囲まれた部分は「配列」である。

　JSONは、すべてが文字で表現されているため、環境に依存せずに数値や文字列、オブジェクト、配列を表現できる。

　実際のMicrosoft Graphの利用では、セキュリティのために正しくログインしているユーザーからのアクセスであることを示す情報（アクセストークン）をHTTPコマンドヘッダに含める必要があるが、マイクロソフトの「Graphエクスプローラー」ページ（https://developer.microsoft.com/ja-jp/graph/graph-explorer）を使うと、WebブラウザからMicrosoft Graphの機能を試すことが可能だ。次回は、このMicrosoft Graphエクスプローラーを実際に使ってみる。