Microsoft Graphってなに？

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

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

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

Transcript

1. Microsoft Graph API ってなに？
   2019/09/25 第25回 Office 365 勉強会：Microsoft Graph API
   株式会社ソントレーゾ 中村亮太
   

   View Slide

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
   

   View Slide

3. ここで質問！
   スマートフォンでこのQRコードを
   読み込んでいただき
   アンケートにお答えください！
   私の合図があるまで送信ボタン
   を押さないでください
   

   View Slide

4. Microsoft Graph API とは・・・？
   Office 365 (Microsoft 365)をAPI レベルで操作できるように公開されているものです
   自分の情報はもちろんのこと、テナント内のすべての情報に対して
   参照・追加・更新・削除を行うことができます。
   ユーザー作成をチャットボットから自動生成したり・・・
   別の処理で生成されたデータをExcelファイルに出力したり・・・
   上司からのメールをTeamsのボットに通知してもらったり
   メールの文面から、感情を読み取って通知方法を変えてみたり・・・
   Microsoft Graph API でできること
   

   View Slide

5. API・・・?
   引用元：e-words (http://e-words.jp/w/API.html)
   全然意味わかんね。
   （ニホンゴデスカ？？）
   

   View Slide

6. ざっくりいうと・・・
   API（Web API）とは、異なるサービス同士を利用者が繋ぎ易いように
   各サービス事業者側が提供しているものです。
   API
   API
   API
   API
   API
   API API
   

   View Slide

7. でも、ちょっとまって？
   作っている会社も・・・
   作っている人も違うのに
   どうしてつながるの？？
   不思議に思いませんか？？
   

   View Slide

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)
   

   View Slide

9. 明示的にHTTPメソッドを使用する
   RFC に基づいた、HTTPプロトコル（RFC2616）の規約に従って、明示的にHTTP メソッドによる
   要求に基づき、処理を行います。
   メソッド名 機能 使用用途
   GET 取得 データの取得に使用する
   POST 新規作成 新たにデータを生成したいときに使用する
   PUT 置換 特定の情報を置換する際に使用する（対象情報すべて変更）
   PATCH 更新 特定の情報を更新する際に使用する（対象情報のうち一部変更）
   DELETE 削除 特定の情報を削除する際に使用する
   https://tools.ietf.org/html/rfc2616
   

   View Slide

10. GET メソッド
    データを取得するときに使用します。
    明日の福岡県の天気は？
    明日の福岡県の天気は晴れです
    

    View Slide

11. POST メソッド
    新たにデータを登録するときに使用します
    平日の朝9時に起こして
    2番目のアラームを平日午前9時に設定しました
    ID 区分 時間
    1 金曜日 7:30
    2 平日 9:00
    

    View Slide

12. PUT メソッド
    特定のレコードを変更します
    2番目のアラームを金曜日の8時に変更して
    2番目のアラームを金曜日の8時に変更しました
    ID 区分 時間
    1 金曜日 7:30
    2 平日 9:00
    ID 区分 時間
    1 金曜日 7:30
    2 金曜日 8:00
    ※Alexaでは実際にはできません
    

    View Slide

13. PATCH メソッド
    特定のレコードの特定の値を変更します
    2番目のアラームを9時に変更して
    2番目のアラームを金曜日の9時に変更しました
    ID 区分 時間
    1 金曜日 7:30
    2 金曜日 8:00
    ID 区分 時間
    1 金曜日 7:30
    2 金曜日 9:00
    ※Alexaでは実際にはできません
    

    View Slide

14. DELETE メソッド
    特定のレコードを削除します
    金曜日午前9時のアラームを削除して
    金曜日午前9時のアラームを削除しました
    ID 区分 時間
    1 金曜日 7:30
    2 金曜日 9:00
    ID 区分 時間
    1 金曜日 7:30
    

    View Slide

15. ステートレスであること
    サーバー側で、ユーザーのセッション状態（ステート）を保持しない。
    大多数のユーザーが大量のリクエストを要求することが想定されるため、通常のWebシステムのような
    セッション状態管理を行っていては（ステートフル）、いくらリソースを増やしたとしても処理できる
    ものではない
    例）あるユーザーの住所を調べたいとき
    ステートフル
    Aさんっている？
    はい、いますよ
    住所は？
    東京都です
    ステートレス
    Aさんっている？
    はい、IDは123です
    ID:123の住所は？
    東京都です
    この人はAさんのこと
    調べてるんだな AさんはID:123 状態管理は自分で
    行う必要がある
    

    View Slide

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を入れる
    

    View Slide

17. XMLもしくはJSONもしくはその両方を返すこと
    Web上のやり取りで一般的とされているXMLもしくはJSON、いずれか片方で必ず返せるようにしておくものと
    し、可能であれば、どちらでも返せるようにするのが推奨とされています。
    （ただし、昨今では、よく使用されているプログラム言語から、JSONのみ返すシステムが多いです）
    ID 名前 住所 性別
    1 テスト太郎 東京都 男
    2 テスト花子 沖縄県 女
    
    
    
    テスト太郎
    東京都
    男
    
    
    テスト花子
    沖縄県
    女
    
    
    [
    {
    id:1,
    name:テスト太郎,
    address:東京都,
    gender:男
    },
    {
    id:2,
    name:テスト花子,
    address:沖縄県,
    gender:女
    }
    ]
    XML
    JSON
    

    View Slide

