カスタム コネクタを一から作成するCreate a custom connector from scratch

注意

このトピックは、Azure Logic Apps、Microsoft Flow、および PowerApps でのカスタム コネクタの作成および使用に関するチュートリアル シリーズの一部です。This topic is part of a tutorial series on creating and using custom connectors in Azure Logic Apps, Microsoft Flow, and PowerApps. プロセスを理解するために、カスタム コネクタの概要を必ずご確認ください。Make sure you read the custom connector overview to understand the process.

カスタム コネクタを作成するには、接続先の API について記述して、コネクタが API の操作とデータ構造を認識できるようにする必要があります。To create a custom connector, you must describe the API you want to connect to so that the connector understands the API's operations and data structures. このトピックでは、カスタム コネクタをゼロから作成します。Cognitive Services Text Analytics Sentiment API (このシリーズのサンプル) の記述に "Postman コレクション" や "OpenAPI 定義" は使用しません。In this topic, you create a custom connector from scratch, without using a Postman collection or an OpenAPI definition to describe the Cognitive Services Text Analytics Sentiment API (our example for this series). 代わりに、カスタム コネクタ ウィザードでコネクタを完全に記述します。Instead, you describe the connector completely in the custom connector wizard.

API を記述する他の方法については、次のトピックを参照してください。For other ways to describe an API, see the following topics:

注意

現在、Microsoft Flow および PowerApps では、ゼロからカスタム コネクタを作成できます。You can currently create a custom connector from scratch in Microsoft Flow and PowerApps. Logic Apps の場合は、少なくとも基本的な OpenAPI 定義または Postman コレクションから始める必要があります。For Logic Apps, you must start with at least a basic OpenAPI definition or Postman collection.

前提条件Prerequisites

カスタム コネクタ ウィザードを開始するStart the custom connector wizard

  1. web.powerapps.com または flow.microsoft.com に移動します。Go to powerapps.com or flow.microsoft.com.

  2. 右上にある歯車アイコンを選択し、[カスタム コネクタ] を選択します。In the upper right corner, choose the gear icon, then choose Custom connectors.

    サービスの歯車アイコン

  3. [カスタム コネクタの作成][一から作成] の順に選択します。Choose Create custom connector, then choose Create from blank.

    カスタム コネクタの作成

  4. カスタム コネクタの名前を入力し、[接続] を選択します。Enter a name for the custom connector, then choose Connect.

    Postman コレクションのアップロード

    パラメーターParameter Value
    カスタム コネクタのタイトルCustom connector title "SentimentDemo""SentimentDemo"

全般的な情報を更新するUpdate general details

以降は Microsoft Flow UI について説明しますが、その手順は、テクノロジ全体でそれほど変わりません。From this point, we'll show the Microsoft Flow UI, but the steps are largely the same across the technologies. 違いがある場合は指摘します。We'll point out any differences.

  1. [全般] ページで次の操作を行います。On the General page:

    • [説明] に、意味のある値を入力します。Enter a meaningful value for Description. この説明は、カスタム コネクタの詳細に表示され、そのコネクタが役に立つかどうかを他のユーザーが判断する助けになります。This description is displayed in the custom connector's details, and it can help others know if the connector could be useful to them.

    • ホストを Text Analytics API のアドレスに更新します。Update Host to the address for the Text Analytics API. コネクタは API ホストとベース URL を使用して、API を呼び出す方法を決定します。The connector uses the API host and the base URL to determine how to call the API.

    カスタム コネクタの [全般] ページ

    パラメーターParameter Value
    説明Description "Cognitive Services Text Analytics Sentiment API を使用して、テキストが肯定的か否定的かを判断します""Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
    HostHost "westus.api.cognitive.microsoft.com""westus.api.cognitive.microsoft.com"

    注意

    [オンプレミスのデータ ゲートウェイ経由で接続] オプションの詳細については、「Connect to on-premises APIs using the data gateway (データ ゲートウェイを使用してオンプレミス API に接続する)」を参照してください。For more information about the option Connect via on-premises data gateway, see Connect to on-premises APIs using the data gateway.

認証の種類を指定しますSpecify authentication type

カスタム コネクタでは複数の認証オプションを使用できます。There are several options available for authentication in custom connectors. Cognitive Services APIs では API キー認証が使用されるため、このチュートリアルではこれを指定します。The Cognitive Services APIs use API key authentication, so that's what you specify for this tutorial.

  1. [セキュリティ] ページの [認証の種類][API キー] を選択します。On the Security page, under Authentication type, choose API Key.

    認証の種類

  2. [API キー] で、パラメーターのラベル、名前、および場所を指定します。Under API Key, specify a parameter label, name, and location. 分かりやすいラベルを指定します。これは、他のユーザーが初めてカスタム コネクタに接続したときに表示されます。Specify a meaningful label, because this is displayed when someone first makes a connection with the custom connector. パラメーターの名前と場所は、API に必要なものと一致する必要があります。The parameter name and location must match what the API expects. [接続] を選択します。Choose Connect.

    API キー パラメーター

    パラメーターParameter Value
    パラメーターのラベルParameter label "API キー""API key"
    パラメーター名Parameter name "Ocp-Apim-Subscription-Key""Ocp-Apim-Subscription-Key"
    パラメーターの場所Parameter location "ヘッダー""Header"
  3. ウィザードの上部で、名前が "SentimentDemo" に設定されていることを確認し、[コネクタの作成] を選択します。At the top of the wizard, make sure the name is set to "SentimentDemo", then choose Create connector.

