カスタム コネクタを最初から作成する

この記事は、Azure Logic Apps、Microsoft Power Automate、および Microsoft Power Apps でのカスタム コネクタの作成および使用に関するチュートリアル シリーズの一部です。

注意

カスタム コネクタの概要 を必ず読んで、プロセスを理解してください。

カスタム コネクタを作成するには、接続したい API について記述して、コネクタが API の操作とデータ構造を認識できるようにする必要があります。 このトピックでは、Postman コレクション または OpenAPI 定義 を使用せずに、最初からカスタム コネクタを作成し、Azure Cognitive Services Text Analytics API センチメント操作 (このシリーズの例) を記述します。 代わりに、カスタム コネクタ ウィザードでコネクタを完全に記述します。

API を記述する他の方法については、以下のトピックへ移動してください:

• OpenAPI 定義からカスタム コネクタを作成する
• Postman コレクションからカスタム コネクタを作成する

注意

現在、カスタム コネクタを Power Automate と Power Apps でゼロから作成できます。 Logic Apps の場合、少なくとも基本的 OpenAPI 定義または Postman コレクションで始める必要があります。

前提条件

• Cognitive Services Text Analytics API の API キー

• 次のいずれかのサブスクリプション:

  • Power Automate
  • Power Apps

カスタム コネクタ ウィザードを起動する

1. Power Apps または Power Automate にサインインします。

2. 左側のペインで データ > 接続 を選択します。

3. 新しいカスタム コネクタ > 空白から作成 を選択します。

4. カスタム コネクタの名前を入力し、続行 を選択します。

   パラメーター	価値
   カスタム コネクタ タイトル	SentimentDemo

ステップ 1: 全般的な詳細を更新する

この点から Power Automate UI について説明しますが、その手順は、テクノロジ全体でそれほど変わりません。 違いがあれば指摘します。

全般 タブで、次の手順を実行します:

1. 説明 フィールドに、わかりやすい値を入力します。 この説明は、カスタム コネクタの詳細に表示され、そのコネクタが役に立つかどうかを他のユーザーが判断するのに役立ちます。

2. ホスト を Text Analytics API のアドレスに更新します。 コネクタにより API ホストとベース URL が使用され、API を呼び出す方法が決定されます。

   パラメーター	価値
   Description	Cognitive Services Text Analytics センチメント API を使用して、テキストが肯定的か否定的かを判断します
   Host	westus.api.cognitive.microsoft.com

ステップ 2: 認証の種類を指定する

カスタム コネクタでは認証に複数のオプションを使用できます。 Cognitive Services API は API キー認証を使用するため、このチュートリアルではそれを指定します。

1. セキュリティ タブの 認証の種類 で API キー を選択します。

2. API キー で、パラメーターのラベル、名前、および場所を指定します。 他のユーザーが初めてカスタム コネクタに接続したときにこれが表示されるため、わかりやすいラベルを指定します。 パラメータ名と場所は、API が期待するものと一致する必要があります。 接続を選択します。

   パラメーター	価値
   パラメーターのラベル	API key
   パラメーター名	Ocp-Apim-Subscription-Key
   パラメーターの場所	ヘッダー

3. ウィザードの上部で、名前が SentimentDemo に設定されていることを確認し、コネクタの作成 を選択します。

ステップ3: コネクタ定義を作成する

カスタム コネクター ウィザードでは、コネクターの機能や、ロジック アプリ、フロー、アプリでの公開方法の定義する多くのオプションが用意されています。 このセクションでは、UI について説明し、いくつかのオプションについて説明しますが、自分で探索することもお勧めします。

アクションの作成

最初に、Text Analytics API センチメント操作を呼び出すアクションを作成します。

1. 定義 タブの左側のペインに、コネクタに対して定義されているアクション、トリガー (Logic Apps および Power Automate 用)、および参照が表示されます。 新しいアクション を選択します。

   このコネクタにはトリガーはありません。 カスタム コネクタのトリガーについては、Power Automate と Azure Logic Apps でウェブフックを使用する を参照してください。

2. 全般 領域には、現在選択されているアクションまたはトリガーに関する情報が表示されます。 このアクションの要約、説明、および操作 ID を追加します。

   パラメーター	価値
   まとめ	検出されたセンチメントを表す数値スコアを返します
   説明	この API により 0 から 1 の数値スコアが返されます。 1 に近いスコアは肯定的なセンチメントを示し、0 に近いスコアは否定的なセンチメントを示します。
   操作 ID	DetectSentiment

   Visibility プロパティを なし に設定したままにします。 ロジック アプリまたはフローでの操作やパラメーターのこのプロパティには、次のオプションがあります:

   • なし: 通常、ロジック アプリまたはフローで表示
   • 詳細: 別のメニューの下で非表示
   • 内部: ユーザーには非表示
   • 重要: 必ずユーザーに最初に表示