18. ちょっとまって？？
    やばくありませんか？？
    システムの情報駄々洩れじゃん
    めっちゃ情報漏れるじゃん
    便利とかそういう場合じゃなくね？
    

    View Slide

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
    

    View Slide

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“
    }
    ]
    }
    

    View Slide

21. Web RESTful APIのまとめ
    1.HTTPを使う（セキュリティ上の観点からHTTPS）
    2.リクエスト要求前にトークンを取得する
    3.要求によっては事前に問い合わせ用のIDを取得する
    必要がある
    4.リクエストの結果はJSONもしくはXMLで返ってくる。
    

    View Slide

22. というわけで・・・
    Microsoft Graph API も・・・
    Web RESTful API の仕様に基づいて作られています
    

    View Slide

23. Microsoft Graph API を使用可能にするまでの流れ
    アプリケー
    ション登録
    トークン
    発行
    各種Graph
    API 発行
    1度だけ 問い合わせ毎に必要
    

    View Slide

24. アプリケーション登録
    Microsoft Graph API を使用するためのアプリケーションを、Azure ADに登録します。
    

    View Slide

25. アプリケーションIDとアクセスキーの取得
    トークン発行時に必要なアプリケーションIDとアクセスキーを取得します
    1. アプリケーションID
    2. アクセスキー
    生成された後、画面を移動すると
    二度と取得できなくなる
    

    View Slide

26. 権限の付与
    アプリケーションに対するアクセス権限を付与します。
    

    View Slide

27. Microsoft Graph APIを使用可能にするまでの流れ
    アプリケー
    ション登録
    トークン
    発行
    各種Graph
    API 発行
    

    View Slide

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/
    

    View Slide

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….
    トークン
    

    View Slide

30. Microsoft Graphを使用可能にするまでの流れ
    アプリケー
    ション登録
    トークン
    発行
    各種Graph
    API 発行
    

    View Slide

31. API発行
    API発行は、以下の内容を含むHTTPSリクエストを送信することで実行することができます。
    1. URL
    処理によって異なる（後述）
    2. メソッド
    処理によって異なる
    3. ヘッダー
    key value
    Content-Type application/json
    Authorization Bearer
    4. ボディ
    POSTやPATCHなど、データ登録や更新を行う際に
    使用するデータをJSON形式で記載する
    

    View Slide

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次階層
    

    View Slide

33. 1次階層
    主に、操作先を指定します。
    値 内容 パラメータ
    me 使用しているアカウント自身に対して操作を行います なし
    users 自分以外のアカウントに対して操作を行います 対象のユーザーID
    groups グループに対して操作を行います 対象のグループID
    sites SharePointサイトに対して操作を行います 対象のsite ID
    applications 登録されているアプリケーションに対して操作を行います 対象のアプリケーションID
    security セキュリティ関連の捜査を行います なし
    ※ほかにもたくさんあります
    

    View Slide

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 テスト太郎 明日の予定
    

    View Slide

35. 検索フィルター
    複数のデータが含まれるリクエストに対して、あらかじめ検索フィルターを用いることで
    戻りの結果を絞ることができます。
    引用元：Microsoftクエリ パラメーターを使用して応答をカスタマイズする
    (https://docs.microsoft.com/ja-jp/graph/query-parameters)
    

    View Slide

36. 2次階層
    1次階層により、指定可能な値が変化しますが、主に、操作機能を指定します。
    値 内容
    message メールに対して操作を行います
    calendar 予定表に対して操作を行います
    drive OneDriveに対して操作を行います
    planner Plannerに対して操作を行います
    joinedteams 参加しているチームを操作します
    manager 自分の上司の設定を操作します
    ※ほかにもたくさんあります
    

    View Slide

37. まずは触ってみることから始めてください。
    Microsoft Graph エクスプローラー （https://developer.microsoft.com/ja-jp/graph/graph-explorer）
    • Office365を持ってい
    なくても、サンプル
    データで試すことが
    できる！（一部制限
    あり）
    • Office365のアカウン
    トを使ってサインイ
    ンすると、より多く
    のクエリを試すこと
    ができる！
    • サンプルクエリが豊
    富
    

    View Slide

38. 物足りないと感じたら・・・
    POSTMAN（https://www.getpostman.com/）
    • 認証トークンの発行もできる
    • トークンを発行した上での各リクエ
    ストを送ることができる
    • 取得した内容を変数に格納すること
    ができる
    • 他のAPIにも当然アクセスすること
    ができる
    

    View Slide

39. 私コーディングなんかできないよ！なんて人には
    Microsoft Flow / Logic Apps
    • ノーコード/ローコードで処理を作ることがで
    きる
    • 270を超えるサービスと連結できる
    • Microsoft Graph API も当然用意してある
    • 一部のものは使用できないので、そういう時
    はHTTPコネクタを使ってMicrosoft Graph APIを
    実行することができる
    

    View Slide