Microsoft Graphってなに？

Microsoft Graphを初めて触る方向けの資料です。
Microsoft Graphを触る上で知っておくべき Web REST APIについても解説しています。

2019/09/25 の Office365勉強会版に改訂しました。

#MicrosoftGraph
#Office365
#Microsoft365
#API
#REST
#Microservice
#SaaS

1. Microsoft Graph API ってなに？ 2019/09/25 第25回 Office 365 勉強会：Microsoft Graph API 株式会社ソントレーゾ 中村亮太
2. 自己紹介 • もともとインフラ上がりのエンジニアです。 • PowerAppsでゲーム作ったり、IoTと組み合わせたりとかしてます • 最近はPower PlatformやLogic AppsといったLow-Code関連だけ でなく、IoTとOffice365をうまく連携できないか試行錯誤 みたいなこともしてます。 R_t_A_n_M rnakamuramartiny 株式会社ソントレーゾ 取締役 最高技術責任者（CTO / Co-Founder） クラウド事業部 事業部長 ▪主催 Office 365 User Group 福岡支部 / IoT365 User Group ▪運営 JAPAN PowerApps User Group ▪YouTube Martinysystem Works Channel 中村亮太 rnakamuramartiny rtanm
3. ここで質問！ スマートフォンでこのQRコードを 読み込んでいただき アンケートにお答えください！ 私の合図があるまで送信ボタン を押さないでください
4. Microsoft Graph API とは・・・？ Office 365 (Microsoft 365)をAPI レベルで操作できるように公開されているものです 自分の情報はもちろんのこと、テナント内のすべての情報に対して 参照・追加・更新・削除を行うことができます。 ユーザー作成をチャットボットから自動生成したり・・・ 別の処理で生成されたデータをExcelファイルに出力したり・・・ 上司からのメールをTeamsのボットに通知してもらったり メールの文面から、感情を読み取って通知方法を変えてみたり・・・ Microsoft Graph API でできること
5. API・・・? 引用元：e-words (http://e-words.jp/w/API.html) 全然意味わかんね。 （ニホンゴデスカ？？）
6. ざっくりいうと・・・ API（Web API）とは、異なるサービス同士を利用者が繋ぎ易いように 各サービス事業者側が提供しているものです。 API API API API API API API
7. でも、ちょっとまって？ 作っている会社も・・・ 作っている人も違うのに どうしてつながるの？？ 不思議に思いませんか？？
8. ルールがあるのです。 Web RESTful (REpresentational State Transfer) API • 明示的にHTTPメソッドを使用すること • ステートレスであること • ディレクトリ構造に似たURIを公開すること • XMLもしくはJSONもしくはその両方を返すこと Web RESTful API のルール 引用元：IBM RESTful Webサービスの基本 (https://www.ibm.com/developerworks/jp/webservices/library/ws-restful/index.html)
9. 明示的にHTTPメソッドを使用する RFC に基づいた、HTTPプロトコル（RFC2616）の規約に従って、明示的にHTTP メソッドによる 要求に基づき、処理を行います。 メソッド名 機能 使用用途 GET 取得 データの取得に使用する POST 新規作成 新たにデータを生成したいときに使用する PUT 置換 特定の情報を置換する際に使用する（対象情報すべて変更） PATCH 更新 特定の情報を更新する際に使用する（対象情報のうち一部変更） DELETE 削除 特定の情報を削除する際に使用する https://tools.ietf.org/html/rfc2616
10. GET メソッド データを取得するときに使用します。 明日の福岡県の天気は？ 明日の福岡県の天気は晴れです
11. POST メソッド 新たにデータを登録するときに使用します 平日の朝9時に起こして 2番目のアラームを平日午前9時に設定しました ID 区分 時間 1 金曜日 7:30 2 平日 9:00
12. PUT メソッド 特定のレコードを変更します 2番目のアラームを金曜日の8時に変更して 2番目のアラームを金曜日の8時に変更しました ID 区分 時間 1 金曜日 7:30 2 平日 9:00 ID 区分 時間 1 金曜日 7:30 2 金曜日 8:00 ※Alexaでは実際にはできません
13. PATCH メソッド 特定のレコードの特定の値を変更します 2番目のアラームを9時に変更して 2番目のアラームを金曜日の9時に変更しました ID 区分 時間 1 金曜日 7:30 2 金曜日 8:00 ID 区分 時間 1 金曜日 7:30 2 金曜日 9:00 ※Alexaでは実際にはできません
14. DELETE メソッド 特定のレコードを削除します 金曜日午前9時のアラームを削除して 金曜日午前9時のアラームを削除しました ID 区分 時間 1 金曜日 7:30 2 金曜日 9:00 ID 区分 時間 1 金曜日 7:30
15. ステートレスであること サーバー側で、ユーザーのセッション状態（ステート）を保持しない。 大多数のユーザーが大量のリクエストを要求することが想定されるため、通常のWebシステムのような セッション状態管理を行っていては（ステートフル）、いくらリソースを増やしたとしても処理できる ものではない 例）あるユーザーの住所を調べたいとき ステートフル Aさんっている？ はい、いますよ 住所は？ 東京都です ステートレス Aさんっている？ はい、IDは123です ID:123の住所は？ 東京都です この人はAさんのこと 調べてるんだな AさんはID:123 状態管理は自分で 行う必要がある
16. ディレクトリ構造に似たURIを公開すること 何をしているのか一目瞭然なURIにすることで、どのシステムでも似たような構造になるように規定されており そのようなURI構造になるように推奨されています。 例1） Conf Room Adamsの情報を取得する https://graph.microsoft.com/v1.0/users?$filter=displayName eq 'Conf Room Adams' 例2）Conf Room Adams の受信しているメールのうち重要度の高いメールを取得する https://graph.microsoft.com/v1.0/users/{user_id}/messages?$filter=importance eq 'high' APIのバージョン ユーザーのこと 検索フィルター APIのバージョン ユーザーのこと メールのこと 検索フィルター 例1の結果から取 得したIDを入れる
17. XMLもしくはJSONもしくはその両方を返すこと Web上のやり取りで一般的とされているXMLもしくはJSON、いずれか片方で必ず返せるようにしておくものと し、可能であれば、どちらでも返せるようにするのが推奨とされています。 （ただし、昨今では、よく使用されているプログラム言語から、JSONのみ返すシステムが多いです） ID 名前 住所 性別 1 テスト太郎 東京都 男 2 テスト花子 沖縄県 女 <?xml version="1.0" encoding="utf-8"?> <data> <user id="1"> <name>テスト太郎</name> <address>東京都</address> <gender>男</gemder> </user> <user id="2"> <name>テスト花子</name> <address>沖縄県</address> <gender>女</gemder> </user> </data> [ { id:1, name:テスト太郎, address:東京都, gender:男 }, { id:2, name:テスト花子, address:沖縄県, gender:女 } ] XML JSON
18. ちょっとまって？？ やばくありませんか？？ システムの情報駄々洩れじゃん めっちゃ情報漏れるじゃん 便利とかそういう場合じゃなくね？
19. 安心してください。漏れませんよ！ 認証と認可というプロセスにより期限付きアクセストークンを取得し、 そのトークンを使用してアクセスすることでセキュリティを担保しています。 認可 今からリクエスト投げるわ。IDはXXXX、パスワードは*******よ。 受理しました。トークンAを発行しました。有効時間は今から3600秒までです ID:XXXXX パスワード:******* 権限：機能A 参照・変更・削除OK 機能B 参照 OK 他 NG アプリ 認可サーバ 認証 アプリ APIサーバ 機能Aのデータを2に更新。IDはXXXX、トークンはAよ。 ID:XXXX、トークン:A って機能A更新していいの？ OK 受理しました。更新OKです！ ID:XXXXX トークン：A 有効期限： 2019/09/25 20:00:00.000
20. 実際のリクエスト 例） ユーザの情報を取得する POST /XXXXXXXX.onmicrosoft.com/oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencoded client_id=ZZZZZZZZZZZZZZZZZZZZZZZZ& client_secret=YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY& grant_type=client_credentials& resource=https%3A%2F%2Fgraph.microsoft.com%2F 1. トークンの取得 { "token_type": "Bearer", "expires_in": "3600", "ext_expires_in": "3600", "expires_on": "1565453639", "not_before": "1565449739", "resource": "https://graph.microsoft.com/", "access_token": "Zx_z0E6jOhR9P6Flz58uIkOFg“ } 2. ユーザーの取得 GET /v1.0/users HTTP/1.1 Host: graph.microsoft.com Authorization: Bearer Zx_z0E6jOhR9P6Flz58uIkOFg Content-Type: application/json { "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users", "value": [ { "businessPhones": [], "displayName": "Conf Room Adams", "givenName": null, "jobTitle": null, "mail": "Adams@M365x214355.onmicrosoft.com", "mobilePhone": null, "officeLocation": null, "preferredLanguage": null, "surname": null, "userPrincipalName": "Adams@M365x214355.onmicrosoft.com", "id": "6e7b768e-07e2-4810-8459-485f84f8f204“ } ] }
21. Web RESTful APIのまとめ 1.HTTPを使う（セキュリティ上の観点からHTTPS） 2.リクエスト要求前にトークンを取得する 3.要求によっては事前に問い合わせ用のIDを取得する 必要がある 4.リクエストの結果はJSONもしくはXMLで返ってくる。
22. というわけで・・・ Microsoft Graph API も・・・ Web RESTful API の仕様に基づいて作られています
23. Microsoft Graph API を使用可能にするまでの流れ アプリケー ション登録 トークン 発行 各種Graph API 発行 1度だけ 問い合わせ毎に必要
24. アプリケーション登録 Microsoft Graph API を使用するためのアプリケーションを、Azure ADに登録します。
25. アプリケーションIDとアクセスキーの取得 トークン発行時に必要なアプリケーションIDとアクセスキーを取得します 1. アプリケーションID 2. アクセスキー 生成された後、画面を移動すると 二度と取得できなくなる
26. 権限の付与 アプリケーションに対するアクセス権限を付与します。
27. Microsoft Graph APIを使用可能にするまでの流れ アプリケー ション登録 トークン 発行 各種Graph API 発行
28. トークン発行 トークン発行は、以下の内容を含むHTTPSリクエストを送信することで得ることができます。 1. URL https://login.microsoftonline.com/{テナントID}/oauth2/token 2. メソッド 新規にトークンを発行するため、「POST」 3. ヘッダー key value Content-Type application/x-www-form-urlencoded 4. ボディ key value client_id アプリケーションID client_secret アクセスキー grant_type client_credentials resource https://graph.microsoft.com/
29. トークン発行 トークン発行後、問題なければ以下のような結果がJSONで返ってきます。 key value 意味 token_type Bearer トークンのタイプ（Bearer 固定） expires_in 3600 トークンの有効期間（秒） ext_expires_in 3600 トークン再発効有効期間（秒） expires_on 1565487764 トークンが切れる日時（UNIX時間） not_before 1565483864 トークンの発行した日時（UNIX時間） resource https://graph.microsoft.com/ トークン使用先リソースのURL access_token eyJ0eXAiOiJKV1QiLCJub25jZSI6Ilozdzh4c0t UYjFN…. トークン
30. Microsoft Graphを使用可能にするまでの流れ アプリケー ション登録 トークン 発行 各種Graph API 発行
31. API発行 API発行は、以下の内容を含むHTTPSリクエストを送信することで実行することができます。 1. URL 処理によって異なる（後述） 2. メソッド 処理によって異なる 3. ヘッダー key value Content-Type application/json Authorization Bearer <access token> 4. ボディ POSTやPATCHなど、データ登録や更新を行う際に 使用するデータをJSON形式で記載する
32. Microsoft Graph API の URI構造 Microsoft Graph API の URI 構造は以下のようになっています。 https://graph.microsoft.com/v1.0/users/{users-ID}/message/{message-ID}/Attachments 1次階層 1次階層 パラメータ 2次階層 2次階層 パラメータ 3次階層
33. 1次階層 主に、操作先を指定します。 値 内容 パラメータ me 使用しているアカウント自身に対して操作を行います なし users 自分以外のアカウントに対して操作を行います 対象のユーザーID groups グループに対して操作を行います 対象のグループID sites SharePointサイトに対して操作を行います 対象のsite ID applications 登録されているアプリケーションに対して操作を行います 対象のアプリケーションID security セキュリティ関連の捜査を行います なし ※ほかにもたくさんあります
34. 1次階層パラメータ Usersなどは、対象が複数前提であるため、パラメータにて対象を絞る必要があります。 パラメータはIDを指定する必要があるため、あらかじめ、一覧を取得する必要があります。 https://graph.microsoft.com/v1.0/users ID Name 1 テスト太郎 2 テスト次郎 https://graph.microsoft.com/v1.0/users/1/messages ID 宛先 件名 1 テスト太郎 ◦◦について 2 テスト太郎 明日の予定
35. 検索フィルター 複数のデータが含まれるリクエストに対して、あらかじめ検索フィルターを用いることで 戻りの結果を絞ることができます。 引用元：Microsoftクエリ パラメーターを使用して応答をカスタマイズする (https://docs.microsoft.com/ja-jp/graph/query-parameters)
36. 2次階層 1次階層により、指定可能な値が変化しますが、主に、操作機能を指定します。 値 内容 message メールに対して操作を行います calendar 予定表に対して操作を行います drive OneDriveに対して操作を行います planner Plannerに対して操作を行います joinedteams 参加しているチームを操作します manager 自分の上司の設定を操作します ※ほかにもたくさんあります
37. まずは触ってみることから始めてください。 Microsoft Graph エクスプローラー （https://developer.microsoft.com/ja-jp/graph/graph-explorer） • Office365を持ってい なくても、サンプル データで試すことが できる！（一部制限 あり） • Office365のアカウン トを使ってサインイ ンすると、より多く のクエリを試すこと ができる！ • サンプルクエリが豊 富
38. 物足りないと感じたら・・・ POSTMAN（https://www.getpostman.com/） • 認証トークンの発行もできる • トークンを発行した上での各リクエ ストを送ることができる • 取得した内容を変数に格納すること ができる • 他のAPIにも当然アクセスすること ができる
39. 私コーディングなんかできないよ！なんて人には Microsoft Flow / Logic Apps • ノーコード/ローコードで処理を作ることがで きる • 270を超えるサービスと連結できる • Microsoft Graph API も当然用意してある • 一部のものは使用できないので、そういう時 はHTTPコネクタを使ってMicrosoft Graph APIを 実行することができる