第3章 API 呼び出しによってトリガーされる Fuse Online インテグレーションの作成
必要時にインテグレーションの実行をトリガーするには、指定した REST API サービスでインテグレーションを開始します。この方法で開始するインテグレーションは、API プロバイダーインテグレーション と呼ばれます。API プロバイダーインテグレーションでは、REST API クライアントはインテグレーションの実行をトリガーするコマンドを呼び出しできます。
Fuse Online が API プロバイダーインテグレーションをパブリッシュすると、インテグレーションエンドポイントにネットワークアクセスできるクライアントはすべてインテグレーションの実行をトリガーできます。
デフォルトでは、Fuse Online は 3scale で使用する API プロバイダーインテグレーションの API サービス定義にアノテーションを付けます。
API プロバイダーインテグレーションを作成するための情報および手順は以下を参照してください。
3.1. API プロバイダーインテグレーションの作成
API プロバイダーインテグレーションを作成するには、インテグレーションが実行できるオペレーションを定義する OpenAPI ドキュメント (.json
、9.yaml
、または .yml
ファイル) を提供します。Fuse Online は各オペレーションの実行フローを作成します。各オペレーションのフローを編集し、そのオペレーションの要件に応じてインテグレーションデータを処理するコネクションおよびステップを追加します。
前提条件
インテグレーションが実行する REST API オペレーションの OpenAPI ドキュメントを提供または定義できる必要があります。
検証するには、API プロバイダークイックスタート の OpenAPI ドキュメントである raw の
task-api.json
ファイルをダウンロード します。Fuse Online が OpenAPI ドキュメントの提供を要求したときに、このファイルをアップロードできます。この代わりに、raw のtask-api.json
ファイルである https://raw.githubusercontent.com/syndesisio/syndesis-quickstarts/1.11/api-provider/task-api.json を指定できます。- 各 OpenAPI オペレーションのフローが計画されている必要があります。
- オペレーションのフローを追加する各アプリケーションまたはサービスのコネクションが作成済みである必要があります。
手順
- Fuse Online の左ナビゲーションパネルで Integrations をクリックします。
- Create Integration をクリックします。
- Choose a connection ページで API Provider をクリックします。
Start integration with an API call ページで以下を行います。
- REST API オペレーションを定義する OpenAPI ドキュメントがある場合は、OpenAPI ドキュメントをアップロードします。
- OpenAPI ドキュメントを定義する必要がある場合は、Create a new OpenAPI 3.x document または Create a new OpenAPI 2.x document を選択します。
Next をクリックします。
ドキュメントをアップロードした場合は、これを確認または編集します。
- Review/Edit をクリックして API Designer エディターを開きます。
必要に応じて確認や編集を行います。
任意の手順: ドキュメントによって OpenAPI 2 仕様が使用される場合に、API Designer でドキュメントを変換して OpenAPI 3 仕様に準拠するようにするには、Convert to OpenAPI 3 をクリックします。
- 右上の Save または Cancel をクリックし、エディターを閉じます。
- Next をクリックします。
ドキュメントを作成する場合は、Fuse Online で起動される API Designer エディターで以下を行います。
- 「API Designer での REST API 定義の作成」の説明どおりに OpenAPI ドキュメントを定義 します。
- 右上の Save をクリックし、エディターを閉じます。
- Next をクリックします。
結果
Fuse Online は OpenAPI ドキュメントが定義するオペレーションの一覧を表示します。
次のステップ
各オペレーションに対して、その オペレーションを実行するフローを定義 します。
3.1.1. API Designer での REST API 定義の作成
以下の手順では、REST API 定義を作成する方法を説明します。
サンプルについて
Task Management API のサンプルは、営業コンサルタントがお客様側の担当者と対話する際に必要なタスクを追跡するために使用する可能性のある単純な API をシミュレートします。「to-do」タスクの例には「create an account for a new contact (新規の担当者のアカウントの作成)」や「place an order for an existing contact (既存の担当者の注文処理)」が含まれる可能性があります。Task Management API のサンプルを実装するには、複数のタスク用のパスと、特定のタスク用のパスの 2 つのパスを作成します。その後、タスクを作成し、すべてのタスクまたは特定のタスクを取得し、タスクを更新してタスクを削除する操作を定義します。
前提条件
-
作成する必要のある API のエンドポイントを把握している必要があります。Task Management API のサンプルの場合、
/todo
および/todo/{id}
の 2 つのエンドポイントがあります。
手順
New API をクリックします。新規の API ページが開きます。
デフォルトでは、API Designer は OpenAPI 3 仕様を使用します。OpenAPI 2 仕様を使用する場合は、New API ボタンの横にある矢印をクリックし、OpenAPI 2 を選択します。
注記OpenAPI 2 仕様に基づいて API を開く場合、API Designer の Convert to OpenAPI 3 オプションを使用して、API が OpenAPI 3 仕様に準拠するよう変換することができます。
API 名を変更するには、以下を実行します。
- 名前にカーソルを合わせ、表示される編集アイコン ( ) をクリックします。
- 名前を編集します。たとえば、Task API を入力します。
- チェックマークアイコンをクリックして、名前変更を確認します。
任意で以下を行います。
- バージョン番号と説明を提供します。
- 連絡先情報 (名前、メールアドレス、および URL) を追加します。
- ライセンスを選択します。
- タグを定義します。
- サーバーを 1 つ以上定義します。
- セキュリティースキームを設定します。
- セキュリティー要件を指定します。
API のそれぞれのエンドポイントへの相対パスを定義します。フィールド名はスラッシュ (/) で開始する必要があります。
Task Management API のサンプルでは、2 つのパスを作成します。
-
複数のタスクのパス:
/todo
ID 別の特定タスクのパス:
/todo/{id}
-
複数のタスクのパス:
任意のパスパラメーターのタイプを指定します。
id
パラメーターのサンプルは、以下のようになります。Paths リストで、
/todo/{id}
をクリックします。id パラメーターが PATH PARAMETERS セクションに表示されます。
- Create をクリックします。
- description (説明) には、The ID of the task to find. と入力します。
「type (タイプ)」については、integer を 32-Bit integer として選択します。
Data Types セクションで、API の再利用可能なタイプを定義します。
- Add a data type をクリックします。
- Add Data Type ダイアログで名前を入力します。Task Management API のサンプルでは、Todo と入力します。
任意で、API Designer がデータタイプのスキーマの作成に使用するサンプルを指定できます。生成されるスキーマを編集できます。
Task Management API のサンプルでは、以下の JSON 例で開始します。
{ "id": 1, "task": "my task", "completed": false }
- オプションで、該当するデータタイプを指定して REST リソースの作成を選択できます。
Save をクリックします。サンプルを指定している場合、API Designer はそのサンプルからスキーマを生成します。
- オプションで、スキーマのプロパティーを編集し、新しいプロパティーを追加できます。
Task Management API のサンプルの場合、タイプ string の task という名前の 1 つのプロパティーを使用して、 Task という名前の別のデータタイプを作成します。
それぞれのパスについて、操作 (GET、PUT、POST、DELETE、 OPTIONS、HEAD、または PATCH) を定義します。
Task Management API のサンプルの場合、以下の表で説明されているように操作を定義します。
表3.1 Task Management API 操作
パス 操作 説明 リクエストボディー 応答 /todo
POST
新しいタスクを作成します。
メディアタイプ:
application/json
データタイプ: Taskステータスコード: 201 説明: Task created
応答ボディー: メディアタイプ:
application/json
データタイプ: Todo
/todo
GET
すべてのタスクを取得します。
該当なし
- ステータスコード: 200 説明: Task deleted
- ステータスコード: 400 説明: Task not deleted
/todo/{id}
GET
ID 別にタスクを取得します。
該当なし
-
ステータスコード: 200 説明: Task found for ID 応答ボディー: メディアタイプ:
application/json
データタイプ: Task - ステータスコード: 404 説明: No task with provided identifier found.
/todo/{id}
UPDATE
ID 別にタスクを更新します。
リクエストボディーのタイプ: Task
- ステータスコード: 200 説明: Completed
- ステータスコード: 400 説明: Task not updated
/todo/{id}
DELETE
ID 別にタスクを削除します。
該当なし
- ステータスコード: 200 説明: Task deleted
- ステータスコード: 400 説明: Task not deleted
- 「 API Designer での検証問題の解決」の説明どおりに問題 を解決します。
関連情報
- OpenAPI 仕様の詳細は、「https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md」を参照してください。
3.1.2. API Designer での検証問題の解決
API の作成および編集時に、API Designer は感嘆符 (!) アイコンと、API Designer タイトルバーの問題のリストを使って解決する必要のある問題を特定します。
前提条件
- API Designer で API を開いている必要があります。
手順
感嘆符 (!) アイコンで示唆される問題を検索します。以下に例を示します。
感嘆符アイコンをクリックして、問題の説明を表示します。以下に例を示します。
問題の説明で提供される情報に基づいて、問題のある場所に移動し、修正します。
たとえば、「Operation must have at least one response」(オペレーションには 1 つ以上の応答が必要) の問題を修正するには、GET オペレーションをクリックして開き、Add a response をクリックします。
応答の説明の入力後、問題は解決され、感嘆符アイコンは表示されなくなります。
すべての問題の概要については、以下のようになります。
右上にある Issues リンクをクリックします。
特定の問題の Go to a problem をクリックし、その問題を解決するために問題のある場所に移動します。