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

カスタム コネクタを作成するには、接続する API を記述して、コネクタが API のアクションとデータ構造を理解できるようにします。 この記事では、Cognitive Services Text Analytics Sentiment API (このシリーズの例) について説明する Postman コレクション を使用して、カスタム コネクタを作成します。

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

• OpenAPI 定義からカスタム コネクタを作成する

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

前提条件

前提条件を確認して、カスタム コネクタを作成するために必要なものがすべて揃っていることを確認します。 以下のものが必要です:

• 例の API を説明する Postman コレクション。 カスタム コネクタの Postman コレクションの作成に関する記事のガイダンスに従います。

• Cognitive Services Text Analytics API の API キー です。

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

  • Logic Appsを使用している場合は、Azure
  • Power Automate
  • Power Apps

• Logic Apps を使用している場合は、最初に Azure Logic Apps カスタム コネクタを作成 します。

Postman コレクションをインポートする

これで、作成またはダウンロードした Postman コレクションを使用する準備ができました。 コレクションには、必要な情報の多くがあります。 カスタム コネクタ ウィザードを実行するときに、この情報を確認して更新できます。 まず、 Logic Apps または Power Automate と Power Apps 用の Postman コレクションをインポートします。

Logic Apps 用の Postman コレクションをインポートする

1. Azure portal に移動し、以前に Azure Logic Apps カスタム コネクタの作成 で作成した Logic Apps コネクタを開きます。

2. コネクタのメニューで、Logic Apps コネクタ を選択し、次に 編集 を選択します。

   

3. 全般で Postman コレクション V1 をアップロードするを選択し、作成した Postman コレクションに移動します。

   

   ウィザードによってコレクションがインポートされ、その後、generatedApiDefinition.swagger.json という名前の OpenAPI 定義に変換されます。

Power Automate および Power Apps 用の Postman コレクションをインポートします

1. make.powerapps.com または flow.microsoft.com に移動します。

2. ナビゲーション ウィンドウで、[その他>すべて検出] を選択します。

3. [データ] セクションで、[ カスタム コネクタ] を選択します。

4. 新しいカスタム コネクタ を選択し、Postman コレクションをインポート を選択します。

5. カスタム コネクタの名前を入力し、ダウンロードまたは作成した Postman コレクションに移動し、続行を選択します。

   

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

   ウィザードによってコレクションがインポートされ、 generatedApiDefinition.swagger.jsonという名前の OpenAPI 定義に変換されます。

全般的な詳細を更新する

この時点から、この記事では Power Automate UI を示していますが、手順は 3 つのテクノロジすべてでほぼ同じです。 違いは、必要に応じて強調表示されます。

1. 全般 ページで、API のホストやベース URL など、Postman コレクションからインポートされた情報を確認します。 コネクタでは、ホストとベース URL を使用して、API を呼び出す方法を決定します。

   注意

   オンプレミス API への接続に関する詳細情報は、データ ゲートウェイを使用してオンプレミス API に接続する をご覧ください。

2. わかりやすい説明に更新します。 この説明は、カスタム コネクタの詳細に表示され、他のユーザーがコネクタがどのように役立つのかを理解するのに役立ちます。

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

認証の種類を指定する

カスタム コネクタでは、いくつかの認証オプションがサポートされています。 Cognitive Services API では API キー認証が使用されます。

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

2. API キー で、パラメーターのラベル、名前、および場所を指定します。 表現力があり意味のあるラベルを選択します。 このテキストは、ユーザーがそのカスタム コネクタを使用して接続するときに表示されます。 パラメーターの名前と場所は、API で必要なものと一致する必要があります (この場合は Postman で指定したヘッダー)。 接続 を選択します。

   

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

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

コネクタの定義を確認して更新する

カスタム コネクタ ウィザードには、コネクタの動作方法と、ロジック アプリ、フロー、アプリ、およびエージェントでのコネクタの公開方法を定義するための多くのオプションが用意されています。 このセクションでは、UI について説明し、いくつかのオプションについて説明しますが、独自にさらに詳しく調べることができます。

UI と定義を確認する

[定義] ページの手順に従う前に、UI を確認します。

1. この領域には、コネクタに対して定義されているアクション、トリガー (Logic Apps と Power Automate の場合)、参照、およびポリシーが表示されます。 この場合、Postman コレクションからの DetectSentiment アクションが表示されました。 このコネクタにはトリガーがありませんが、カスタム コネクタのトリガーについては、Azure Logic Apps および Power Automate での webhook の使用 ページでご確認いただけます。

   

2. 全般領域には、現在選択されているアクションまたはトリガーに関する情報が表示されます。 この情報は、Postman コレクションから取得されます。 ロジック アプリまたはフローの操作とパラメーターに対する Visibility プロパティを含む情報 は、ここで編集できます。

   • 重要: 必ずユーザーに最初に表示
   • なし: 通常、ロジック アプリまたはフローで表示
   • advanced: 最初は追加メニューに表示されません
   • internal: ユーザーに表示されません

3. 要求 領域には、Postman コレクションに含まれる HTTP 要求に基づいて情報が表示されます。 この場合、HTTP 動詞 は POST で、URL は 「/text/analytics/v2.0/sentiment」 (API への完全な URL は 「<https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>」) です。 近々body パラメーターを詳しく見ていきます。

4. 応答 領域には、Postman コレクションに含まれる HTTP 応答に基づいて情報が表示されます。 ここで定義されている応答は 「200」 (成功応答) のみですが、他の応答を定義することもできます。

5. 検証 領域には、API 定義で検出された問題が表示されます。 コネクタを保存する前に、必ずこの領域を確認してください。

定義を更新する

ロジック アプリ、Power Automate、または Power Apps でコネクタを使いやすくするために、いくつかの設定を変更します。

1. 全般エリアで、概要を「検出されたセンチメントを表す数値スコアを返す」に更新します。

2. 要求 領域で、本文、編集 の順に選択します。

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

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

   

   パラメーター	価値
   タイトル	"ID"
   説明	"送信する各ドキュメントの識別子"
   既定値	"1"
   必須	"はい"

5. パラメーター 領域で、言語、編集 の順に選択し、上記のプロセスを次の値を使用して繰り返します。

   パラメーター	価値
   タイトル	"言語"
   説明	"テキストの 2 または 4 文字の言語コード"
   既定値	"en"
   必須	"はい"

6. パラメーター 領域で、テキスト、編集 の順に選択し、上記のプロセスを次の値を使用して繰り返します。

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

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

8. ウィザードの右上で、コネクタの更新 を選択します。

コネクタをテストする

コネクタを作成したら、コネクタをテストして、正しく動作することを確認します。 テストは、Power Automate と Power Apps でのみ使用できます。

1. テスト ページで、新しい接続を選択します。

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

3. テスト ページに戻ります。

   • Power Automate で、テスト ページに戻ります。 更新アイコンを選択して、接続情報が更新されることを確認します。
   • Power Apps で、現在の環境で使用できる接続の一覧に移動します。 右上隅にある歯車アイコンを選択し、カスタム コネクタ を選択します。 作成したコネクタを選択した後、テスト ページに戻ります。

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

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

   

制限

Power Automate と Power Apps で、Postman コレクションを使用して既存のカスタム コネクタを更新する場合は、コネクタを保存する前に以前のカスタマイズをやり直す必要があります。 たとえば、アクションのパラメーターの認証の種類と既定値を再構成する必要があります。

次の手順

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

• フローからカスタム コネクタを使用する
• アプリからカスタム コネクタを使用する
• ロジック アプリからカスタム コネクタを使用する

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

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

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

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