OpenAPI
OpenAPIコネクターは、OpenAPI仕様を使用してAPIエンドポイントを記述する任意のアプリケーションを操作するために使用できる汎用コネクターです。
注: 最適なエクスペリエンスを得るには、RESTful APIでコネクターを使用することをお勧めします。 詳細については、制限事項セクションを参照してください。
基本
- OpenAPIとは
- Swaggerファイルとは
- OpenAPIコネクターでできること
- OpenAPIコネクターを使用すべきタイミング
- OpenAPIコネクターを使用してカスタムコネクターを作成する方法
- OpenAPIコネクターのトリガーとは
- OpenAPIコネクターで実行できるアクション
OpenAPIとは
OpenAPIは、RESTful Webサービスの記述、生成、利用、および可視化のための、機械可読なインターフェースとして機能する仕様です。
Swaggerファイルとも呼ばれるOpenAPIドキュメントは、さまざまな目的を果たすために使用できます。
- APIドキュメントの生成
- さまざまなプログラミング言語でのサーバーおよびクライアントの生成
- テストケース生成の自動化
- ... その他多数
詳細については、OpenAPIのリソースを確認してください。
Swaggerファイルとは
Swaggerファイルは、APIで使用可能なエンドポイントを記述し、次のデータを含みます。
- エンドポイントメソッド
- エンドポイントパス
- ヘッダー
- パラメーターおよびクエリ文字列
- リクエストおよびレスポンススキーマ
例: このサンプルSwaggerファイルの一部では、POST /petエンドポイントについて記述しています。
paths:
/pet:
post:
tags:
- pet
summary: Add a new pet to the store
operationId: addPet
requestBody:
$ref: https://api.swaggerhub.com/domains/Colon-Org/PetStore-Objects/1.0#/components/requestBodies/PetRequest
responses:
'405':
description: Invalid input
security:
- petstore_auth:
- 'write:pets'
- 'read:pets'OpenAPIコネクターでできること
OpenAPIコネクターは、ユーザーが提供したSwaggerファイルを解析し、その内容を使用して、アクション、入力フィールドと出力フィールド、オブジェクトなどを含むユーザーインターフェースをWorkatoで生成します。 ただし、コネクターの品質はSwaggerファイルの内容に依存することに注意してください。
インターフェースをカスタマイズする必要がある場合は、OpenAPIコネクターをテンプレートとして使用してカスタムコネクターを構築できます。 例: コネクターにカスタムアイコンまたは認証が必要な場合は、OpenAPIコネクターを開始点として使用し、必要に応じてカスタマイズします。
OpenAPIコネクターを使用すべきタイミング
次の場合は、OpenAPIコネクターの使用を検討してください。
次の図は、OpenAPIコネクターの使用を検討するタイミング、および他のコネクターを使用するタイミング、またはカスタムコネクターを構築するタイミングを示しています。
OpenAPIコネクターを使用してカスタムコネクターを作成する方法
OpenAPIコネクターはアプリケーションにすばやく簡単に接続する方法ですが、特定のアプリケーション用にカスタムコネクターを作成したい場合があります。
たとえば、次のことを行う場合があります。
- アプリケーションの名前とアイコンを使用してUXを向上させる
- コネクション設定を簡素化する
- カスタム認証フローを実装する
開始するには、OpenAPIコネクターを使用したカスタムコネクターの作成ガイドを確認してください。
注: コネクターのコードをカスタマイズすると、新しいバージョンへのアップグレードが複雑になる可能性があります。 詳細については、OpenAPIコネクターのソースコードのアップグレードガイドを参照してください。
サポートされている機能
Swaggerのバージョンと形式
OpenAPIコネクターは、次のSwaggerバージョンと形式をサポートしています。
提供するSwaggerファイルは、有効なYAMLまたはJSONであり、サポートされているいずれかのバージョンの仕様に準拠している必要があります。
認証方法
OpenAPIコネクターは、次の認証方法をサポートしています。
- なし
- Basic
- ヘッダー
- クエリパラメーター
- OAuth 2.0: 認可コードグラント
- OAuth 2.0: クライアント資格情報グラント
- OAuth 2.0: リソースオーナーパスワードグラント
詳細については、OpenAPIコネクター認証ガイドを参照してください。
インターフェースのカスタマイズ
OpenAPIコネクターは、提供されたSwaggerファイルの内容に基づいてユーザーインターフェースを自動的に生成します。 ユーザーエクスペリエンスを向上させるために、次の要素をカスタマイズできます。
- オブジェクト名とヒント
- フィールド名とヒント
- 外部ドキュメントへのリンク
- APIオペレーションのグループ化
- 無視するフィールド
詳細と例については、OpenAPIユーザーインターフェースのカスタマイズガイドを確認してください。
トリガー
OpenAPIコネクターを使用すると、API上の特定のイベントに応答するトリガーを設定し、レシピエディター内でワークフローを開始できます。
OpenAPIトリガー
OpenAPIコネクターは、次のトリガーをサポートしています。
新規/更新済みレコード
個々のオブジェクトが作成または更新されたときにトリガーします。
新規/更新済みレコード（バッチ）
選択したオブジェクトのバッチが作成または更新されたときにトリガーします。
OpenAPIコネクターは、Swaggerファイル定義からAPIオペレーションをトリガーに直接マッピングします。 レコードの作成または更新を示すオペレーションIDは、対応するワークフローアクションを自動的にトリガーします。
詳細情報と例については、OpenAPIユーザーインターフェースのカスタマイズガイドを参照してください。
アクション
OpenAPIコネクターを使用すると、APIで定義されたオペレーションに対応するアクションを実行できます。
OpenAPIアクション
OpenAPIコネクターは、次のアクションをサポートしています。
レコードの作成
APIを使用して新しいレコードを作成します。
カスタムアクション
一意のAPIオペレーション用のHTTPリクエストを構築します。
レコードの削除
APIを使用して既存のレコードを削除します。
操作の実行
APIで定義された特定のオペレーションを実行します。
IDによるレコード詳細の取得
一意の識別子に基づいてレコードの詳細を取得します。
レコードの検索
APIを介して検索条件を使用してレコードを検索します。
レコードの更新
既存のレコードの詳細を変更します。
OpenAPIコネクターが提供されたSwaggerファイルを解析すると、APIオペレーションは上記のサポートされるアクションのいずれかに割り当てられます。 例: 新しいpetレコードを作成するエンドポイントは、Create recordアクションに割り当てられます。
詳細情報と例については、OpenAPIユーザーインターフェースのカスタマイズガイドを参照してください。
制限事項
OpenAPIには、次の制限事項があります。
コネクターの品質はSwaggerファイルの内容に依存します。 コネクターはSwagger/OpenAPI仕様からユーザーインターフェースを構築します。 アクションとトリガーのリストには、仕様で定義されているオブジェクトが表示されます。 メニューに表示するには、そのオブジェクトを仕様に追加します。 たとえば、Create recordアクションにClientを表示するには、OpenAPI仕様に
Clientを追加します。コネクターはRESTful APIを対象としています。 最適なエクスペリエンスを得るには、RESTful APIでコネクターを使用することをお勧めします。 非REST APIでも機能する場合がありますが、APIオペレーションをアクションにグループ化する際に問題が発生する可能性があります。
セットアップ
OpenAPIコネクターを開始する準備はできましたか。 次のガイドを確認してください。
Last updated: