Share
Embed
カスタム コネクタとは
MiyakeMito
August 27, 2022
Transcript
74 slides
-
Power Automate と Power Virtual Agents で ゲームを作ってます ⚫ オセロ
⚫ 神経衰弱 ⚫ どうぶつしょうぎ ⚫ WORDL 5 -
本日の参考サイト ▪ 【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 -
注意 カスタム コネクタを利用するには、有料ライセンスが必要です。 運用環境での使用は許可されていませんが、開発向けプランや 開発者テナントであれば無償でお試しいただけます。 ▪ 開発者向けプラン 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 -
カスタム コネクタとは ① ◼ コネクタとは API のラッパーまたはプロキシであり、 REST API と
Power Platform 間でデータ連携するための接続 ◼ 独自のトリガーとアクションを備えたコネクタを作成し、共有 できる ◼ あらかじめ準備されたコネクタが利用できないサービスと通信 する場合に構築する Custom connectors A P I サービス 10 -
カスタム コネクタとは ② いつ? コネクタ が存在しない ときに どこで? Power Automate
Power Apps Logic Apps なにを? Actionと Trigger どのように? なぜ? だれが? 対応するライ センスを持つ ユーザー ウィザードの他 OpenAPI や Postman collection等から作成可能 利用方法は標準コネクタと同じ 作成したコネクタは組織内だけでなく世界中で共有可能 独自のアクションやトリガーを構成するため API連携の度にURIや認証情報を設定するのは手間だから コネクタの共有すれば非開発者もAPIに連携可能なので 11 -
カスタム コネクタという手段 事前構築済(標準)コネクタ コネクタを共有 1. 事前構築済(標準)コネクタを利用 2. カスタム コネクタを利用 3.
HTTPアクション ある Power Automateで外部サービスを呼びたい 共有する ない 共有しない 13 -
事前構築済(標準)コネクタ ▪ 標準コネクタ+プレミアムコネクタ ▪ 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 -
HTTPアクション ▪ HTTPアクション による API連携 が可能 ▪ Power Automate から
HTTPリクエスト する際に利用 ▪ 認証オプション – 基本(HTTP認証) – クライアント証明書 – Active Directory Oauth – Raw(未加工) 15 -
だれが? ▪ 作成 ➢ ユーザーごとに − 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 -
なにを? ▪ Action ➢ API へのリクエスト ➢ Action 毎の表示/非表示 ➢
リクエストURI ,パラメータ,ヘッダー,本文 を構成 ➢ 応答 を設定すると、[動的コンテンツ]として表示 (Power Automate) ▪ Trigger ➢ Webhook トリガー ➢ ポーリング トリガー 19 -
なにを?-Trigger トリガー リアル タイム 起動タイミング 動作 API 仕様への 要求 Webhook
トリガー 〇 トリガー条件 が揃ったら サービス ⇒ カスタム コネクタ のプッシュに応答 複雑 ポーリング トリガー × 定期的に実行 カスタム コネクタ ⇒ サービス へ前回との差分を要求 シンプル Power Apps では 使用できません 20 -
Webhook トリガー APIで下記のWebhookエンドポイントが 実装されている必要あります ➢ 登録 応答(201)に Location HTTP ヘッ
ダーが含む必要がある ➢ 通知 イベント毎に、POST 要求を発行し、 メッセージの本文で関連データを渡す ➢ 削除 登録時に応答した Location HTTP ヘッダー内の webhook パス への Delete 要求を処理できること https://docs.microsoft.com/ja-jp/connectors/custom-connectors/create-webhook-trigger 21 -
ポーリング トリガー API はフィルター処理によるデータの抽出が可能 であること パラメーターの値に基づいて、データの増分を返 す必要があるため ➢ トリガー作成/更新時 APIは現在のデータをすべてコネクタに返す
➢ トリガー起動(タイマー)時 APIは前回の呼び出し以降に更新されたデー タをコネクタに返す ➢ 一定期間フローをOFFし、再びONするとその 期間中のすべてのアイテムがトリガーされる https://docs.microsoft.com/ja-jp/connectors/custom-connectors/create-polling-trigger 22 https://tana-techlog.net/?p=201 (たな姐さん) -
プロセスフロー APIの識別または ビルド コネクタの 構築 コネクタの 利用 認定/オープ ンソース •
APIの仕様確認(要求、応答、認証) • Opne API や Postman コレクション の取得 • Microsoft Azure Functions、Azure App Service 等 REST API をホストできるテクノロジによるAPIの構築 • カスタム コネクタは標準コネクタと同じ方法で使用可 • 組織内での共有 • 構築環境と異なる環境へのコピー • データ損失防止(DLP)ポリシーによる管理 • トリガー、アクションの設計および実装 • クエリ、本文に含むパラメータ設定 • 利用者の利便性を高める設計 • 認証を実装 • 独立発行者 の認定プロセスによるMicrosoftの認定 • 認定(検証済み)発行者 の認定プロセスによるMicrosoft の認定 24 -
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
NHKの番組をゆるく検索できる PowerAppsでつくってみた https://qiita.com/MiyakeMito/items/a0c6b8b293463392fd35 NHK番組見逃し防止機能をPower Apps と Automate で作成 https://qiita.com/MiyakeMito/items/1597ba6590014a042b90 -
構築方法 ▪ 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 -
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 -
APIのエンドポイント(URI) 全般 30 カスタム コネクタの構成 ➢ コネクタが API の操作とデータ構 造を認識できるように、接続した
い API について記述する https://make.powerautomate.com/ または https://make.powerapps.com/ の左ペイン から アイコン設定 おすすめです -
認証 ① ▪ 認証なし: – 匿名アクセス ▪ 基本認証 – IDとパスワード
▪ OAuth 2.0 – 認証のための業界標準プロトコル AAD,GitHub,Dropbox、Slack など ▪ API キー – Webサービスの一般的な認証スキーム – API公開元より提供される認証情報 ▪ Windows認証 – オンプレミス データ ゲートウェイを使用する接続で利用 Oauth 2.0 31 -
セキュリティ - APIキー の場合 API キー API の仕様による API の仕様による
ヘッダー:リクエストヘッダーにAPIキーを指定する場合 クエリ:URIのクエリパラメータにAPIキーを指定する場合 任意(「API キー」でいいよ) 32 -
セキュリティ - 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 -
Graph API with カスタム コネクタ Graph API との接続をカスタム コネクタで作成した場合、 Power
Automate 側での実行がエラーになる場合があります。 Power Automate カスタム コネクタ からMicrosoft Graph REST API passwordAuthenticationMethod: resetPasswordを使ってみた (sys_zeroさん) https://www.syszero.net/post/graphcustomconnert/ 34 -
定義 - アクション - 全般 概要: Power Automate でのアクション名 アクションのID:Power
Apps での関数名 アクションの表示 Important:優先、コネクタを選ばなくても表示 コネクタを選んだ際、先頭に表示 None :規定:通常通り表示 Advanced :Noneとほぼ同等 Internal :非表示 説明:Power Automate での info やヘルプで表示される内容 36 -
定義 - アクション - 要求 パラメータの構成により、ユーザーがアクション を使用するときに表示される情報を制御できる ▪ アクションの API
リクエストの際に、受け渡すパラメー ターを定義 37 -
定義 - アクション – 要求 パラメータ ヘッダーやボディのパラメータを 編集 必須入力 とするか
型 と 書式 ※次スライドで説明 入力候補をドロップダウンで選択可能とする場合に設定(次々スライドで説明) パラメータの表示 Important:リストの先頭に表示 None :通常通り表示 Advanced :[詳細オプションを表示する]で展開すると表示 Internal :非表示 既定値を 設定可能 概要:パラメータタイトル 説明:プレースホルダ APIの仕様に合わせる 39 API定義に合わせる -
パラメータの型と書式 種類 書式 バリデー ション 説明 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 -
パラメータの入力値をリスト化 ② HOT PEPPER グルメ API https://webservice.recruit.co.jp/doc/hotpepper/r eference.html ▪ ドロップダウンの種類
ー ダイナミック ➢ クエリパラメータの設定値を、APIから取得するとき等 グルメサーチの検索エリア コードを取得するための APIが存在する 要求を定義し、 表示する応答パラメータを指定 42 -
定義 - アクション – 応答 各プロパティに明確な名前や説明、表示/非表示 など設定すると、利用者の利便性が上がる ▪ API からの応答を定義すると、動的なコンテンツ
として 各プロパティが選択可能 設定は必須ではない です。 動的コンテンツにす るならJSONの解析で も可能です。 43 -
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 -
定義 - アクション – 応答 パラメータ ヘッダーやボディのパラメータを編集 型 と 書式
• String • Integer • Number • Boolean が選択可能 [動的なコンテンツを追加]での表示 Important:リストの先頭に表示 None :通常通り表示 Advanced :Noneとほぼ同等 Internal :非表示 タイトル:動的コンテンツ名として表示 id:内部的なプロパティのID APIの仕様に合わせる 45 -
定義 - アクション – 検証 ➢ 定義したアクションやトリ ガーを検証 ➢ 検証に成功しないと、コネク
タの保存は不可 ➢ 検証に成功しても、Swagger エディター上でエラーになる こともある 46 -
定義 - ポリシー 例)「Set property」テンプレートを使用し、 API の応答にプロパティを追加する ▪ ランタイムでトリガーとアクションの動作を変更可能 用意された複数のテンプレートの
セットから動作を選びます https://docs.microsoft.com/ja-jp/connectors/custom-connectors/policy-templates 47 -
定義 – ポリシーテンプレート 名前 説明 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 -
▪ C# で記載したカスタムコードを使用可能 ▪ 要求と応答のペイロードを変換するポリシー ▪ 追加データを取得するために、外部リクエストを送信可能 コード .cs や
.csx ファイルをアップロード可能 https://docs.microsoft.com/ja-jp/connectors/custom-connectors/write-code コードレス定義よりも優先されます コードが有効をONで有効化 Policyを適用するアクションとトリガー 49 -
▪ 作成したコネクタをテスト可能 テスト ③ テストするアク ションやトリ ガーを選択する ① 新しい接続を作成 Bearer認証の場合は、
APIキーの前に"Bearer "を付与する ④ パラメータの値を 入力しテスト操作 ② 接続情報を更新する 50 -
Open API 定義から ✓ ファイルサイズは1MBまで ✓ OpenAPI 2.0 (Swagger) 形式
であること(3.0は不可) 52 -
Postman コレクション から ✓ Postman コレクションサイズは 1MBまで Postman 54 応答
の定義は作成されないため注意 -
▪ Azure APIM に登録した API からカスタム コネクタを作成 Azure API Management
から ① カスタム コネクタの作成 ➢ 発行先の環境 ➢ コネクタ名 ② サブスクリプションキーの生成 ➢ カスタム コネクタの接続で利用 56 応答 の定義は作成されないため注意 -
▪ 事前構築済(標準)コネクタ と変わりなく利用可能 Power Automate で使用する ① カスタムを選択 ③ トリガー
/ アクションを選択 ④ パラメータを入力 応答を設定していれば、サービスからの レスポンスを動的コンテンツで取得可能 59 ② カスタム コネクタを選択 -
▪ データに接続 > コネクタ 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 -
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": "NHKEテレ1", "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": "旅するためのスペイン語(19)「チリ・イースター島 受け継がれる先祖の文化」", "subtitle": "伊原六花さんと一緒に、ラテンアメリカの文化とスペイン語の多様性を体感しましょう。絶景あ り、グルメあり、ダンスあり!ネイティブとふれあって会話の上達をめざします。", "content": "第19回はチリ・イースター島。モアイだけじゃありません!この島の知られざる魅力、伝統を 守り伝えるダンスに迫ります▼私たちの身近にあった先住民言語が由来のスペイン語をご紹介。今回は動物編。▼ワークア ウトは腕立て伏せを極めます▼マンガdeスペイン語は早くも最終回。ロドリゴさんが愛してやまない「銀魂」を徹底的に 語り尽くします。こたつを「日本の奇妙なソファ」と思ったあの日…。なんとマダオのコスプレまで!?", "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 -
カスタム コネクタのDLP ▪ 環境管理者 – 環境内のカスタム コネクタを ブロック済み/ビジネス/非ビジネス に分類可能 ▪
グローバル管理者 – テナントレベルで、URLパターンで ブロック済み/ビジネス/非ビジネス/無視 にタグ付け可能 Defaultで「無視」設定なので、 「ビジネス」に分類されたコネクタと共有可能です テナント レベルのポリシーのすべ てのコネクタの DLP 分類を無視 https://docs.microsoft.com/ja-jp/power-platform/admin/dlp-custom-connector-parity 63 -
カスタム コネクタの展開 ▪ OpenAPI ファイルを Download > Import ▪ Swagger
コピー OpenAPI 定義をcopy&paste 65 -
組織内で共有 共有レベル フローでの コネクタの利用 ウィザードでの コネクタの編集 コネクタの共有 コネクタの削除 所有者 〇
〇 〇 〇 編集可能 〇 〇 〇 〇 表示+共有可能 〇 参照のみ可 〇 (「編集可能」は不可) × 表示可能 〇 参照のみ可 × × 共有なし × × × × 組織全体で共有することも可能です(共有レベルは [表示可能] 固定) ▪ 作成したカスタム コネクタを組織内で共有できる ▪ 個人、または、配布リストを除くグループに対して割り当て可能 共有先ユーザーでも、APIへの認証設定(接続の作成)が必要です 66 共有時に 設定可能 -
組織外で共有 - コネクタの認定を受ける ▪ 作成したカスタム コネクタを Microsoft 公式コネクタとして認定を受けることが可能 ▪ 認定を受けるメリットは以下
– APIを 世界中の Power Platform ユーザーに共有され認知される – Microsoft Project Coordinator Group によるコネクタの検証、品質チェック 等 ▪ 独立発行者、認定(検証済み)発行者の2種類 – コネクタの基盤となるサービスを ➢ 独立発行者:所有していない ➢ 認定発行者:所有している ◼ 認定されたコネクタは、プレミアムコネクタとしてリリースされる https://docs.microsoft.com/ja-jp/connectors/custom-connectors/submit-certification 67 -
カスタム コネクタ注意点 ◼ 名前は後から変更できません ◼ コネクタを修正後、Power Automate に反映されるまでにタイムラグが 発生することがあります ◼
要求や応答の各プロパティのデータ型は、APIに合わせないとエラーが発 生する コネクタを修正すると、既にフローに組み込み済みコネクタの動作も変わる ◼ 接続ごと、1 分あたりの要求の数 500 回まで 69 -
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