Share
Embed
lobal Microsoft 365 Developer Bootcamp 2019 Tokyo:Microsoft Graph API
Ryota Nakamura
November 23, 2019
Transcript
47 slides
-
Microsoft Graph API 2019/11/23 Global Microsoft 365 Developer Bootcamp 2019
Tokyo:Microsoft Graph API 株式会社ソントレーゾ 中村亮太 Global Microsoft 365 Developer Bootcamp -
自己紹介 • もともとインフラ上がりのエンジニアです。 • Power Appsでゲーム作ったり、IoTと組み合わせたりとかしてます • 最近はPower PlatformやLogic AppsといったLow-Code関連だけ
でなく、IoTとOffice365をうまく連携できないか試行錯誤 みたいなこともしてます。 R_t_A_n_M rnakamuramartiny 株式会社ソントレーゾ 取締役 最高技術責任者(CTO / Co-Founder) DX推進事業部 (DX OverDrive Business Dept.) 事業部長 ▪主催 Office 365 User Group 福岡支部 / IoT365 User Group ▪運営 JAPAN Power Apps User Group JAPAN Power Virtual Agents User Group ▪YouTube Martinysystem Channel 中村亮太 rnakamuramartiny rtanm -
アジェンダ 1. What’s API?? 2. Microsoft Graph API! 3. Let’s
Challenge API! 4. Let’s Create Apps Using API! →APIってどんなものか説明します →Microsoft Graph APIの説明です →ツールを使ってMicrosoft Graph APIを試してみましょう → Microsoft Graph APIを使ったアプリを作りましょう! -
Microsoft Graph API とは・・・? Office 365 (Microsoft 365)をAPI レベルで操作できるように公開されているものです 自分の情報はもちろんのこと、テナント内のすべての情報に対して
参照・追加・更新・削除を行うことができます。 ユーザー作成をチャットボットから自動生成したり・・・ 別の処理で生成されたデータをExcelファイルに出力したり・・・ 上司からのメールをTeamsのボットに通知してもらったり メールの文面から、感情を読み取って通知方法を変えてみたり・・・ Microsoft Graph API でできること -
ルールがあるのです。 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) -
明示的にHTTPメソッドを使用する RFC に基づいた、HTTPプロトコル(RFC2616)の規約に従って、明示的にHTTP メソッドによる 要求に基づき、処理を行います。 メソッド名 機能 使用用途 GET 取得
データの取得に使用する POST 新規作成 新たにデータを生成したいときに使用する PUT 置換 特定の情報を置換する際に使用する(対象情報すべて変更) PATCH 更新 特定の情報を更新する際に使用する(対象情報のうち一部変更) DELETE 削除 特定の情報を削除する際に使用する https://tools.ietf.org/html/rfc26 16 -
PUT メソッド 特定のレコードを変更します 2番目のアラームを金曜日の8時に変更して 2番目のアラームを金曜日の8時に変更しました ID 区分 時間 1 金曜日
7:30 2 平日 9:00 ID 区分 時間 1 金曜日 7:30 2 金曜日 8:00 ※Alexaでは実際にはできません -
PATCH メソッド 特定のレコードの特定の値を変更します 2番目のアラームを9時に変更して 2番目のアラームを金曜日の9時に変更しました ID 区分 時間 1 金曜日
7:30 2 金曜日 8:00 ID 区分 時間 1 金曜日 7:30 2 金曜日 9:00 ※Alexaでは実際にはできません -
DELETE メソッド 特定のレコードを削除します 金曜日午前9時のアラームを削除して 金曜日午前9時のアラームを削除しました ID 区分 時間 1 金曜日
7:30 2 金曜日 9:00 ID 区分 時間 1 金曜日 7:30 -
ステートレスであること サーバー側で、ユーザーのセッション状態(ステート)を保持しない。 大多数のユーザーが大量のリクエストを要求することが想定されるため、通常のWebシステムのような セッション状態管理を行っていては(ステートフル)、いくらリソースを増やしたとしても処理できる ものではない 例)あるユーザーの住所を調べたいとき ステートフル Aさんっている? はい、いますよ 住所は?
東京都です ステートレス Aさんっている? はい、IDは123です ID:123の住所は? 東京都です この人はAさんのこと 調べてるんだな AさんはID:123 状態管理は自分で 行う必要がある -
ディレクトリ構造に似た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を入れる -
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 -
安心してください。漏れませんよ! 認証と認可というプロセスにより期限付きアクセストークンを取得し、 そのトークンを使用してアクセスすることでセキュリティを担保しています。 認可 今からリクエスト投げるわ。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 -
実際のリクエスト 例) ユーザの情報を取得する 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": "[email protected]", "mobilePhone": null, "officeLocation": null, "preferredLanguage": null, "surname": null, "userPrincipalName": "[email protected]", "id": "6e7b768e-07e2-4810-8459-485f84f8f204“ } ] } -
Microsoft Graph API を使用可能にするまでの流れ アプリケー ション登録 トークン 発行 各種Graph API
発行 1度だけ 問い合わせ毎に必要 -
アクセス許可 リソース Calendars Directory Mail Group 操作 Read All All
Shared Shared None None None ReadWrite All All Shared Shared None None None どのデータに アクセス するのか? どんな操作を するのか どの範囲まで アクセスする のか? アクセス許可は以下のような構造となっています。 ※アプリケーションの許可の場合はすべてALL権限 引用元:ODATA 杉本さん Office365 Graphで2種類のアクセス許可の仕様にハマった話 (http://bit.ly/O365JPCDATA) -
トークン発行 トークン発行は、以下の内容を含む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/ -
トークン発行 トークン発行後、問題なければ以下のような結果が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 eyJ0eXAiOiJKV1QiLCJub25jZSI6Ilozdzh4c 0tUYjFN…. トークン -
API発行 API発行は、以下の内容を含むHTTPSリクエストを送信することで実行することができます。 1. URL 処理によって異なる(後述) 2. メソッド 処理によって異なる 3. ヘッダー
key value Content-Type application/json Authorization Bearer <access token> 4. ボディ POSTやPATCHなど、データ登録や更新を行う際に 使用するデータをJSON形式で記載する -
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次階層 -
1次階層 主に、操作先を指定します。 値 内容 パラメータ me 使用しているアカウント自身に対して操作を行います なし users 自分以外のアカウントに対して操作を行います
対象のユーザーID groups グループに対して操作を行います 対象のグループID sites SharePointサイトに対して操作を行います 対象のsite ID applications 登録されているアプリケーションに対して操作を行います 対象のアプリケーションID security セキュリティ関連の捜査を行います なし ※ほかにもたくさんあります -
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 テスト太郎 明日の予定 -
2次階層 1次階層により、指定可能な値が変化しますが、主に、操作機能を指定します。 値 内容 message メールに対して操作を行います calendar 予定表に対して操作を行います drive OneDriveに対して操作を行います
planner Plannerに対して操作を行います joinedteams 参加しているチームを操作します manager 自分の上司の設定を操作します ※ほかにもたくさんあります -
まずは触ってみることから始めましょう! Microsoft Graph エクスプローラー (https://developer.microsoft.com/ja-jp/graph/graph-explorer) • Office365を持ってい なくても、サンプル データで試すことが できる!(一部制限
あり) • Office365のアカウン トを使ってサインイ ンすると、より多く のクエリを試すこと ができる! • サンプルクエリが豊 富 -
私コーディングなんかできないよ!なんて人には Power Automate / Logic Apps • ノーコード/ローコードで処理を作ることがで きる •
270を超えるサービスと連結できる • Microsoft Graph API も当然用意してある • 一部のものは使用できないので、そういう時 はHTTPコネクタを使ってMicrosoft Graph APIを 実行することができる