カスタム コネクタとは

Transcript

1. カスタム コネクタ について 気ままに勉強会 #29 1
2. 今日の目標 カスタム コネクタ を理解しよう 2
3. アジェンダ カスタム コネクタとは カスタム コネクタの構築 カスタム コネクタの使用 カスタム コネクタの共有 カスタム コネクタの注意点 3
4. Miyake Mito @MiTo60448639 https://qiita.com/MiyakeMito 株式会社アイシーソフト Technical Manager www.icsoft.jp https://speakerdeck.com/ miyakemito 4
5. Power Automate と Power Virtual Agents で ゲームを作ってます ⚫ オセロ ⚫ 神経衰弱 ⚫ どうぶつしょうぎ ⚫ WORDL 5
6. 本日の参考サイト ▪ 【LogicFlow-ja Online #3】#2 [Power Automate]カスタムコ ネクタ入門 https://youtu.be/qSo6GEs1mbc ▪ APIについて https://speakerdeck.com/miyakemito/apinituite ▪ Graph APIについて https://speakerdeck.com/miyakemito/graph-api-nituite 6
7. 注意 カスタム コネクタを利用するには、有料ライセンスが必要です。 運用環境での使用は許可されていませんが、開発向けプランや 開発者テナントであれば無償でお試しいただけます。 ▪ 開発者向けプラン 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 7
8. 免責事項 当スライドは、 2022年8月現在のバージョンでの情報です 今後のアップデート等により、 仕様変更する可能性があります また、私の見解による内容が含まれます 間違いなどありましたらご指摘ください 8
9. カスタム コネクタ とは
10. カスタム コネクタとは ① ◼ コネクタとは API のラッパーまたはプロキシであり、 REST API と Power Platform 間でデータ連携するための接続 ◼ 独自のトリガーとアクションを備えたコネクタを作成し、共有 できる ◼ あらかじめ準備されたコネクタが利用できないサービスと通信 する場合に構築する Custom connectors A P I サービス 10
11. カスタム コネクタとは ② いつ？ コネクタ が存在しない ときに どこで? Power Automate Power Apps Logic Apps なにを? Actionと Trigger どのように？ なぜ？ だれが？ 対応するライ センスを持つ ユーザー ウィザードの他 OpenAPI や Postman collection等から作成可能 利用方法は標準コネクタと同じ 作成したコネクタは組織内だけでなく世界中で共有可能 独自のアクションやトリガーを構成するため API連携の度にURIや認証情報を設定するのは手間だから コネクタの共有すれば非開発者もAPIに連携可能なので 11
12. いつ 使うのか？ 12
13. カスタム コネクタという手段 事前構築済(標準)コネクタ コネクタを共有 １. 事前構築済(標準)コネクタを利用 ２. カスタム コネクタを利用 ３. HTTPアクション ある Power Automateで外部サービスを呼びたい 共有する ない 共有しない 13
14. 事前構築済(標準)コネクタ ▪ 標準コネクタ＋プレミアムコネクタ ▪ Services: 700 以上 Actions : 9000 以上 Triggers : 900 以上 （2022年8月時) https://connectorinfo.z31.web.core.windows.net/apilist.html https://docs.microsoft.com/ja-jp/connectors/connector-reference/ 14
15. HTTPアクション ▪ HTTPアクション による API連携 が可能 ▪ Power Automate から HTTPリクエスト する際に利用 ▪ 認証オプション – 基本（HTTP認証） – クライアント証明書 – Active Directory Oauth – Raw（未加工） 15
16. だれが 使えるのか？ 16
17. だれが？ ▪ 作成 ➢ ユーザーごとに − 365範囲 ：1つだけ作成可能 − 有償プラン ：50個まで ▪ 利用 ➢ カスタム コネクタを含むフローの実行には有償プランが必要 https://docs.microsoft.com/ja-jp/connectors/custom-connectors/faq https://docs.microsoft.com/ja-jp/power-automate/limits-and-config 2022年8月現在 • ライセンスの有無関係なく、カスタム コネクタを含むフローが 実行できてしまう状態です。 • 有償ライセンスなしでプレミアムコネクタを実行すると、ライセン ス違反となるため気を付けてください 無料プラン（MSA）は利用不可です 17
18. なにを 作れるのか？ 18
19. なにを？ ▪ Action ➢ API へのリクエスト ➢ Action 毎の表示/非表示 ➢ リクエストURI ，パラメータ，ヘッダー，本文 を構成 ➢ 応答 を設定すると、[動的コンテンツ]として表示 (Power Automate) ▪ Trigger ➢ Webhook トリガー ➢ ポーリング トリガー 19
20. なにを？－Trigger トリガー リアル タイム 起動タイミング 動作 API 仕様への 要求 Webhook トリガー 〇 トリガー条件 が揃ったら サービス ⇒ カスタム コネクタ のプッシュに応答 複雑 ポーリング トリガー × 定期的に実行 カスタム コネクタ ⇒ サービス へ前回との差分を要求 シンプル Power Apps では 使用できません 20
21. Webhook トリガー APIで下記のWebhookエンドポイントが 実装されている必要あります ➢ 登録 応答(201)に Location HTTP ヘッ ダーが含む必要がある ➢ 通知 イベント毎に、POST 要求を発行し、 メッセージの本文で関連データを渡す ➢ 削除 登録時に応答した Location HTTP ヘッダー内の webhook パス への Delete 要求を処理できること https://docs.microsoft.com/ja-jp/connectors/custom-connectors/create-webhook-trigger 21
22. ポーリング トリガー API はフィルター処理によるデータの抽出が可能 であること パラメーターの値に基づいて、データの増分を返 す必要があるため ➢ トリガー作成/更新時 APIは現在のデータをすべてコネクタに返す ➢ トリガー起動（タイマー）時 APIは前回の呼び出し以降に更新されたデー タをコネクタに返す ➢ 一定期間フローをOFFし、再びONするとその 期間中のすべてのアイテムがトリガーされる https://docs.microsoft.com/ja-jp/connectors/custom-connectors/create-polling-trigger 22 https://tana-techlog.net/?p=201 （たな姐さん）
23. どのように 利用するのか？ 23
24. プロセスフロー APIの識別または ビルド コネクタの 構築 コネクタの 利用 認定/オープ ンソース • APIの仕様確認（要求、応答、認証） • Opne API や Postman コレクション の取得 • Microsoft Azure Functions、Azure App Service 等 REST API をホストできるテクノロジによるAPIの構築 • カスタム コネクタは標準コネクタと同じ方法で使用可 • 組織内での共有 • 構築環境と異なる環境へのコピー • データ損失防止（DLP）ポリシーによる管理 • トリガー、アクションの設計および実装 • クエリ、本文に含むパラメータ設定 • 利用者の利便性を高める設計 • 認証を実装 • 独立発行者 の認定プロセスによるMicrosoftの認定 • 認定（検証済み）発行者 の認定プロセスによるMicrosoft の認定 24
25. カスタム コネクタ の構築
26. DEMOします NHK番組表API https://api-portal.nhk.or.jp/ 全国のNHKの番組情報を提供するAPI Program List API GET https://api.nhk.or.jp/v2/pg/list/{area}/{service}/{date}.json?key={apikey} 26 ＮＨＫの番組をゆるく検索できる PowerAppsでつくってみた https://qiita.com/MiyakeMito/items/a0c6b8b293463392fd35 ＮＨＫ番組見逃し防止機能をPower Apps と Automate で作成 https://qiita.com/MiyakeMito/items/1597ba6590014a042b90
27. 構築方法 ▪ 1から作成 ▪ Open API 定義をインポート – 多くのサービス/API が Open API 定義を公開 – Ver 2.0を利用する（Ver 3.0 サポート対象外） ▪ Postman コレクションをインポート – REST API をテストするツール – v1 と v2（v2.1も） ▪ Azureからエクスポート – Azure App Service、Microsoft Azure Functions で作成されたAPI からカスタム コネクタ定義を作成 ➢ Azure API Management サービス からも作成可能 ▪ Githubからインポート 27
28. OpenAPI と Swagger ▪ OpenAPI – RESTful APIの仕様を記述するためのフォーマット – JSONやYAMLで記載する ▪ Swagger – OpenAPI を設計、構築、使用するツール群のこと ➢ Swagger Editor: API仕様書を書くためのエディタ ➢ カスタム コネクタは Swaggerエディター で構築も可能 https://docs.microsoft.com/ja- jp/connectors/custom- connectors/openapi-extensions#x- ms-visibility Swagger エディターが意外と便利 28
29. カスタム コネクタの構築 一から作成 29
30. APIのエンドポイント（URI） 全般 30 カスタム コネクタの構成 ➢ コネクタが API の操作とデータ構 造を認識できるように、接続した い API について記述する https://make.powerautomate.com/ または https://make.powerapps.com/ の左ペイン から アイコン設定 おすすめです
31. 認証 ① ▪ 認証なし: – 匿名アクセス ▪ 基本認証 – IDとパスワード ▪ OAuth 2.0 – 認証のための業界標準プロトコル AAD，GitHub，Dropbox、Slack など ▪ API キー – Webサービスの一般的な認証スキーム – API公開元より提供される認証情報 ▪ Windows認証 – オンプレミス データ ゲートウェイを使用する接続で利用 Oauth 2.0 31
32. セキュリティ - APIキー の場合 API キー API の仕様による API の仕様による ヘッダー：リクエストヘッダーにAPIキーを指定する場合 クエリ：URIのクエリパラメータにAPIキーを指定する場合 任意（「API キー」でいいよ） 32
33. セキュリティ - OAuth 2.0 の場合 Graph API の例 graph.microsoft.com 全般 セキュリティ Oauth 2.0 Azure Active Directory アプリケーション ID クライアントシークレット https://login.windows.net https://graph.microsoft.com .default カスタム コネクタを保 存すると表示される Azure AD に登録したアプリ にリダイレクトURIを設定 33
34. Graph API with カスタム コネクタ Graph API との接続をカスタム コネクタで作成した場合、 Power Automate 側での実行がエラーになる場合があります。 Power Automate カスタム コネクタ からMicrosoft Graph REST API passwordAuthenticationMethod: resetPasswordを使ってみた （sys_zeroさん） https://www.syszero.net/post/graphcustomconnert/ 34
35. 定義 - アクション ▪ コネクタで使用するアクションを定義 アクションの構成すると、ユーザーが カスタム コネクタからアクションを選 択するときの表示情報を制御できる 35
36. 定義 - アクション - 全般 概要： Power Automate でのアクション名 アクションのID：Power Apps での関数名 アクションの表示 Important：優先、コネクタを選ばなくても表示 コネクタを選んだ際、先頭に表示 None ：規定：通常通り表示 Advanced ：Noneとほぼ同等 Internal ：非表示 説明：Power Automate での info やヘルプで表示される内容 36
37. 定義 - アクション - 要求 パラメータの構成により、ユーザーがアクション を使用するときに表示される情報を制御できる ▪ アクションの API リクエストの際に、受け渡すパラメー ターを定義 37
38. 定義 - アクション - 要求 38 メソッド リクエストURL リクエストボディ リクエストヘッダー
39. 定義 - アクション – 要求 パラメータ ヘッダーやボディのパラメータを 編集 必須入力 とするか 型 と 書式 ※次スライドで説明 入力候補をドロップダウンで選択可能とする場合に設定（次々スライドで説明） パラメータの表示 Important：リストの先頭に表示 None ：通常通り表示 Advanced ：[詳細オプションを表示する]で展開すると表示 Internal ：非表示 既定値を 設定可能 概要：パラメータタイトル 説明：プレースホルダ APIの仕様に合わせる 39 API定義に合わせる
40. パラメータの型と書式 種類 書式 バリデー ション 説明 string byte base64 でエンコードされた文字 binary バイナリデータ 、本文（body）の top level でのみ指定可能 date 〇 RFC 3339 セクション 5.6 で定義されている日付表記 (例: 2022-07-27) date-time 〇 RFC 3339 セクション 5.6 で定義されている日時表記 (例: 2022-08-27T17:32:28Z) password 入力をマスクするためのUIへのヒント html HTML形式、 フローではリッチテキストエディタ integer int32 〇 符号付き 32 ビット整数 (一般的に使用される整数型) int64 〇 符号付き 64 ビット整数 ( 型) long number float 〇 浮動小数点 double 〇 倍精度の浮動小数点 boolean - 〇 フローでは、はい/いいえのドロップダウン array - item: の記載が必須 （Swaggerエディタで記載する） フローでは、Array入力エディタ 40
41. ▪ ドロップダウンの種類 ➢ 無効 ドロップダウンリストなし ➢ 静的 リテラルで、要素を設定（カンマ区切り） ➢ ダイナミック 同一コネクタ内の別アクションの 応答からリストアイテムを作成 パラメータの入力値をリスト化 ① 41
42. パラメータの入力値をリスト化 ② HOT PEPPER グルメ API https://webservice.recruit.co.jp/doc/hotpepper/r eference.html ▪ ドロップダウンの種類 ー ダイナミック ➢ クエリパラメータの設定値を、APIから取得するとき等 グルメサーチの検索エリア コードを取得するための APIが存在する 要求を定義し、 表示する応答パラメータを指定 42
43. 定義 - アクション – 応答 各プロパティに明確な名前や説明、表示/非表示 など設定すると、利用者の利便性が上がる ▪ API からの応答を定義すると、動的なコンテンツ として 各プロパティが選択可能 設定は必須ではない です。 動的コンテンツにす るならJSONの解析で も可能です。 43
44. 200 OK DATE: Thu, 14 Apr 2022 13:21:16 GMT Content-Type: application/json; charset=utf-8 { "id": "1234-1", "jsonrpc": "2.0", "result": { "word": [ { "furigana": "あいくるしい", "roman": "aikurusii", "subword": [ 定義 アクション – 応答 レスポンスボディ レスポンスヘッダ－ HTTPレスポンス 44
45. 定義 - アクション – 応答 パラメータ ヘッダーやボディのパラメータを編集 型 と 書式 • String • Integer • Number • Boolean が選択可能 [動的なコンテンツを追加]での表示 Important：リストの先頭に表示 None ：通常通り表示 Advanced ：Noneとほぼ同等 Internal ：非表示 タイトル：動的コンテンツ名として表示 id：内部的なプロパティのID APIの仕様に合わせる 45
46. 定義 - アクション – 検証 ➢ 定義したアクションやトリ ガーを検証 ➢ 検証に成功しないと、コネク タの保存は不可 ➢ 検証に成功しても、Swagger エディター上でエラーになる こともある 46
47. 定義 - ポリシー 例）「Set property」テンプレートを使用し、 API の応答にプロパティを追加する ▪ ランタイムでトリガーとアクションの動作を変更可能 用意された複数のテンプレートの セットから動作を選びます https://docs.microsoft.com/ja-jp/connectors/custom-connectors/policy-templates 47
48. 定義 – ポリシーテンプレート 名前 説明 Converts an array to an objects (preview) 要求/応答ボディのプロパティ内の配列を、指定のキーをオブジェクトキーとするオブ ジェクトに変換する Converts an objects to an array (preview) 要求/応答ボディのJSONオブジェクトを、指定したオブジェクトキー名をキーとする オブジェクトが要素の配列に変換する Set host URL ホストURL を動的にルーティングしたいときに (*1) Route request ホストURL以降のパスを動的にルーティングしたいときに(*1) サービスの同一エンドポイントに対し、複数バージョンへ要求するときなどに利用 Sets connection status to unauthenticated (preview) 特定の HTTP ステータスコードの場合、接続状況を未認証に設定する 「テスト接続」機能と組み合わせて利用 Set HTTP header 要求/応答ヘッダー の値を動的に上書き、または追加 (*1) Set property 要求/応答ボディのプロパティを追加/更新する addProperty() や setProperty() のような動作 Set query string parameter リクエストクエリのプロパティを動的に上書き、または追加 (*1) Sets header/query parameter value URL (preview) ヘッダ/クエリパラメータの値を、同一ホスト（API）内の別のエンドポイントから取 得した値で設定 Converts a delimited into array of objects (preview) 要求/応答ボディのプロパティに対し、区切られた文字列を配列に変換する Split() のような動作 （(*1)要求ヘッダ、クエリパラメータ、接続パラメータの値を代入可能） 48
49. ▪ C# で記載したカスタムコードを使用可能 ▪ 要求と応答のペイロードを変換するポリシー ▪ 追加データを取得するために、外部リクエストを送信可能 コード .cs や .csx ファイルをアップロード可能 https://docs.microsoft.com/ja-jp/connectors/custom-connectors/write-code コードレス定義よりも優先されます コードが有効をONで有効化 Policyを適用するアクションとトリガー 49
50. ▪ 作成したコネクタをテスト可能 テスト ③ テストするアク ションやトリ ガーを選択する ① 新しい接続を作成 Bearer認証の場合は、 APIキーの前に"Bearer "を付与する ④ パラメータの値を 入力しテスト操作 ② 接続情報を更新する 50
51. カスタム コネクタの構築 Open API から作成 51
52. Open API 定義から ✓ ファイルサイズは1MBまで ✓ OpenAPI 2.0 (Swagger) 形式 であること（3.0は不可） 52
53. カスタム コネクタの構築 Postman から作成 53
54. Postman コレクション から ✓ Postman コレクションサイズは 1MBまで Postman 54 応答 の定義は作成されないため注意
55. カスタム コネクタの構築 Azure API Management から作成 55
56. ▪ Azure APIM に登録した API からカスタム コネクタを作成 Azure API Management から ① カスタム コネクタの作成 ➢ 発行先の環境 ➢ コネクタ名 ② サブスクリプションキーの生成 ➢ カスタム コネクタの接続で利用 56 応答 の定義は作成されないため注意
57. カスタム コネクタ の使用
58. Power Automate で使用する 58
59. ▪ 事前構築済(標準)コネクタ と変わりなく利用可能 Power Automate で使用する ① カスタムを選択 ③ トリガー / アクションを選択 ④ パラメータを入力 応答を設定していれば、サービスからの レスポンスを動的コンテンツで取得可能 59 ② カスタム コネクタを選択
60. Power Apps で利用する 60
61. ▪ データに接続 ＞ コネクタ Power Apps で使用する ① ① データ > データに追加 ② カスタム コネクタを選択 ClearCollect(RubiCollection, KimamaniDEMO_YahooFurigana.FuriganaService( {id:"1234", jsonrpc:"2.0", method:"jlp.furiganaservice.furigana", params: {q:"漢字の振り仮名", grade:1 }})) カスタム コネクタ名.操作id名 を記載 応答（JSONオブジェクト）は コレクションに格納する Record型で指定 ClearCollect(cAPIreturn, LINEMessagingAPI.SendPushMessage( "XXXXXX", {messages:Table({type:"text", text:"from PA"}), notificationDisabled:false })) Table型で指定 61
62. API のレスポンスボディJSONは複雑なので・・・ Power Apps で使用する { "list": { "e1": [ { "id": "2022082500807", "event_id": "00807", "start_time": "2022-08-25T06:00:00+09:00", "end_time": "2022-08-25T06:25:00+09:00", "area": { "id": "130", "name": "東京" }, "service": { "id": "e1", "name": "ＮＨＫＥテレ１", "logo_s": { "url": "//www.nhk.or.jp/common/img/media/etv-100x50.png", "width": "100", "height": "50" }, "logo_m": { "url": "//www.nhk.or.jp/common/img/media/etv-200x100.png", "width": "200", "height": "100" }, "logo_l": { "url": "//www.nhk.or.jp/common/img/media/etv-200x200.png", "width": "200", "height": "200" } }, "title": "旅するためのスペイン語（１９）「チリ・イースター島 受け継がれる先祖の文化」", "subtitle": "伊原六花さんと一緒に、ラテンアメリカの文化とスペイン語の多様性を体感しましょう。絶景あ り、グルメあり、ダンスあり！ネイティブとふれあって会話の上達をめざします。", "content": "第１９回はチリ・イースター島。モアイだけじゃありません！この島の知られざる魅力、伝統を 守り伝えるダンスに迫ります▼私たちの身近にあった先住民言語が由来のスペイン語をご紹介。今回は動物編。▼ワークア ウトは腕立て伏せを極めます▼マンガｄｅスペイン語は早くも最終回。ロドリゴさんが愛してやまない「銀魂」を徹底的に 語り尽くします。こたつを「日本の奇妙なソファ」と思ったあの日…。なんとマダオのコスプレまで！？", "act": "【出演】伊原六花，セバスティアン・クラビホ，ロドリゴ・コロネル，【講師】中央大学 教授…高松 英樹，パコ・パルティーダ，【語り】勝生真沙子，エステル・モリナ", "genres": [ "1007", "1000", "1011" ] }, お供にいかがですか？ Power AppsでもJSONと仲良くなるために https://qiita.com/MiyakeMito/items/ffc c7639b2813dee77ca JSONの読み解き方 https://speakerdeck.com/miyakemito/j sonfalsedu-mijie-kifang 62
63. カスタム コネクタのDLP ▪ 環境管理者 – 環境内のカスタム コネクタを ブロック済み/ビジネス/非ビジネス に分類可能 ▪ グローバル管理者 – テナントレベルで、URLパターンで ブロック済み/ビジネス/非ビジネス/無視 にタグ付け可能 Defaultで「無視」設定なので、 「ビジネス」に分類されたコネクタと共有可能です テナント レベルのポリシーのすべ てのコネクタの DLP 分類を無視 https://docs.microsoft.com/ja-jp/power-platform/admin/dlp-custom-connector-parity 63
64. カスタム コネクタ の共有
65. カスタム コネクタの展開 ▪ OpenAPI ファイルを Download > Import ▪ Swagger コピー OpenAPI 定義をcopy&paste 65
66. 組織内で共有 共有レベル フローでの コネクタの利用 ウィザードでの コネクタの編集 コネクタの共有 コネクタの削除 所有者 〇 〇 〇 〇 編集可能 〇 〇 〇 〇 表示＋共有可能 〇 参照のみ可 〇 (「編集可能」は不可) × 表示可能 〇 参照のみ可 × × 共有なし × × × × 組織全体で共有することも可能です（共有レベルは [表示可能] 固定） ▪ 作成したカスタム コネクタを組織内で共有できる ▪ 個人、または、配布リストを除くグループに対して割り当て可能 共有先ユーザーでも、APIへの認証設定（接続の作成）が必要です 66 共有時に 設定可能
67. 組織外で共有 - コネクタの認定を受ける ▪ 作成したカスタム コネクタを Microsoft 公式コネクタとして認定を受けることが可能 ▪ 認定を受けるメリットは以下 – APIを 世界中の Power Platform ユーザーに共有され認知される – Microsoft Project Coordinator Group によるコネクタの検証、品質チェック 等 ▪ 独立発行者、認定（検証済み）発行者の２種類 – コネクタの基盤となるサービスを ➢ 独立発行者：所有していない ➢ 認定発行者：所有している ◼ 認定されたコネクタは、プレミアムコネクタとしてリリースされる https://docs.microsoft.com/ja-jp/connectors/custom-connectors/submit-certification 67
68. 注意など
69. カスタム コネクタ注意点 ◼ 名前は後から変更できません ◼ コネクタを修正後、Power Automate に反映されるまでにタイムラグが 発生することがあります ◼ 要求や応答の各プロパティのデータ型は、APIに合わせないとエラーが発 生する コネクタを修正すると、既にフローに組み込み済みコネクタの動作も変わる ◼ 接続ごと、1 分あたりの要求の数 500 回まで 69
70. Update 情報
71. REST API から Power App を 自動的に作成する https://powerapps.microsoft.com/en-us/blog/automatically-create-a-power-app-from-a-rest-api/ ▪ カスタム コネクタからキャンバス アプリが生成可能 ➢ カスタム コネクタで定義された各 POST アクションと GET アク ション ➢ アクションによって定義される入 力と出力の種類に応じたコント ロールが画面に表示される 生成にはPower Platform CLI コマンドが必要 71
72. まとめ
73. まとめ カスタム コネクタを理解すると コネクタへの理解も深まります 色々な API と連携し、 便利で面白いアプリやフローを作成してみ てください。 73
74. ありがとうございました 74