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

2025-06-17

注意

この記事は、Azure Logic Apps、Microsoft Power Automate、Microsoft Power Apps でのカスタムコネクタの作成と使用、そしてMicrosoft Copilot Studio の Copilot コネクタとアクションの使用に関するチュートリアルシリーズの一部です。カスタムコネクタの概要を必ず読んで、プロセスを理解してください。

Copilot Studio で Power Platform コネクタを使用するに移動して、Microsoft Copilot エージェントでコネクタアクションとしてコネクタを呼び出せる方法について学びます。

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

API を記述する別の方法については、OpenAPI 定義からカスタムコネクタを作成するを参照してください。

注意

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

前提条件

Cognitive Services Text Analytics API の API キー
次のいずれかのサブスクリプション:
- Power Automate
- Power Apps

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

Power Apps または Power Automate にサインインします。
左側のペインでソリューションを選択します。
カスタムコネクタを含むアンマネージドソリューションを編集または作成します。ソリューションの作成方法を学習する
新規ドロップダウンを選択し、自動化>カスタムコネクタを選択します。

新しいコネクタウィザードが開きます
コネクタ名を入力します (例: SentimentDemo)。

次の手順を使用して、残りの手順を完了します。

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

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

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

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

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

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

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

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

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

パラメーター価値

パラメーターのラベル API key

パラメーター名 Ocp-Apim-Subscription-Key

パラメーターの場所ヘッダー
ウィザードの上部で、名前が SentimentDemo に設定されていることを確認し、コネクタの作成 を選択します。

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

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

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

アクションの作成

最初に、Text Analytics API センチメント操作を呼び出すアクションを作成します。定義タブの左側のウィンドウに、コネクタに対して定義されているアクション、トリガー (Logic Apps、Power Automate、Copilot Studio 用)、参照が表示されます。

注意

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

新しいアクション を選択します。

全般エリアで、このアクションの概要、説明、操作 ID を追加します。

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

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

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

リクエストエリアで、サンプルからインポートを選択します。
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"
    }
  ]
}
```
応答領域で既定の応答を追加するを選択します。
応答本文を指定してから、インポート を選択します。要求本文の場合と同様、この情報も提供していますが、通常は API ドキュメントに記載されています。

例:
```
{
 "documents": [
   {
     "score": 0.0,
     "id": "string"
   }
 ],
 "errors": [
   {
     "id": "string",
     "message": "string"
   }
 ]
}
```
検証領域には、API 定義で検出された問題が表示されます。
問題を修正します。定義の検証が成功すると、緑色のチェックマークが表示されます。
ウィザードの右上隅にあるコネクタの更新を選択します。

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

定義を更新する

いくつかの変更を加えて、Logic Apps、Power Automate、Power Apps、Copilot Studio でコネクタを使いやすくしましょう。

パラメーター 領域で本文を選択した後、編集を選択します。
パラメーター 領域に、API に必要な、id、language、および text の 3 つのパラメーターが表示されます。 id を選択し、編集を選択します
スキーマプロパティ 領域で、パラメーターの値を更新し、戻るを選択します。

パラメーター価値

肩書き ID

説明送信する各ドキュメントの識別子

規定値 6

必須イエス
パラメーター 領域で、言語>編集を選択します。id で使用したプロセスを繰り返して次の language の値を使用します:

パラメーター価値

肩書き Language

プロパティ "テキストの 2 または 4 文字の言語コード"

規定値 en

必須はい
パラメーター 領域で、テキスト>編集を選択します。id と language で使用したプロセスを繰り返して次の text の値を使用します:

パラメーター価値

肩書き Text

プロパティセンチメントの分析対象テキスト

規定値 None

必須はい
パラメーター 領域で、戻るを選択して、メインの定義タブに戻ります。
ウィザードの右上隅にある コネクタの更新 を選択します。

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

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

パラメーター	価値
肩書き	Text
プロパティ	センチメントの分析対象テキスト
規定値	None
必須	はい

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

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

注意

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

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

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

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

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

コード タブで、次のいずれかのオプションを使用してカスタムコードを挿入します:
- コピー/貼り付け
- アップロード ボタンの選択。
カスタムコードをアップロードする場合は、拡張子が .cs または .csx のファイルのみ利用可能です。

重要

現在、コードエディターでの構文の強調表示のみに対応しています。必ずローカルでコードをテストしてください。
コードを貼り付ける、またはアップロードしたら、コードが無効 の横にあるトグルを選択して、コードを有効にします。トグル名がコード有効に変わります。

コードはいつでも有効、無効にできます。トグルが コードが無効 となっている場合、コードが削除されます。
ドロップダウンメニューでオプションを選択して、カスタムコードに適用するアクションとトリガーを選択します。操作が選択されていない場合、アクションとトリガーは すべて の操作に適用されます。

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

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

重要

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

テスト タブで、新しい接続 を選択します。
Text Analytics API から API キーを入力し、接続の作成 を選択します。

注意

ベアラー認証を必要とする API の場合、API キーの前に ベアラー と 1 つのスペースを追加します。
テスト タブに戻り、次のいずれかを実行します:
- (Power Automate で) テスト タブに戻ります。更新アイコンを選択して、接続情報が更新されていることを確認します。
- (Power Apps で) 現在の環境で使用できる接続のリストに移動します。左側のウィンドウで、カスタムコネクタを選択します。作成したコネクタを選択した後、テスト タブに戻ります。
テスト タブの テキスト フィールドに値を入力し (他のフィールドでは前に設定した既定値を使用)、テスト操作 を選択します。

コネクタで API が呼び出されます。
応答を確認します。この応答にはセンチメントスコアが含まれます。

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

コネクタをすべてダウンロードし、Git またはソースコード管理システムを使用してファイルを保存します。
不適切な更新があった場合は、ソースコード管理システムの正しいファイルのセットを使用して更新コマンドを再実行し、コネクタを再デプロイします。
運用環境にデプロイする前に、テスト環境でカスタムコネクタと設定ファイルをテストします。
環境とコネクタ ID が正しいことを、必ず再確認してください。

次の手順

カスタムコネクタを作成し、その動作を定義したので、以下からコネクタを使用できます。

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

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

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