Windows Info 第95回

Microsoft Graphの動作を確認できる「Graphエクスプローラー」を試す

Graphエクスプローラーで
Microsoft Graphの動作を確認する

　前回はMicrosoft Graphについての概説を行なったが、今回は実際の動作を見ていこう。Microsoft Graphを呼び出すプログラムを作ればもちろん試すことができるが、それはちょっと大変だ。そこでウェブブラウザから動作を試すことができる「Graphエクスプローラー」が用意されている。

みることができる

　これを使えば、用意されているサンプルアカウントで動作を見ることができるほか、自分のアカウントでログオンして自分の情報を見ることもできる。

　Microsoft Graphが対象にするのは、マイクロソフトのクラウド系サービスにあるユーザーと関連情報なのだが、2種類のアカウントを受け付ける。１つはOffice 365のアカウントで、こちらはAzure ADで管理されているものだ。この場合、対象になる情報（リソース）は、Office365とその関連サービスであるExchage OnlineやOneDrive for Businessとなる。

　もう1つのアカウントタイプはMicrosoftアカウントで、こちらはOutlook.comとOneDriveが対象となる。なお、Microsoftアカウントでは、Office365アカウントと違い契約している組織情報などが含まれない。また、アカウントが持つユーザーのプロフィール情報も限定されたものになる。その関係で、組織内のユーザー同士のやりとりを元に行なわれるMicrosoft GraphのInsight（推論）が一部動作しない。これらを試すにはサンプルアカウントを使う。

　まずは、以下のURLからGraphエクスプローラーを開いて見よう。

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

　この状態ですぐに動作が試せるので、ページ左側にあるサンプルクエリをクリックしてみよう。右側の白地の領域の上がMicrosoft Graphの機能を示すURLで下がその応答だ。

左側からサンプルクエリーを選べば、API用のURLが入力され、応答が下に表示される

　Microsoft Graphは、HTTPプロトコルを使ってURLで対象を指定、HTTPメソッドで処理方法を指定する。HTTP、Hyper Text Transfer Protocolには、GET、POST、PUT、DELETE、PATCHなどのメソッドがある。ウェブブラウザでページを開くときに使われるのがGETメソッド、アップロードを行うのがPUT、ページ内のフォームにテキストなどを入力してボタンを押したときに使われるのがPOSTメソッドなどに相当する。

　Microsoft Graphでは、GETメソッドが情報の取得、POSTが新規作成、DELETEが削除、PUTが置き換え、PATCHが部分書き換えという使い方になっている。ただし、どのメソッドが使えるのかは同時に指定するURLが示す対象（リソース）によって違う。そのあたりはすべて、Microsoft Graphのドキュメントに記載がある。これは、以下のURLで見ることが可能だ。

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

　なお、このページでは、ブラウザの横幅が狭いと左側の目次が省略表示になるので注意されたい。

応答にはJSONを使う

　GETメソッドを使うと、応答の本文（body）には、リソースに含まれる情報がJSON形式で入っている。

JSONは、文字列（ダブルクオートで括られている）や数値などの基本的な値や配列やオブジェクトといった構造を持つ値を組みあわせて複雑なオブジェクトを表現できる

　JSONとは、「JavaScript Object Notation」の略で、もともとはJavaScriptでオブジェクトデータを交換する場合のテキスト表現形式だった。この形式は、JavaScriptのeval関数で評価することで簡単にオブジェクトに変換することができた。ただし、現在では、JavaScript以外でも利用できるようになり、他の言語でも使われることが多い。特にインターネット上のサービスでは、APIで扱うデータをJSON形式としているものが多い。

　JSONは、「文字列」、「数値」、「真偽値」（trueとfalse）、「ヌル値」（null）という基本となる「値」に加え、「配列」と「オブジェクト」という構造を持つ「値」が定義されている。イメージ的には、テキストのフィールドからなるレコードを表現できるCSV（カンマ区切り形式）を拡張して複雑な構造を表現できるようにしたものといえる。

　「配列」は、要素となる「値」をカンマで区切って、“[”と“]”で囲ったもの。「オブジェクト」は、「文字列:値」という形式のメンバーをカンマで区切って“{”と“}”で囲ったものだ。配列もオブジェクトも「値」の一種なので、さらに配列やメンバーに入れることができ、複雑な構造が表現できる。

サンプルクエリを試す

　まずはサンプルクエリの「自分のメール」をクリックしてみると、大量の情報が下の領域（応答のプレビュー）に表示される。まずは、各メールの件名（subject）、受信日（receivedDateTime）、差出人（from）だけを応答させるようにしよう。それには、上部のURL欄に以下のものを入れてみる。

クエリー文字列に＄selectを指定することで、応答に含めるプロパティを制限できる

https://graph.microsoft.com/v1.0/me/messages?$select=subject,receivedDateTime,from

　元々のURLの後に「?$select=subject,receivedDateTime,from」を付けたものだ。これは、3つのフィールドだけを応答させる指示（クエリー文字列）である。

　また、メールに対して検索を行うこともできる。デフォルトでは、検索キーワードだけを指定すると、「本文」、「件名」、「差出人」が対象となる。たとえば、

https://graph.microsoft.com/v1.0/me/messages?$search=davids

とするとdavidsという単語を含むメッセージのみが返ってくる。先ほどと同じく応答させるフィールドを限定するには、「&」で後に$selectを付ける。

＄searchを使えば、応答の中から特定の文字列を含むものを取り出せる

https://graph.microsoft.com/v1.0/me/messages?$search=davids&$select=subject,receivedDateTime,from

　このクエリー文字列は、OASYSが既定したODataという仕様に準拠している。Microsoft Graphでは、下の表のようなクエリー文字列をサポートしている。

パラメーターなどについては、「OData Version 4.0. Part 2」を参照（http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html）

　Microsoft Graphでは、応答が多数の場合、リソースによっては、ページに分割されて応答が戻る。たとえば、組織内の全ユーザーに対応するusersリソースは大量の応答があるが、自分のすべてのメールme/messagesリソースは、標準では10件/ページに分割されて応答が戻る。応答が複数のページに分割されているかどうかは、応答に「@odata.nextlink」プロパティが含まれているかどうかで判断できる。また、最初から大量の応答が予想される場合、$topを使って、ページに分割して送信させることもできる。

　Microsoft Graphでは、$count=trueというクエリー文字列を付けることで、応答の総数を「@odata.count」プロパティとして応答に含めることができるが、これはdirectoryObject（Azure ADのオブジェクト。たとえばusersリソース）などに対しては適用できない。

「＄count=true」をクエリー文字列に含めると応答に「＠odata.count」というプロパティが含まれ、応答の総数を得ることができる

　大量の情報が含まれる場合、これを数え上げる負荷が大きくなるため制限があるのだと考えられる。また、総数は応答に含まれるため、事前に総数だけを知ることができない。大量の応答が返ってくる場合、場合によってはクライアント側のメモリ不足や大量の通信などを引き起こす可能性もあり、最初から$topを使って複数ページに分割してしまったほうがよい場合がある。

　これまでマイクロソフトは、クラウドサービスに対して、個々にAPIを定義してきた。たとえば、OneDrive用、Office 365用、Exchange、SharePoint、Azure ADなどだ。しかし、OneDriveのAPIなどに関しては、今後はMicrosoft Graphを介してAPIを利用することを推奨するなど、APIをMicrosoft Graphに統合しつつある。