Microsoft Flow でカスタム コネクタを登録して使用するRegister and use custom connectors in Microsoft Flow

Microsoft Flow を使用すると、コーディングなしでワークフローを作成できます。Microsoft Flow enables you to build workflows with no code. しかし、場合によっては Microsoft Flow の機能を拡張する必要がありますが、そのためには Web サービスが最適です。But in some cases, you need to extend Microsoft Flow capabilites, and web services are a natual fit for this. フローでサービスに接続し、操作を実行して、データを取得できます。Your flow can connect to a service, perform operations, and get data back. Microsoft Flow で接続したい Web サービスがある場合は、サービスをカスタム コネクタとして登録します。When you have a web service you want to connect to with Microsoft Flow, you register the service as a custom connector. そうすることで、Microsoft Flow は、必要な認証、サポートされる操作、操作ごとのパラメーターと出力など、Web API の特性を知ることができます。This process enables Microsoft Flow to understand the characteristics of your web API, including the authentication that it requires, the operations that it supports, and the parameters and outputs for each of those operations.

このトピックでは、カスタム コネクタを登録して使用するために必要な手順について説明します。また、Azure Cognitive Services の Text Analytics API を使います。In this topic, we'll look at the steps required to register and use a custom connector, and we'll use the Azure Cognitive Services Text Analytics API. この API は、渡されたテキストの言語、センチメント、キー フレーズを識別します。This API identifies the language, sentiment, and key phrases in text that you pass to it.

前提条件Prerequisites

  • Microsoft Flow アカウントA Microsoft Flow account.
  • JSON 形式の OpenAPI 2.0 (旧称 Swagger) ファイル、OpenAPI 定義への URL、または API の Postman Collection。An OpenAPI 2.0 (formerly known as Swagger) file in JSON format, a URL to an OpenAPI definition, or a Postman Collection for your API. 1 つもお持ちではない場合は、ガイダンスを提供します。If you don't have any of these, we'll provide guidance for you.
  • (省略可能) カスタム コネクタのアイコンとして使う画像。An image to use as an icon for your custom connector (optional).

カスタム コネクタのプロセスの手順Steps in the custom connector process

カスタム コネクタのプロセスには複数の手順があります。以下では、それについて簡単に説明します。The custom connector process has several steps, which we describe briefly below. この記事では、何らかの種類の認証済みアクセスを備えた RESTful API が既にあるものと想定し、記事の残りの部分では手順 3 ~ 6 に注目します。This article assumes you already have a RESTful API with some type of authenticated access, so we'll focus on steps 3-6 in the rest of the article. 手順 1 と 2 の例については、「Microsoft Flow 用にカスタム Web API を作成する」をご覧ください。For an example of steps 1 and 2, see Create a custom Web API for Microsoft Flow.

  1. 選択した言語とプラットフォームで、RESTful API を作成します。Build a RESTful API in the language and platform of your choice. マイクロソフトの技術を使う場合は、次のいずれかをお勧めします (ただし、任意のプラットフォームを使うことができます)。For Microsoft technologies, we recommend one of the following (but you can use any platform):

    • Azure FunctionsAzure Functions
    • Azure Web AppsAzure Web Apps
    • Azure API AppsAzure API Apps
  2. 次のいずれかの認証メカニズムを使って、API をセキュリティで保護します。Secure your API using one of the following authentication mechanisms. コネクタへの認証されていないアクセスを許可することはできますが、お勧めできません。You can allow unauthenticated access to your connectors, but we don't recommend it.

  3. Microsoft Flow が接続できるように、業界標準の 2 つの方法のどちらかで API を記述します。Describe your API in one of two industry-standard ways, so that Microsoft Flow can connect to it.

    • OpenAPI ファイルAn OpenAPI file
    • Postman CollectionA Postman Collection

      登録プロセスの一環として、手順 4 で OpenAPI ファイルを作成することもできます。You can also build an OpenAPI file in step 4 as part of the registration process.

  4. Microsoft Flow のウィザードを使って、カスタム コネクタを登録します。API の説明、セキュリティの詳細、その他の情報を指定します。Register your custom connector using a wizard in Microsoft Flow, where you specify an API description, security details, and other information.
  5. アプリでカスタム コネクタを使用します。Use your custom connector in an app. アプリでコネクタへの接続を作成し、API が提供する操作を呼び出します。Microsoft Flow で標準の接続を呼び出す場合と同じです。Create a connection to the connector in your app, and call any operations that the API provides, just like you call standard connections in Microsoft Flow.
  6. Microsoft Flow の他のリソースと同じように、カスタム コネクタを共有します。Share your custom connector like you do other resources in Microsoft Flow. この手順は省略してもかまいませんが、通常は、複数のアプリ作成者の間でカスタム コネクタを共有すると役に立ちます。This step is optional, but it often makes sense to share custom connectors across multiple app creators.

API を記述するDescribe your API

何らかの種類の認証済みアクセスを備えた API がある場合、Microsoft Flow がそれに接続できるように API を記述する方法が必要です。Assuming you have an API with some type of authenticated access, you need a way to describe the API so that Microsoft Flow can connect to it. そのためには、OpenAPI ファイルまたは Postman Collection を作成します。これは、次のような "任意の" REST API エンドポイントから行うことができます。To do this, you create an OpenAPI file or a Postman Collection – which you can do from any REST API endpoint, including:

  • パブリックに利用可能なコネクタ。Publicly available connectors. 例: SpotifyUberSlackRackspace、その他。Some examples include Spotify, Uber, Slack, Rackspace, and more.
  • 作成して、Azure、Amazon Web Services (AWS)、Heroku、Google Cloud などのクラウド ホスティング プロバイダーに展開する API。An API that you create and deploy to any cloud hosting provider, including Azure, Amazon Web Services (AWS), Heroku, Google Cloud, and more.
  • API がパブリック インターネットで公開される場合、ネットワークにデプロイされたカスタム基幹業務 API。A custom line-of-business API deployed on your network as long as the API is exposed on the public internet.

OpenAPI 2.0 (旧称 Swagger) と Postman Collection では使う形式が異なりますが、どちらもコンピューターで読み取り可能な言語に依存しないドキュメントであり、API の操作とパラメーターを記述します。OpenAPI 2.0 (formerly known as Swagger) and Postman Collections use different formats, but both are language-agnostic machine-readable documents that describe your API's operations and parameters:

  • これらのドキュメントは、API の基になっている言語とプラットフォームに応じたさまざまなツールを使って生成できます。You can generate these documents using a variety of tools depending on the language and platform that your API is built on. OpenAPI ファイルの例については、Text Analytics API のドキュメントをご覧ください。See the Text Analytics API documentation for an example of an OpenAPI file.
  • API の OpenAPI ファイルがまだなく、ファイルを作成しない場合でも、Postman Collection を使ってカスタム コネクタを簡単に作成できます。If you don't already have an OpenAPI file for your API and don't want to create one, you can still easily create a custom connector by using a Postman Collection. 詳しくは、「Postman Collection を作成する」をご覧ください。See Create a Postman Collection for more information.
  • Microsoft Flow の背後では最終的に OpenAPI が使われるので、Postman Collection は解析されて OpenAPI 定義ファイルに変換されます。Microsoft Flow ultimately uses OpenAPI behind the scenes, so a Postman Collection is parsed and translated into an OpenAPI definition file.

: ファイルのサイズを 1 MB 未満にする必要があります。Note: Your file size must be less than 1MB.

OpenAPI と Postman の概要Getting started with OpenAPI and Postman

カスタム コネクタを登録するRegister your custom connector

OpenAPI ファイルまたは Postman Collection を使って、Microsoft Flow にカスタム コネクタを登録します。You will now use the OpenAPI file or Postman Collection to register your custom connector in Microsoft Flow.

  1. flow.microsoft.com の上部のバーで、歯車アイコンを選択して設定メニューを開きます。In flow.microsoft.com, in the top bar, select the gear to open the settings menu. [Custom Connectors (カスタム コネクタ)] オプションを選びます。Select the Custom Connectors option.

    カスタム コネクタの作成

  2. [Create custom connector (カスタム コネクタの作成)] を選びます。Select Create custom connector.

    カスタム コネクタのプロパティ

  3. [General (全般)] タブで、カスタム コネクタの作成方法を選びます。In the General tab, choose how you want to create the custom connector.

    • OpenAPI をアップロードするUpload OpenAPI
    • OpenAPI URL を貼り付けるPaste OpenAPI URL
    • Postman Collection V1 をアップロードするUpload a Postman Collection V1

      カスタム コネクタの作成方法

      カスタム コネクタのアイコンをアップロードします。Upload an icon for your custom connector. [Description (説明)]、[Host (ホスト)]、[Base URL (ベース URL)] の各フィールドは、通常、OpenAPI ファイルの情報が自動的に設定されます。Description, Host, and Base URL fields are typically auto-populated with the information from the OpenAPI file. 自動設定されない場合は、フィールドに情報を追加できます。If they are not auto-populated, you can add information to those fields. [続行] を選択します。Select Continue.

  4. [Security (セキュリティ)] タブで、認証プロパティを入力します。In the Security tab, enter any authentication properties.

    認証の種類

    • 認証の種類は、OpenAPI の securityDefinitions オブジェクトでの定義に基づいて自動的に設定されます。The authentication type is auto-populated based on what is defined in your OpenAPI securityDefinitions object. 次に示すのは OAuth2.0 の例です。Below is an OAuth2.0 example.

      "securityDefinitions": {
          "AAD": {
          "type": "oauth2",
          "flow": "accessCode",
          "authorizationUrl": "https://login.windows.net/common/oauth2/authorize",
          "tokenUrl": "https://login.windows.net/common/oauth2/token"
          "scopes": {}
          }
      },
      
    • OpenAPI ファイルで securityDefintions オブジェクトが使われていない場合は、値を追加する必要はありません。If the OpenAPI file does not use the securityDefintions object, then no additional values are needed.
    • Postman Collection の場合は、サポートされる認証の種類 (OAuth 2.0 や基本など) を使っている場合にのみ、認証の種類が自動的に設定されます。When using a Postman Collection, authentication type is auto-populated only when using supported authentication types, such as OAuth 2.0 or Basic.
    • Azure Active Directory (AAD) 認証の設定の例については、「Microsoft Flow 用にカスタム Web API を作成する」をご覧ください。For an example of setting up Azure Active Directory (AAD) authenthication, see Create a custom Web API for Microsoft Flow.
  5. [Definitions (定義)] タブでは、OpenAPI ファイルまたは Postman Collection で定義されているすべての操作と要求および応答の値が自動的に設定されます。In the Definitions tab, all the operations defined in your OpenAPI file or Postman Collection, along with request and response values, are auto-populated. 必要なすべての操作が定義されている場合は、この画面を変更せずに、登録プロセスの手順 6 に進むことができます。If all your required operations are defined, you can go to step 6 in the registration process without making changes on this screen.

    [Definition (定義)] タブ

    既存のアクションを編集する場合、またはカスタム コネクタに新しいアクションを追加する場合は、引き続き以下をお読みください。If you want to edit existing actions or add new actions to your custom connector, continue reading below.

    1. OpenAPI ファイルまたは Postman Collection にまだ含まれていなかった新しいアクションを追加する場合は、左側のウィンドウで [New action (新しいアクション)] を選択し、[General (全般)] セクションで操作の名前、説明、可視性を指定します。If you want to add a new action that was not already in your OpenAPI file or Postman Collection, select New action in the left pane and fill in the General section with the name, description, and visibility of your operation.
    2. [Request (要求)] セクションで、右上の [Import from sample (サンプルからインポート)] を選択します。In the Request section, select Import from sample on the top right. 右側のフォームで、サンプルの要求に貼り付けます。In the form on the right, paste in a sample request. 通常、API ドキュメントではサンプルの要求を使用でき、[Verb (動詞)][Request URL (要求 URL)][Headers (ヘッダー)][Body (本文)] の各フィールドに入力する情報を取得できます。Sample requests are usually available in the API documentation, where you can get information to fill out the Verb, Request URL, Headers, and Body fields. 例については、Text Analytics API のドキュメントをご覧ください。See the Text Analytics API documentation for an example.

      重要

      ヘッダー Content-type は Microsoft Flow によって自動的に追加されます。このヘッダーは必ずアクションから削除してください。Make sure you remove the Content-type header from actions, as this will be automatically added by Microsoft Flow. [セキュリティ] セクションに定義されている認証ヘッダーもアクションとトリガーから削除する必要があります。Authentication headers that have been defined in the Security section should also be removed from actions and triggers.

      サンプルからのインポート

    3. [Import (インポート)] を選択して、要求の定義を完了します。Select Import to complete the request definition. 同様の方法で応答を定義します。Define the response in a similar way.
  6. すべての操作の定義が済んだら、[Create (作成)] を選択してカスタム コンテナを作成します。Once you have all your operations defined, select Create to create your custom connector.
  7. カスタム コンテナを作成した後、[Test (テスト)] タブに移動して、API で定義した操作をテストします。Once you have created your custom connector, go to the Test tab to test the operations defined in the API. 接続を選択し、入力パラメーターを指定して、操作をテストします。Choose a connection, and provide input parameters to test an operation.

    カスタム コネクタのテスト

    呼び出しが成功すると、有効な応答を受け取ります。If the call is successful, you get a valid response.

    コネクタのテストの応答