コネクタの定義を作成するCreate the connector definition

カスタム コネクタ ウィザードには、コネクタがどのように機能し、どのようにロジック アプリ、フロー、およびアプリに表示されるかを定義するためのオプションが多数用意されています。The custom connector wizard gives you a lot of options for defining how your connector functions, and how it is exposed in logic apps, flows, and apps. このセクションでは、UI といくつかのオプションについて説明しますが、ご自身でも確認することをお勧めします。We'll explain the UI and cover a few options in this section, but we also encourage you to explore on your own.

アクションを作成するCreate an action

まず、Text Analytics Sentiment API を呼び出すアクションを作成します。The first thing to do is create an action that calls the Text Analytics Sentiment API.

  1. [定義] ページの左側の領域に、コネクタに対して定義されているアクション、トリガー (Logic Apps および Microsoft Flow 用)、および参照が表示されます。On the Definition page, the left area displays any actions, triggers (for Logic Apps and Microsoft Flow), and references that are defined for the connector. [新しいアクション] を選択します。Choose New action.

    [定義] ページ - アクションとトリガー

    このコネクタにはトリガーがありませんが、カスタム コネクタのトリガーについては、Azure Logic Apps および Microsoft Flow での webhook の使用に関するページで確認できます。There are no triggers in this connector, but you can learn about triggers for custom connectors in Use webhooks with Azure Logic Apps and Microsoft Flow.

  2. [全般] 領域には、現在選択されているアクションまたはトリガーに関する情報が表示されます。The General area displays information about the action or trigger currently selected. このアクションの概要、説明、および操作 ID を追加します。Add a summary, description, and operation ID for this action.

    [定義] ページ - 全般

    パラメーターParameter Value
    まとめSummary "検出されたセンチメントを表す数値スコアを返します""Returns a numeric score representing the sentiment detected"
    説明Description "API は 0 ~ 1 の数値スコアを返します。"The API returns a numeric score between 0 and 1. 1 に近いスコアは肯定的センチメント、0 に近いスコアは否定的センチメントを示します。"Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment."
    操作 IDOperation ID "DetectSentiment""DetectSentiment"

    表示プロパティは none のままにします。Leave the Visibility property set to none. ロジック アプリまたはフローの操作とパラメーターに対するこのプロパティのオプションを次に示します。This property for operations and parameters in a logic app or flow has the following options:

    • none: 通常、ロジック アプリまたはフローに表示されますnone: displayed normally in the logic app or flow
    • advanced: 追加メニューに表示されませんadvanced: hidden under an additional menu
    • internal: ユーザーに表示されませんinternal: hidden from the user
    • important: 必ずユーザーに最初に表示されますimportant: always shown to the user first
  3. [要求] 領域には、アクションに対する HTTP 要求に基づいて情報が表示されます。The Request area displays information based on the HTTP request for the action. [サンプルからのインポート] を選択します。Choose Import from sample.

    [定義] ページ - サンプルからのインポート

  4. API への接続に必要な情報と、要求本文を指定して、[インポート] を選択します。Specify the information necessary to connect to the API, and the request body, then choose Import. この情報は用意しています (図の下を参照)。We provide this information for you (below the image). パブリック API では、通常、Text Analytics センチメント API などのドキュメントから取得します。For a public API, you typically get it from the documentation, like Text Analytics Sentiment API.

    [定義] ページ - サンプルからのインポート

    パラメーターParameter Value
    VerbVerb "POST""POST"
    URLURL "https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment""https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment"
    本文Body 以下を参照See below
    {
      "documents": [
        {
          "language": "string",
          "id": "string",
          "text": "string"
        }
      ]
    }
    
  5. [応答] 領域には、アクションに対する HTTP 応答に基づいて情報が表示されます。The Response area displays information based on the HTTP response for the action. [既定の応答を追加する] を選びます。Choose Add default response.

    [定義] ページ - 応答

  6. 応答本文を指定し、[インポート] を選択します。Specify the response body, then choose Import. 要求と同様、この情報は用意していますが、通常は API ドキュメントにあります。Like the request, we provide this information for you, but it's typically in the API documentation.

    [定義] ページ - 応答

    {
     "documents": [
       {
         "score": 0.0,
         "id": "string"
       }
     ],
     "errors": [
       {
         "id": "string",
         "message": "string"
       }
     ]
    }
    
  7. [検証] 領域に、API 定義で検出された問題が表示されます。The Validation area displays any issues that are detected in the API definition. 状態を確認し、ウィザードの右上で [コネクタの更新] を選択します。Check the status, then at the top right of the wizard, choose Update connector.

    [定義] ページ - 検証

定義を更新するUpdate the definition

いくつかの変更を行って、ロジック アプリ、フロー、または PowerApps アプリでコネクタをさらに使いやすくしてみましょう。Now let's change a few things so that the connector is more friendly when someones uses it in a logic app, flow, or PowerApps app.

  1. [要求] 領域で、[本文][編集] の順に選択します。In the Request area, choose body then Edit.

    要求本文を編集する

  2. [パラメーター] 領域で、API に必要な 3 つのパラメーター idlanguage、および text が表示されます。In the Parameter area, you now see the three parameters that the API expects: id, language, and text. [id][編集] の順に選択します。Choose id then Edit.

    要求本文 id の編集

  3. [スキーマのプロパティ] 領域で、パラメーターの値を更新し、[戻る] を選択します。In the Schema Property area, update values for the parameter, then choose Back.

    スキーマのプロパティの編集

    パラメーターParameter Value
    タイトルTitle "ID""ID"
    説明Description "送信する各ドキュメントの識別子""An identifier for each document that you submit"
    既定値Default value "1""1"
    必須Is required "はい""Yes"
  4. [パラメーター] 領域で、[言語][編集] の順に選択し、id で行ったプロセスを次の値を使用して繰り返します。In the Parameter area, choose language then Edit, and repeat the process you used for id, with the following values.

    パラメーターParameter Value
    タイトルTitle "言語""Language"
    説明Description "テキストの 2 または 4 文字の言語コード""The 2 or 4 character language code for the text"
    既定値Default value "en""en"
    必須Is required "はい""Yes"
  5. [パラメーター] 領域で、[テキスト][編集] の順に選択し、id および language で行ったプロセスを次の値を使用して繰り返します。In the Parameter area, choose text then Edit, and repeat the process you used for id and language, with the following values.

    パラメーターParameter Value
    タイトルTitle "テキスト""Text"
    説明Description "センチメントの分析対象テキスト""The text to analyze for sentiment"
    既定値Default value なしNone
    必須Is required "はい""Yes"
  6. [パラメーター] 領域で、[戻る] を選択して、メインの定義ページに戻ります。In the Parameter area, choose Back to take you back to the main definition page.

  7. ウィザードの右上で [コネクタの更新] を選択します。At the top right of the wizard, choose Update connector.

接続をテストするTest the connector

コネクタの作成が完了したので、次はそのコネクタをテストして、適切に機能していることを確認します。Now that you've created the connector, test it to make sure it's working properly. テストは、現在、Microsoft Flow および PowerApps でのみ使用できます。Testing is currently available only in Microsoft Flow and PowerApps.

重要

API キーを使用している場合、コネクタのテストは、作成直後には行わないことをお勧めします。When using an API key, we recommend not testing the connector immediately after you create it. コネクタが API に接続できるようになるまで、数分かかる場合があります。It can take a few minutes until the connector is ready to connect to the API.

  1. [テスト] ページで、[新しい接続] を選択します。On the Test page, choose New connection.

    新しい接続

  2. Text Analytics API から API キーを入力し、[接続の作成] を選択します。Enter the API key from the Text Analytics API, then choose Create connection.

    接続を作成する

  3. [テスト] ページに戻ります。Return to the Test page:

    • Microsoft Flow で、[テスト] ページに戻ります。In Microsoft Flow, you are taken back to the Test page. 更新アイコンを選択して、接続情報が更新されることを確認します。Choose the refresh icon to make sure the connection information is updated.

      接続の更新

    • PowerApps では、現在の環境で使用できる接続の一覧が表示されます。In PowerApps, you are taken to the list of connections available in the current environment. 右上にある歯車アイコンを選択し、[カスタム コネクタ] を選択します。In the upper right corner, choose the gear icon, then choose Custom connectors. 作成した接続を選択し、[テスト] ページに戻ります。Choose the connector you created, then go back to the Test page.

      サービスの歯車アイコン

  4. [テスト] ページの [テキスト] フィールドに値を入力し (他のフィールドでは前に設定した既定値を使用)、[テスト操作] を選択します。On the Test page, enter a value for the text field (the other fields use the defaults that you set earlier), then choose Test operation.

    テスト操作

  5. コネクタが API を呼び出したら、応答を確認できます。この応答にはセンチメント スコアが含まれます。The connector calls the API, and you can review the response, which includes the sentiment score.

    コネクタの応答

次の手順Next steps

カスタム コネクタを作成し、動作の定義が完了しました。これでコネクタを使用できます。Now that you've created a custom connector and defined its behaviors, you can use the connector:

組織内でコネクタを共有したり、組織外のユーザーが使用できるようにコネクタの認定を受けたりすることもできます。You can also share a connector within your organization and/or get the connector certified so that people outside your organization can use it: