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

[アーティクル]
04/19/2024

注意

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

カスタムコネクタを作成するには、接続したい API について記述して、コネクタが API の操作とデータ構造を認識できるようにする必要があります。このトピックでは、Cognitive Services Text Analytics センチメント API を記述する OpenAPI 定義 (このシリーズの例) を使用してカスタムコネクタを作成します。

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

前提条件

API の例を説明する OpenAPI 定義です。カスタムコネクタを作成する場合、OpenAPI 定義は 1 MB 未満である必要があります。 OpenAPI 定義は、OpenAPI 2.0 (以前は Swagger と呼ばれていました) 形式である必要があります。

複数のセキュリティ定義がある場合、カスタムコネクタは一番上のセキュリティ定義を選択します。カスタムコネクタの作成では、OAuth セキュリティ定義のクライアント認証情報 (アプリケーションやパスワードなど) は対応していません。
Cognitive Services Text Analytics API の API キーです。
次のいずれかのサブスクリプション:
- Logic Appsを使用している場合は、Azure
- Power Automate
- Power Apps
Logic Apps を使用している場合は、最初に Azure Logic Apps カスタムコネクタを作成します。

OpenAPI 定義をインポートする

これで、ダウンロードをした OpenAPI 定義を使用する準備ができました。必要な情報はすべて定義に含まれており、カスタムコネクタウィザードを使用して、この情報を確認および更新できます。

Logic Apps、または Power Automate および Power Apps 用に OpenAPI 定義をインポートすることから始めます。

注意

OpenAPI 定義は、OpenAPI 2.0 (以前は Swagger と呼ばれていました) 形式である必要があります。 OpenAPI 3.0 形式にある OpenAPI 定義は、サポートされていません。

Logic Apps 用に OpenAPI 定義をインポートする

Azure ポータルに移動し、以前に Azure Logic Apps カスタムコネクタの作成で作成した Logic Apps コネクタを開きます。
コネクタのメニューで、Logic Apps コネクタを選択し、次に編集を選択します。
全般で、OpenAPI ファイルをアップロード を選び、作成した OpenAPI 定義に移動します。

注意

このチュートリアルでは REST API に焦点を当てていますが、Logic Apps で SOAP API を使用することもできます。

Power Automate と Power Apps 用に OpenAPI 定義をインポートする

Power Apps または Power Automate にサインインします。
左側のペインで データ > 接続を選択します。
新しいカスタムコレクタ を選び、OpenAPI ファイルをインポートする を選択します。
カスタムコネクタの名前を入力し、ダウンロードまたは作成した OpenAPI 定義に移動し、続行を選択します。

パラメーター価値

カスタムコネクタタイトル SentimentDemo

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

全般の詳細のレビュー

ここからは Power Automate UI について説明しますが、手順は、3 つのすべてのテクノロジ全体でそれほど変わりません。違いがあれば指摘します。トピックのこの部分では、主に UI を確認し、値が OpenAPI ファイルのセクションにどのように対応するかを示します。

ウィザードの上部で、名前が SentimentDemo に設定されていることを確認し、コネクタの作成 を選択します。
全般ページで、API ホストや API のベース URL など、OpenAPI 定義からインポートされた情報を確認します。コネクタにより API ホストとベース URL が使用され、API を呼び出す方法が決定されます。

注意

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

OpenAPI 定義の次のセクションには、UI のこのページに関する情報が含まれています:
```
  "info": {
    "version": "1.0.0",
    "title": "SentimentDemo",
    "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
  },
  "host": "westus.api.cognitive.microsoft.com",
  "basePath": "/",
  "schemes": [
    "https"
  ]
```

認証タイプのレビュー

カスタムコネクタでは認証に複数のオプションを使用できます。 Cognitive Services API は API キー認証を使用するため、それが OpenAPI 定義で指定されているものです。

セキュリティ ページで、API キーの認証情報を確認します。

API キーパラメーター。

このラベルは、誰かが最初にカスタムコネクタと接続したときに表示され、編集を選択してこの値を変更できます。パラメーターの名前と場所は、API で必要なものと一致する必要があり、この場合は Ocp-Apim-Subscription-Key と ヘッダー になります。

OpenAPI 定義の次のセクションには、UI のこのページに関する情報が含まれています:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

コネクタ定義をレビューする

