# OpenAPI コネクターを使用したカスタムコネクターの作成
アプリケーション固有のコネクターは、高い柔軟性と最適なユーザーエクスペリエンスをもたらします。しかし、コネクターを一から作成するには時間がかかることがあります。コネクターの作成にかかる時間を短縮するために、アプリケーションコネクターの作成の土台またはテンプレートとして、OpenAPI コネクターを使用することができます。
一度変換が済むと、そのアプリケーション固有の新しいコネクターは、Workato レシピ内で、ユニバーサルな OpenAPI コネクターの代わりに使用できます。
これが適切なアプローチかどうかを判断するにはどうすればよいのでしょうか。 ほとんどのケースでは、OpenAPI コネクターをそのまま使用できます。一方で、カスタムコネクターの作成が必要になる場合もあります。たとえば以下のようなときです。
- コネクターの名前やアイコンをカスタマイズする
- カスタム認証フローを実装する
- アプリ固有のコネクション項目を追加する
- コネクションの設定を簡素化する
上記のいずれかが必要な場合は、カスタムコネクターの作成が最適なアプローチである可能性が高いでしょう。
# 前提条件
OpenAPI コネクションを設定するには、以下が必要です。
Workato コネクター SDK に関する知識。 詳細については、SDK のドキュメントを参照してください。
Workato で以下を行える権限 :
- コネクションの作成
- SDK コネクターの作成と変更
以下の条件を満たす Swagger ファイル :
- OpenAPI v2 または v3 仕様 (opens new window)に準拠している
- 有効な JSON または YAML である
# ステップ1 : コネクターをインストールする
最初のステップは、Workato アカウントでコネクターをインストールすることです。すでにインストール済みの場合は、ステップ 2に進んでください。
[Install connector] をクリックします。
[Release latest version] をクリックします。
# ステップ2 : Workato で新しい SDK コネクターを作成する
# ステップ2.1 : OpenAPI コネクターのソースコードをコピーする
まだの場合は、Workato アカウントにサインインします。
[Tools] > [Connector SDK] に移動します。
[OpenAPI] タイルをクリックします。
[Source code] の内容を選択してコピーします。
# ステップ2.2 : SDK コネクターを作成する
[Connector SDK] ページに戻ります。
[+ New connector] をクリックします。
[Source code] の内容を、ステップ2.1でコピーしたコードで置き換えます。
鉛筆のアイコン またはコネクターの名前をクリックして、コネクターの名前を変更します。
コネクターのアイコンを置き換える場合は、以下のようにします。
デフォルトのアイコンの上にマウスポインターを移動して、 [Upload] を表示させます。
アイコンをクリックします。
新しいアイコンを選択してアップロードします。
[Save] をクリックしてコネクターを保存します。
# ステップ3 : コネクターの設定をカスタマイズする
TIP
バージョンのアップグレードを簡素化するために、ソースコードは必要な場合にのみカスタマイズすることをお勧めします。コネクターのカスタマイズが多いほど、アップグレードは複雑になります。
このステップでは、コネクターのコネクション設定の変更方法を示します。これには、以下の2つの方法があります。
- カスタム項目を追加するかデフォルトのコネクション項目を変更する。
- コネクション値をハードコードする。この方法は、ユーザー用のコネクション設定を簡素化するのに有用です。たとえば、ユーザーに OpenAPI ドキュメントへのリンクの指定を求める代わりに、これをハードコードすることができます。
コネクション項目の詳細については、OpenAPI のデフォルトのコネクション項目についてリファレンスを参照してください。
# コネクション項目の追加と変更
コネクション項目を追加または変更するには、connection.fields リストを探します。Workato はこのリストを使用してコネクション用のユーザーインターフェイスを生成します。
デフォルトでは、Workato はこのリストに OpenAPI document source や Document URL といった項目を用意します。表示させたくない項目がある場合は、リストから削除するか、その値をハードコードして、ユーザーが指定する必要をなくすことができます。
たとえば、接続先アプリケーションにおいて、認証に API キーのみが必要であるとします。この場合、すべてのデフォルト項目を削除し、api_key という1つの項目を追加できます。この項目で、ユーザーは API キーを入力するように求められます。
connection: {
fields: [
{
name: 'api_key',
label: 'API key',
hint: 'Refer to <a href="<YOUR_DOC_URL>"><APP> docs</a> ' \
'for help retrieving your API key.',
optional: false,
control_type: 'password'
}
]
}
TIP
各項目とそのプロパティの定義の詳細については、SDK スキーマのリファレンスを参照してください。
# コネクション値のハードコード
ユーザーのためにコネクション設定を簡素化することを目的として、コネクション値をハードコードすることができます。ユーザーに代わって必要なコネクション値を指定することにより、設定手順が1つ省かれます。
認証関連の項目を除き 、コネクション値は adjust_connection メソッド内にハードコードできます。このメソッドはソースコード内の他のメソッドから呼び出され、コネクターの動作に影響します。このメソッドに変更が加えられると、それが呼び出されるすべての場所で変更が適用されます。
以下の規則を使用して、項目を adjust_connection に追加してください。<FIELD_NAME> を項目の name (名前) に、value (値) をハードコードされた値に置き換えます。
methods: {
adjust_connection: lambda do |connection|
connection.merge (
{
'<FIELD_NAME>' => '<VALUE>',
'<FIELD_NAME>' => '<VALUE>'
}
)
end,
[...]
}
たとえば、前セクションでは、デフォルトのコネクション項目すべてを connection.fields から削除しました。このコネクターを正しく設定するには、そうした項目の値を adjust_connection でハードコードする必要があります。
上記の例では、既存のコネクション項目を connection.fields から削除しました。このコネクターを正しく設定するには、そうした項目を adjust_connection でハードコードする必要があります。
methods: {
adjust_connection: lambda do |connection|
connection.merge (
{
'definition_mode' => 'url',
'definition_url' => 'http://redocly.github.io/redoc/openapi.yaml',
'base_url' => 'https://petstore.swagger.io/v2/',
'advanced' => {
'test_endpoint' => '/pet/findByStatus?status=%3D%5B%22available%22%5D',
'documentation_href' => 'http://redocly.github.io/redoc/'
}
}
)
end,
[...]
}
名前や説明など、項目の詳細については、OpenAPI のデフォルトのコネクション項目についてのリファレンスを参照してください。
注 : 必須項目は、connection.fields に含まれているか、adjust_connection でハードコードされている必要があります。
# ステップ4 : 認証を実装する
注
デフォルトのソースコードに含まれるコネクション項目によって認証の詳細が指定されている場合は、このステップを飛ばすことができます。
認証項目がカスタマイズされているか、カスタム認証フローが必要な場合は、ソースコードの authorization セクションを変更する必要があります。
変更する必要があるメソッドは、要件および使用している認証方法により異なります。詳細については、認証に関する SDK リファレンスの記事を参照してください。
たとえば、ステップ 3では、デフォルトのコネクション項目を api_key という1つの項目で置き換えました。この場合、カスタム認証フローを正しく設定するには、authorization.apply メソッドを更新する必要があります。
実装に取り組むには以下の2つの方法があり、それぞれにメリットがあります。
コードをほぼそのまま使用し、コネクション変数のみを更新する。 注 : 元のコードを維持することにより、ソースコードのアップグレードが容易になります。
例を表示
authorization: { type: 'custom_auth', apply: lambda do |connection| connection = connection.merge( { 'auth_method' => 'header', 'auth_headers' => "api_key: Bearer #{connection['api_key']}", } ) auth_method = connection['auth_method'] # don't apply any credentials when requesting the API definition if connection['definition_mode'] == 'url' && current_url == connection['definition_url'] auth_method = nil end case auth_method when 'none' # nothing to do when 'basic' username = connection['basic_auth_user'] password = connection['basic_auth_password'] encoded = "#{username}:#{password}".encode_base64 headers(Authorization: "Basic #{encoded}") when 'header' auth_headers_input = connection['auth_headers'] lines = auth_headers_input.split(/\n+|\r+/) headers_hash = {} lines.each do |header| next if header.blank? header = header.split(':', 2) header_name = header[0] header_value = header[1].strip headers_hash[header_name] = header_value end headers(headers_hash) end end }, [...]既存のコードを新しいカスタムコードで置き換える。 この方法を取ると、コードは明確になり、読みやすくなります。ただしカスタマイズにより、ソースコードのアップグレードの適用が複雑になるというデメリットがあります。
例を表示
authorization: { type: 'custom_auth', apply: lambda do |connection| headers(api_key: => "api_key: Bearer #{connection['api_key']}") end }, [...]
# ステップ5 : オンプレミス接続を設定する
注
オンプレミス接続が不要な場合、このステップは飛ばすことができます。
オンプレミス接続が必要な場合は、 Workato オンプレミスエージェント (OPA) を通して通信するように、コネクターを設定することができます。詳細については、「オンプレミスエージェントの設定」ガイドを参照してください。
新しい OPA を設定したら、SDK コネクターのソースコードの始まりにある secure_tunnel キーを探します。
これが true に設定されている場合、コネクター設定の項目 [Is this app in a private network?] が使用可能になります。この場合、ユーザーは接続する OPA を選択できます。
# 次のステップ
これでカスタムコネクターを作成できました。ここから、以下のことを行うことができます。
Last updated: 2023/8/31 1:07:14