Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Graph API の基本とPower Automateでの利用方法について

MiyakeMito
April 30, 2023

Graph API の基本とPower Automateでの利用方法について

MiyakeMito

April 30, 2023
Tweet

More Decks by MiyakeMito

Other Decks in Technology

Transcript

  1. アジェンダ 1. Microsoft Graph API とは 2. Microsoft Graph API

    の構成 3. Graph API を Power Automate で使う 4
  2. 注意 プレミアムコネクタを利用します。有料ライセンスが必要です。 運用環境での使用は許可されていませんが、開発向けプランや 開発者テナントであれば無償でお試しいただけます。 ▪ 開発者向けプラン https://powerapps.microsoft.com/ja-jp/developerplan/ ▪ Microsoft 365

    開発者テナント https://developer.microsoft.com/ja-jp/microsoft-365/dev- program ▪ Microsoft 365 開発者プログラムを登録してみよう(ようさん) https://www.youtube.com/watch?v=6nCSihZwYuI ▪ Microsoft 365 と Power Platform 開発環境の作り方 (りなたむさん) https://github.com/rnakamuramartiny/HowToM365- PPFDevelopEnvironment
  3. Graph APIとは ① ◼ Microsoft クラウド内の豊富なデータを取得、更新できる RESTful Web API ◼

    単一なエンドポイントを提供 https://graph.microsoft.com Graph API アプリ 8 8
  4. Graph APIとは ② Microsoft 365 User, Groups, Organizations Outlook /

    Exchange SharePoint, OneDrive Teams Planner To Do Excel OneNote Delve Microsoft Search Viva Learning Viva Insights Bookings アクセス可能なソリューション Windows 10,11 Activities Device Relay Commands 通知(Notification Hubs) Enterprise Mobility + Security Azure AD Intune Identity Protection Microsoft 365 Defender Microsoft Defender for Cloud Apps Microsoft Defender for Endpoint Microsoft Defender for Identity Microsoft Defender for Office 365 Microsoft Purview DLP Microsoft Purview 電子情報開示 Microsoft 365 Lighthouse Dynamics 365 Business Central など https://learn.microsoft.com/ja-jp/graph/overview-major-services 9
  5. Power Automate コネクタ vs Graph API 操作範囲 取得できる 情報(項目) 手軽さ

    自由度 コスト Power Automate Microsoft 365 Azure Web APIを備えた サービス 少ない (Graph APIの同等 の機能に比べて) 手軽 (Graph APIの同等 機能をPower Autoamteで利用す る場合に比べて) 低 (各コネクタの仕様 (パラメータ等)に 従うため) プレミアムコネクタ 利用のために、有償 ライセンスが必要 (一部を除く) Graph API Microsoft 365 AAD EMS Windows など 多い 複雑 高 (メソッド、リソー ス、クエリパラメー タの組み合わせで、 できることが多い) ユーザー サブスク リプション ライセ ンス内で利用可能 (*1) (一部で従量課金) (*1) 以下を含む • Microsoft 365 and Microsoft Office 365 • Microsoft Azure • Microsoft Dynamics 365 10
  6. Power AutomateでGraph API 要件に対する提供コネクタ 機能を共有 1. 提供コネクタを利用 2. カスタムコネクタを利用 3.

    HTTPアクション または HTTP要求を呼び出します ある Power Automateで Microsoft クラウド内のデータにアクセスしたい 共有する ない 共有しない Power Automate 機能でできなきいことをGraph APIで実現しよう! 11
  7. Graph API リクエストの構成 {HTTP method} https://graph.microsoft.com/{version}/{resource}?[query_parameters] エンドポイント リソースのセグメントまたはパス users, groups,

    devices, organization など me:サインインしているユーザー myOrganization:サインインユーザーの所属テナント クエリ パラメーター(省略可能) $filter や $select など OData クエリ オプション または REST メソッド パラメーター HTTP メソッド GET, POST, PATCH, PUT, DELETE バージョン v1.0 (GA) と beta (Preview) Microsoft Graph APIの書き込み要求 のサイズ制限は 4 MB です 13 他に、要求ヘッダ、要求本文も 構成に含まれます
  8. Graph API の 構成 -HTTPメソッド メソッド 説明 GET リソースからデータを読み取ります。 POST

    新しいリソースを作成、または処理を実行します。 PATCH リソースを新しい値で更新します。 PUT リソースを新しいものと置換します。 DELETE リソースを削除します。 14 ◼ POST、PATCH、および PUT は、通常 JSON 形式の要求本文が必要 要求本文には、リソースのプロパティの値などの追加の情報が含まれる ◼ GET と DELETE は、要求本文は不要
  9. Graph API の 構成-リソース① 15 ◼ リソースの階層構造 https://graph.microsoft.com/v1.0/users/{id | userPrincipalName}/mailFolders/{id}/messages/{id}

    第1セグメントリソース 第2セグメントリソース 第3セグメントリソース 第1セグメントパラメータ 第2セグメントパラメータ 第3セグメントパラメータ ◼ 取得イメージ https://graph.microsoft.com/v1.0/users ID userPrincipalName 1 [email protected] 2 [email protected] 3 [email protected] https://graph.microsoft.com/v1.0/users/[email protected]/mailFolders ID userPrincipalName ID mailFolders/displayName 1 [email protected] 1 Inbox 1 [email protected] 2 Deleted Items 1 [email protected] 3 Archive
  10. Graph API の 構成-リソース② 16 ◼ 第1セグメントで指定可能なリソース(の一部) 値 対象 パラメーター

    me 使用しているアカウント なし users Azure AD のユーザー アカウント 対象ユーザーのIDやUPN groups 動的配布グループを除くすべてのグループ 対象グループのID sites SharePoint サイト 対象のサイトID applications Azure AD に登録されているアプリケーション 対象のアプリケーションID security セキュリティソリューション なし admin ブラウザー管理、サービス正常性など なし education 教育機関のシナリオと関連する情報 なし invitations ゲスト招待 なし identityProtection ID ベースのリスクを検出、調査、修復 なし informationProtection 脅威評価 なし 1階セグメントで指定可能なリソースは 限定されています
  11. Graph API の 構成 -クエリパラメータ 17 ◼ 応答で返されるデータの量を指定したり制御したりするために使用する 値 対象

    パラメーター $count 一致するリソースの総数を取得します。 /me/messages?$top=2&$count=true $expand 関連リソースを取得します。 /groups?$expand=members $filter 結果 (行) をフィルターします。 /users?$filter=startswith(givenName,'J') $format 指定したメディア形式で結果を返します。 /users?$format=json $orderby 結果を並べます。 /users?$orderby=displayName desc $search 検索条件に基づいて結果を返します。 /me/messages?$search=pizza $select プロパティ (列) をフィルターします。 /users?$select=givenName,surname $skip 結果セットへのインデックス。 また、ページングを実装するために一部の API で使用 され、と一緒 $top に使用して結果を手動でページできます。 /me/messages?$skip=11 $top 結果のページ サイズを設定します。 /users?$top=2 https://learn.microsoft.com/ja-jp/graph/query-parameters?tabs=http ➢ クエリパラメータ(URL セグメントで指定) 値 対象 パラメーター $count コレクションの整数の合計を取得します。 GET /users/$count GET /groups/{id}/members/$count $ref コレクションに対するエンティティ メンバーシップーを更新します。 POST /groups/{id}/members/$ref $value 項目のバイナリ値を取得または更新します。 GET /me/photo/$value $batch 複数の HTTP 要求をバッチ要求に結合します。 POST /$batch OData のシステム クエリ オプション が使えます ➢ クエリパラメータ(GET の クエリパラメータで指定)
  12. Microsoft Graph の従量制課金 API 18 ◼ Microsoft Graph には、従量制課金される API

    が含まれる ◼ 従量制課金 API とサービスでは、使用量に基づいてコストが発生する API 課金とライセンス情報 Teams チャット のエクスポート Teams API の支払いモデルとライセンス要件 Teams チャネルの エクスポート Teams API の支払いモデルとライセンス要件 Teams チャット/チャネル 変更通知 Teams API の支払いモデルとライセンス要件 Teams conversationMember の変更通知 Teams API の支払いモデルとライセンス要件 Teams チャット/チャネル メッセージ PATCH 操作 Teams API の支払いモデルとライセンス要件 SharePoint と OneDrive for Business assignSensitivityLabel API 呼び出しあたり $0.00185 (USD) https://learn.microsoft.com/ja-jp/graph/metered-api-overview
  13. DEMOします ▪ ゲストを招待する https://docs.microsoft.com/ja-jp/graph/api/invitation-post?view=graph-rest-1.0&tabs=http ▪ ライセンスを割り当てる https://docs.microsoft.com/ja-jp/graph/api/user-assignlicense?view=graph-rest-1.0&tabs=http ▪ パスワードを変更する https://docs.microsoft.com/ja-jp/graph/api/passwordauthenticationmethod-

    resetpassword?view=graph-rest-beta&tabs=http ▪ Intune 業務用デバイスIDを登録する https://docs.microsoft.com/ja-jp/graph/api/intune-enrollment-importeddeviceidentity- importdeviceidentitylist?view=graph-rest-beta Graphを利用すると 例えばこんなことができます 20
  14. Graph Explorer ▪ https://developer.microsoft.com/ja-jp/graph/graph-explorer ▪ GUI を使って実際に Graph を触れるツール ▪

    委任されたアクセス許可で実行される ▪ サンプルアカウントで の実行も可能 22
  15. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 これが 一番手軽 Graph API 実行 パターン1 パターン2 パターン3 23
  16. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 Graph API 実行 パターン1 パターン2 パターン3 いまココ! 25
  17. Power AutomateでGraph API 「委任されたアクセス許可」が可能? NO Power Automateで Graph API を呼びたい

    権限エラーなど YES 実行可能 パターン1 パターン2 パターン3 強力な権限が必要な 要求は難しい アプリ登録が不要なアクション で実行
  18. APIの呼び出し ① HTTP with Azure AD コネクタ > HTTP要求を呼び出します アクション

    https://graph.microsoft.com https://graph.microsoft.com 27 プレミアムコネクタです
  19. ノンプレミアムな呼び出し① Office 365 Groups > HTTP 要求を送信します HTTPメソッド URI 要求本文

    Defaultでコンテンツタイプの指定が されていてるので嬉しい! ヘッダー 2023/08 現在 Power Automateで利用不可となりました
  20. リソース URI 操作 me Users ユーザー users ユーザー情報取得 〇 〇

    ユーザー情報更新 × × パスワード変更 × × 差分を取得する 〇 〇 組織 directory ライセンス割り当て × × 削除済みオブジェクトの取得 × × ゴミ箱から削除 × × ゴミ箱から復元 × × グループ groups ユーザーがダイレクト メンバーになっているグループ、ディレクトリ ロール、管理 単位を取得 〇 〇 追加・更新・削除 〇 - メンバーの追加・削除 〇 - Office Graph分析情報 insights ユーザーと共有されるドキュメントの一覧を含む計算された分析情報 〇 × 人気上昇中 〇 〇 ユーザーが表示または変更したドキュメント 〇 〇 メッセージ message メールボックス内のメッセージを取得 〇 〇 メールの送信 〇 〇 ユーザーの受信トレイに定義されているすべての messageRule オブジェクト 〇 × カレンダー calendar 予定の取得 〇 〇 event イベントの作成 × × Outlookの設定 mailboxSettings メールボックスの設定を取得 〇 × メールボックスの設定を更新 × × Todo todo To-doタスクリスト取得 〇 × To-doタスクリスト作成 〇 × Office 365 Groups > HTTP 要求を送信します がサポートするリソース ① 2023/08 現在 Power Automateで利用不可となりました
  21. リソース URI 操作 me Users 連絡先 contacts 連絡先の取得 〇 ×

    連絡先の作成 〇 × 委任された権限の付与 oauth2PermissionGrants oauth2PermissionGrants を一覧表示する × × Onenote onenote 作成 × × 取得 × × OneDrive drive OneDriveを取得する 〇 × SharaPoint sites サイトを取得する 〇 - リストの情報を取得 〇 - リストの作成・更新・削除 × - Teams teams チームの作成/編集 〇 - チームの削除(グループ削除) 〇 - 所属チームの一覧取得 〇 〇 チームをアーカイブ 〇 - メンバーの操作 〇 - チャネルの一覧取得 〇 - チャネルの作成・削除 〇 - chats メッセージの取得 × × セキュリティ security アラートの取得 × - security セキュリティスコア取得 × - informationProtection 脅威評価取得 × - Office 365 Groups > HTTP 要求を送信します がサポートするリソース ② 2023/08 現在 Power Automateで利用不可となりました
  22. ノンプレミアムな呼び出し② Office 365 Groups > HTTP 要求 V2 を送信する ➢

    第 1 セグメントでgroups リ ソースのみサポート 前述の[HTTP 要求 を送信する]に 比べると随分と貧弱です
  23. ノンプレミアムな呼び出し③ Office 365 Outlook > HTTP 要求を送信します(プレビュー) ➢ 以下のリソースをサポート •

    第 1 セグメント: /me, /users/ • 第 2 セグメント: messages、 mailFolders、 events、 calendar、 calendars、 outlook、 inferenceClassification
  24. ノンプレミアムな呼び出し③ Office 365 Users > HTTP 要求を送信します ➢ 以下のリソースをサポート •

    第 1 セグメント: /me, /users/ • 第 2 セグメント: messages、 mailFolders、 events、 calendar、 calendars、 outlook、 inferenceClassification
  25. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 Graph API 実行 パターン1 パターン2 パターン3 ここ! 38
  26. アプリをAzure ポータル(Microsoft ID プラット フォーム)に登録 Microsoft Entra 管理センター Microsoft Entra

    ID ➢ アプリケーション ➢ アプリの登録 アプリを Azure に登録① 39
  27. アプリを Azure に登録② クライアントシークレット追加 アプリの登録 ➢ 証明書とシークレット シークレットの有効期限は最長24ヶ月 New-AzureADApplicationPasswordCredential コマンドで無制限にできる

    (2023年7月時点) 初回作成時のみ表示 画面を閉じると再表示されないので注意 40 https://jpazureid.github.io/blog/azure-active- directory/azuread-clientsecrets-202104/
  28. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 Graph API 実行 パターン1 パターン2 パターン3 いまココ! 42
  29. 委任されたアクセス許可 ◼ HTTP with Azure ADコネクタ > HTTP要求を呼び出します ◼ HTTP

    with Azure AD コネクタはある程度の権限を保持している ➢ 実行できる権限スコープの一覧は公開されていない ➢ フローを実行した際に権限エラーが発生する場合、アプリケー ションの許可を利用する、またはトークンを取得する必要がある 私の権限で実行して どうぞ 47
  30. アプリケーションの許可 ◼ HTTP > HTTP ◼ Azure AD にアプリを登録する必要がある ➢

    フローから Active Directory OAuth で認証する 私が実行します 48
  31. アクセス許可の名前付けパターン ▪ [リソース].[操作].[制約] の組み合わせ ➢ [リソース] User:ユーザーに対して Group:グループに対して Sites:サイトコレクションに対して Mail:メールに対して

    など ➢ [操作] Read:読み取り ReadWrite:編集 など ➢ [制約] ALL > Shared > なし の順に操作できる範囲が狭くなる All, AppFolder, OwnedBy, Selected, Shared, Hidden など 49 https://learn.microsoft.com/ja-jp/graph/permissions-overview?tabs=http#permissions-naming-pattern
  32. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 Graph API 実行 パターン1 パターン2 パターン3 ココ!
  33. アクセストークンを発行 ③ POST https://login.microsoftonline.com/common/ oauth2/v2.0/token Content-Type : application/x-www-form-urlencoded client_id={アプリケーション(クライアント)ID} &scope=offline_access%20user.read

    &code={認証コード} &redirect_uri=http%3A%2F%2Flocalhost%2Fm yapp%2F &grant_type=authorization_code &client_secret={クライアントシークレット} 55 プレミアムコネクタです
  34. アクセストークンを発行 ⑤ POST https://login.microsoftonline.com/common/ oauth2/v2.0/token Content-Type : application/x-www-form-urlencoded client_id={アプリケーション(クライアント)ID} &scope=offline_access%20user.read

    &refresh_token={リフレッシュトークン} &redirect_uri=http%3A%2F%2Flocalhost%2F myapp%2F &grant_type=refresh_token &client_secret={クライアントシークレット} 57 プレミアムコネクタです
  35. トークンの発行サイクル 承認要求 認可コード リフレッシュ トークン リフレッシュ トークン リフレッシュ トークン リフレッシュ

    トークン アクセス トークン アクセス トークン アクセス トークン アクセス トークン アクセストークン発 行時に、リフレッ シュトークンも併せ て発行されるよ 初 回 の み 問 い 合 わ せ の 度 に 58
  36. 認可サーバー APIのセキュリティ ▪ OAuth2.0 ① 許可申請 クライアント ② 権限付与確認 ③

    許可 ④ 認可コード発行 利用権でアクセス ⑤ アクセストークン リクエスト ⑥ アクセストークン 取得 そうだよ リソースサーバの API使いたい ID Pass 知ってるクライアント? 許可されたよ 許可権を利用権 にかえて 利用権だよ ⑦ APIへ アクセス ⑧ リソース取得 やったぜ! リソースオーナー リソースサーバー Graph API 59
  37. アクセストークン発行 ROPC POST https://login.microsoftonline.com/ {ディレクトリ (テナント) ID}/oauth2/token Content-Type : application/x-www-form-urlencoded

    grant_type=password &resource=https://graph.microsoft.com &client_id={アプリケーション(クライアント)ID} &username={実行ユーザーID} &password={実行ユーザーパスワード} &client_secret={クライアントシークレット} ROPC権限は1アクションでアクセストークンを取得できるけど、 フローにユーザーID/パスワードとクライアントシークレットを設定するので注意!! 60 プレミアムコネクタです
  38. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 Graph API 実行 パターン1 パターン2 パターン3 ココ! 61
  39. Graph API 実行 HTTPメソッド URI Authorization : Bearer {アクセストークン} 要求本文

    Content-type : application/json body(HTTP')?['access_token'] 62 プレミアムコネクタです
  40. Power Automateで利用する手順 アプリの登録 アプリにアクセス許可を付与 アプリケーションの 許可でAPI実行 委任されたアクセス許可でAPI実行 初 回 の

    み 問 い 合 わ せ の 度 に Graph API 実行 Graph API 実行 アクセストークン 発行 Graph API 実行 パターン1 パターン2 パターン3 ココ! 64
  41. トークンを発行 ◼ 「アプリケーションの許可」の場合 POST https://login.microsoftonline.com/ {ディレクトリ (テナント) ID}/oauth2/token Content-Type :

    application/x-www-form-urlencoded grant_type=client_credentials &resource=https://graph.microsoft.com &client_id={アプリケーション(クライアント)ID} &client_secret ={クライアントシークレット} 65
  42. 66 トークンを発行しGraph API 実行 本文 HTTPメソッド URI なし Host :

    graph.microsoft.com Authorization : Bearer {アクセストークン} body(HTTP')?['access_token'] 事前にトークンを発行する と、 アプリケーションIDやクラ イアントシークレットを使 わずに実行可能です
  43. トークンを発行しないでGraph API 実行 {ディレクトリ (テナント) ID} {クライアントシークレット} HTTPメソッド URI Content-type

    : application/json 要求本文 {アプリケーション(クライアント)ID} Acrive Directory Oauth を選択 https://graph.microsoft.com シークレットを選択 67
  44. ご参考に ▪ Power Automate で Graph API の「委任されたアクセス許可」でアクセス トークンを発行する方法 https://qiita.com/MiyakeMito/items/a768841d76d22544a4c6

    ▪ Power Virtual Agents と Power Automate でユーザーのパスワードリセット するチャットボット作成【情シスボットシリーズ①】 https://qiita.com/MiyakeMito/items/e433059661dbfcd4fdf4 ▪ Power Virtual Agents と Power Automate でユーザーにライセンスを付与す るチャットボット作成【情シスボットシリーズ②】 https://qiita.com/MiyakeMito/items/6595dffc3a97a2f92d7c https://qiita.com/MiyakeMito 71