カスタムコネクタウィザードの定義ページでは、コネクタの機能、およびロジックアプリ、フロー、アプリで公開する方法を定義するための多くのオプションが用意されています。このセクションでは、UI について説明し、いくつかのオプションについて説明しますが、自分で探索することもお勧めします。この UI でオブジェクトを最初から定義する方法については、コネクタ定義を作成するを参照してください。

次の領域には、コネクタに対して定義されているアクション、トリガー (Logic Apps および Power Automate 用)、および参照が表示されます。このケースでは、OpenAPI 定義から DetectSentiment アクションが表示されます。このコネクタにはトリガーがありませんが、カスタムコネクタのトリガーについては、Azure Logic Apps および Power Automate での webhook の使用ページでご確認いただけます。
全般領域には、現在選択されているアクションまたはトリガーに関する情報が表示されます。ロジックアプリまたはフローの操作とパラメーターに対する Visibility プロパティを含む情報は、ここで編集できます。
- なし: 通常、ロジックアプリまたはフローで表示
- 詳細: 追加メニューでは非表示
- 内部: ユーザーには非表示
- 重要: 必ずユーザーに最初に表示
要求エリアでは、OpenAPI 定義に含まれる HTTP 要求に基づいて情報が表示されます。この場合、HTTP 動詞は POST で、URL は /text/analytics/v2.0/sentiment (API への完全な URL は <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>) です。ここでは、本文パラメーターについて詳しく説明します。

OpenAPI 定義の次のセクションには、UI の全般および要求の領域に関する情報が含まれています:
```
"paths": {
  "/text/analytics/v2.0/sentiment": {
    "post": {
      "summary": "Returns a numeric score representing the sentiment detected",
      "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
      "operationId": "DetectSentiment"
```
応答領域では、OpenAPI 定義に含まれる HTTP 応答に基づいて情報が表示されます。この場合、定義されている応答は 200 (正常な応答) のみですが、追加の応答を定義することもできます。

OpenAPI 定義の次のセクションには、応答に関する一部の情報が含まれています:
```
"score": {
 "type": "number",
 "format": "float",
 "description": "score",
 "x-ms-summary": "score"
},
"id": {
 "type": "string",
 "description": "id",
 "x-ms-summary": "id"
}
```
このセクションでは、コネクタによって返される id と score の 2 つの値を示します。データ型とフィールド x-ms-summary が含まれ、これは OpenAPI 拡張機能です。これと他の拡張機能の詳細については、カスタムコネクタの OpenAPI 定義を拡張するを参照してください。
検証領域には、API 定義で検出された問題が表示されます。コネクタを保存する前に、必ずこの領域を確認してください。

定義を更新する

ダウンロードした OpenAPI の定義は基本的な良い例ですが、誰かが Logic App、フロー、アプリで使うときにコネクタがより使いやすくなるように、多くの更新が必要な定義で作業することもあるかもしれません。定義を変更する方法について説明します。

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

パラメーター値

説明送信する各ドキュメントの数値の識別子
パラメーター 領域で、戻るを選択して、メインの定義ページに戻ります。
ウィザードの右上隅にある コネクタの更新 を選択します。

パラメーター	値
説明	送信する各ドキュメントの数値の識別子

更新した OpenAPI ファイルをダウンロードする

カスタムコネクタを OpenAPI ファイルから、またはゼロから作成できます (Power Automate および Power Apps で)。コネクタを作成する方法に関係なく、サービスが内部的に使用する OpenAPI 定義をダウンロードできます。

Logic Apps では、カスタムコネクタからダウンロードします。
Power Automate または Power Apps で、カスタムコネクタのリストからダウンロードします。

コネクタをテストする

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

重要

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

テスト ページで、新規接続を選択します。
Text Analytics API から API キーを入力し、接続の作成 を選択します。
テストページ に戻り、次のいずれかを実行します:
- Power Automate で、テスト ページに戻ります。更新アイコンを選択して、接続情報が更新されることを確認します。
- Power Apps で、現在の環境で使用できる接続のリストに移動します。右上隅にある歯車アイコンを選択し、カスタムコネクタ を選択します。作成したコネクタを選択した後、テスト ページに戻ります。
テスト ページの テキスト フィールドに値を入力し (他のフィールドには前に設定した既定値を使用)、操作のテスト を選択します。
コネクタは API を呼び出し、センチメントスコアを含む応答を確認できます。