クォータと調整Quota and throttling

  • カスタム コネクタの作成クォータについて詳しくは、「最適なプランをお選びください」ページをご覧ください。See the Microsoft Flow Pricing page for details about custom connector creation quotas. 他のユーザーから共有されているカスタム コネクタは、このクォータに含まれません。Custom connectors that are shared with you don't count against this quota.
  • カスタム コネクタで作成される接続ごとに、ユーザーは 1 分あたり最大 500 個の要求を行うことができます。For each connection created on a custom connector, users can make up to 500 requests per minute.

カスタム コネクタを共有するShare your custom connector

カスタム コネクタが完成したので、組織の他のユーザーと共有できます。Now that you have a custom connector, you can share it with other users in your organization. カスタム コネクタを共有した後、カスタム コネクタを削除するとコネクタへのすべての接続が削除されますが、他のユーザーが既に依存している可能性がある点に注意してください。Keep in mind that when you share an custom connector, others might start to depend on it, and deleting a custom connector deletes all the connections to the connector. 組織の外部のユーザーにコネクタを提供する場合は、「API コネクタの概要 (Microsoft Flow)」をご覧ください。If you want to provide a connector for users outside your organization, see Overview of certifying custom connectors in Microsoft Flow.

  1. flow.microsoft.com の上部のバーで、歯車アイコンを選択して設定メニューを開きます。In flow.microsoft.com, in the top bar, select the gear to open the settings menu. [Custom connectors (カスタム コネクタ)] オプションを選びます。Select the Custom connectors option.

    新しい接続

  2. コネクタの省略記号 [...] ボタンを選択し、[プロパティの表示] を選択します。Select the ellipsis (. . .) button for your connector, then select View properties.

    コネクタのプロパティの表示

  3. [共有] を選択し、コネクタへのアクセスを許可するユーザーまたはグループを入力します。Select Share, and then enter the users or groups to whom you want to grant access to your connector.

    カスタム コネクタの共有

  4. [保存] を選択します。Select Save.

次のステップNext steps

Postman Collection の作成方法を学習しますLearn how to create a Postman Collection

OpenAPI のカスタム拡張機能について学習しますLearn about custom OpenAPI extensions.

ASP.NET Web API を使用しますUse an ASP.NET Web API.

Azure Resource Manager API を登録しますRegister an Azure Resource Manager API.