3. 要求 領域には、アクションの HTTP 要求に基づく情報が表示されます。 サンプルからのインポート を選択します。

4. API に接続するために必要な情報と要求本文 (次の図の後に表示) を指定して、インポート を選択します。 この情報は提供されますが、パブリック API の場合、通常、Text Analytics API (v2.0) などのドキュメントからこの情報を取得します。

   パラメーター	価値
   動詞	投稿
   [URL]	<https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
   Body	以下の JSON コードを使用します

   例:

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. 応答 領域には、アクションの HTTP 応答に基づく情報が表示されます。 既定の応答を追加する を選択します。

6. 応答本文を指定してから、インポート を選択します。 要求本文の場合と同様に、この情報は図に従って提供されますが、通常は API ドキュメントに記載されています。

   例:

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

7. 検証 領域には、API 定義で検出された問題が表示されます。 ステータスを確認し、ウィザードの右上隅で コネクタを更新 を選択します。

定義を更新する

いくつかの変更を行って、ロジック アプリ、フロー、またはアプリでコネクタをさらに使いやすくしてみましょう。

1. パラメーター 領域で 本文 を選択した後、編集 を選択します。

2. パラメーター 領域に、API に必要な、id、language、および text の 3 つのパラメーターが表示されます。 id を選択し、編集 を選択します

3. スキーマ プロパティ 領域で、パラメーターの値を更新し、戻る を選択します。

   パラメーター	価値
   肩書き	ID
   Description	送信する各ドキュメントの識別子
   規定値	6
   必須	イエス

4. パラメータ 領域で、 言語 > 編集 を選択し、次のプロセスを繰り返します。この手順のステップ 2 と 3 で id を使用し、次の値を使用します。

パラメーター	価値
肩書き	Language
Description	"テキストの 2 または 4 文字の言語コード"
規定値	en
必須	イエス

1. パラメータ 領域で、 テキスト > 編集 を選択し、次のプロセスを繰り返します。この手順のステップ 2 と 3 で id を使用し、次の値を使用します。

パラメーター	値
タイトル	テキスト
説明	センチメントの分析対象テキスト
既定値	いいえ
必須	はい

1. パラメーター 領域で、戻る を選択して、メインの 定義 タブに戻ります。

2. ウィザードの右上隅にある コネクタの更新 を選択します。

ステップ 4: (オプション) コネクタを AI プラグインとして有効にする

コネクタの AI プラグイン (プレビュー) タブは、コネクタを認定 する予定がある場合にのみ使用します。 コネクタを AI プラグインとして使用するには、コネクタが認定されている必要があります。

コネクタを AI プラグインとして有効にする前に、AI プラグイン シナリオのユース ケースを理解し、サポート性、ベスト プラクティス、推奨事項などのその他の考慮事項を確認してください。 詳細: コネクタ AI プラグインを作成する (プレビュー)

1. 左側のナビゲーション ウィンドウで、カスタム コネクタ を選択します。

   カスタム コネクタ が表示されない場合は、その他 > すべてを検出 > カスタム コネクタ を選択します。 このオプションは左側のナビゲーション ウィンドウに表示されます。

2. 右上の 新しいカスタム コネクタ メニューからオプションを選択します。

3. この記事の ステップ 1、ステップ 2、ステップ 3 を完了していることを確認します。

4. AI プラグイン (プレビュー) タブを選択します。

5. プラグイン マニフェスト セクションに、このコネクタを AI プラグインとして有効にするための詳細を入力します。

   

   Field	Description
   プラグイン マニフェスト: 名前	AI プラグインの名前。
   プラグインマニフェスト: 説明	AI プラグインの説明。 詳細: コネクタ AI プラグインを作成する (プレビュー)
   プラグイン マニフェスト: 連絡先メールアドレス	この AI プラグインの連絡先のメール アドレス。
   プラグイン マニフェスト: 法的情報 URL	AI プラグインに関連する法的情報が公開される、一般にアクセス可能な場所。

6. プラグイン アクションの詳細 セクションまで下にスクロールし、コネクタ AI プラグインの各アクションのアクション詳細を入力します。

   

   Field	Description
   プラグイン アクションの詳細: 概要	ユーザーが実行できる各 AI プラグイン アクションの概要。
   プラグイン アクションの詳細: 説明	この特定の AI プラグイン アクション ステップに関してユーザーが実行できる各アクションの説明。
   チェックボックス: コパイロット プラグイン操作として有効にする	チェックボックスにチェック マークがある場合は、AI プラグイン操作が有効になります。
   チェックボックス: ユーザー確認が必要ですか?	チェックボックスにチェック マークがある場合は、ユーザー確認が必要です。

   ヒント

   アクションの定義にヘルプが必要な場合は、Swagger エディタ トグルをオンにします。

7. パラメーター セクションまで下にスクロールし、コネクタ AI プラグインのパラメーターの詳細を入力します。

   

   Field	Description
   パラメーター: 名前	パラメーターの名前。 ID の代わりに、アカウント識別子 などの識別可能な名前を使用します。
   パラメーター: 説明	パラメーターの説明。 b_date の代わりに、MM/DD/YYYY 形式の連絡先の生年月日 などの詳しい説明を使用します。 このような名前と説明は、LLM (大規模言語モデル) が AI プラグインと効果的に対話するのに役立ちます。
   パラメーター: 概要	パラメーターに関する概要情報。
   パラメーター: 既定値	パラメーターの既定値。

8. AI プラグイン (プレビュー) セクションの下にある 要求 セクションで、入力パラメーターを選択し、説明を入力します。

ステップ 5: (オプション) カスタム コード サポートを使用する

カスタム コードは、既存のポリシー テンプレートの範囲を超えて要求と応答のペイロードを変換します。 変換には、追加データを取得するための外部リクエストの送信が含まれます。 コードを使用する場合、コードレス定義よりも優先されます。 つまり、コードは実行されますが、バックエンドには要求を送信しません。

注意

• この手順は必須ではありません。 この手順を無視して 手順 6: コネクタのテスト に進むと、コードレスでコネクタを作成することができます。
• カスタム コードのサポートは、パブリック プレビュー版で利用できます。

コードを貼り付けることも、コードを含むファイルをアップロードすることもできます。 コードは以下の条件を満たす必要があります:

• C# で記述されていること。
• 最大実行時間が 5 秒になっていること。
• ファイル サイズが 1 MB を超えないこと。

コードの記述の手順とサンプルについては、カスタム コネクタにコードを記述する にアクセスしてください。

カスタム コードに関するよくある質問については、カスタム コード FAQ にアクセスしてください。

1. コード タブで、次のいずれかのオプションを使用してカスタム コードを挿入します:

   • コピー/貼り付け
   • アップロード ボタンの選択。

   カスタム コードをアップロードする場合は、拡張子が .cs または .csx のファイルのみ利用可能です。

   

   重要

   現在、コード エディターでの構文の強調表示のみに対応しています。 必ずローカルでコードをテストしてください。

2. コードを貼り付ける、またはアップロードしたら、コードが無効 の横にあるトグルを選択して、コードを有効にします。 トグル名がコード有効に変わります。

   コードはいつでも有効、無効にできます。 トグルが コードが無効 となっている場合、コードが削除されます。

3. ドロップダウン メニューでオプションを選択して、カスタム コードに適用するアクションとトリガーを選択します。 操作が選択されていない場合、アクションとトリガーは すべて の操作に適用されます。

   

ステップ 6: コネクタをテストする

コネクタの作成が完了したので、そのコネクタをテストして、適切に機能していることを確認します。 テストは現在、Power Automate と Power Apps でのみ使用可能です。

重要

API キーを使用する場合は、作成後すぐにコネクタをテストしないことをお勧めします。 コネクタが API に接続できるようになるまで数分かかる場合があります。

1. テスト タブで、新しい接続 を選択します。

2. Text Analytics API から API キーを入力し、接続の作成 を選択します。

   注意

   ベアラー認証を必要とする API の場合、API キーの前に ベアラー と 1 つのスペースを追加します。

3. テスト タブに戻り、次のいずれかを実行します:

   • (Power Automate で) テスト タブに戻ります。更新アイコンを選択して、接続情報が更新されていることを確認します。

     

   • (Power Apps で) 現在の環境で使用できる接続のリストに移動します。 左側のペインで データ > 接続 を選択します。 作成したコネクタを選択した後、テスト タブに戻ります。

4. テスト タブの テキスト フィールドに値を入力し (他のフィールドでは前に設定した既定値を使用)、テスト操作 を選択します。

5. コネクタは API を呼び出し、センチメント スコアを含む応答を確認できます。

   

(CLI ユーザー向け) ベスト プラクティス

• コネクタをすべてダウンロードし、Git またはソース コード管理システムを使用してファイルを保存します。

• 不適切な更新があった場合は、ソース コード管理システムの正しいファイルのセットを使用して更新コマンドを再実行し、コネクタを再デプロイします。

• 運用環境にデプロイする前に、テスト環境でカスタム コネクタと設定ファイルをテストします。

• 環境とコネクタ ID が正しいことを、必ず再確認してください。

次の手順

以上で、カスタム コネクターの作成と、その動作の定義が完了したため、以下からコネクターを使用できます:

• フロー
• アプリ
• ロジック アプリ

組織内でコネクタを共有したり、組織外のユーザーが使用できるようにコネクタの認定を取得したりすることもできます。

• 自分のコネクタの共有
• 自分のコネクタを認定する

フィードバックを提供する

コネクタ プラットフォームの問題点や新機能のアイデアなどのフィードバックをお待ちしています。 フィードバックを提供するには、「問題を送信するか、コネクタに関するヘルプを入手する」にアクセスし、フィードバックの種類を選択します。