OAS生成コネクターの拡張
コネクターの生成は、多くの場合、コネクター構築の過程の出発点にすぎません。 以下では、コネクターの反復改善を継続する方法について、次のような推奨事項とガイドラインを示します。
TIP
以下の多くのポイントは、WorkatoのConnector SDKフレームワークに関する知識があることを前提としています。 可能な場合は、関連トピックの詳細情報へのリンクを提供します。
コネクションフィールドの調整
コネクターを生成する際、コネクション内のフィールド（APIキーなど）がユーザーにとって見つけにくい場合があります。 ユーザーがこれらの認証情報を簡単に見つける方法を理解しやすくするために、これらのフィールドにヒントを追加することをお勧めします。 これは、:fields属性の下にある:connectionハッシュで定義されたフィールドに追加できます。 たとえば、hint属性を各フィールドに追加できます。また、HTML互換であるため、リンクも含めることができます。
以下は、コネクションフィールドにヒントがない生成コードのサンプルです。
:connection => {
:authorization => {
:type => "api_key",
:apply => lambda do |connection|
headers(:"Ocp-Apim-Subscription-Key" => connection['Ocp-Apim-Subscription-Key'])
end
},
:fields => [
{
:name => "Ocp-Apim-Subscription-Key",
:label => "APIキー",
:control_type => "password",
:optional => false
}
],
:base_uri => lambda do |connection|
'https://api.mediavalet.com' + '/'
end
},
:test => lambda do
true
end,以下は、コネクションフィールドにヒントがある生成コードのサンプルです。
:connection => {
:authorization => {
:type => "api_key",
:apply => lambda do |connection|
headers(:"Ocp-Apim-Subscription-Key" => connection['Ocp-Apim-Subscription-Key'])
end
},
:fields => [
{
:name => "Ocp-Apim-Subscription-Key",
:label => "APIキー",
:control_type => "password",
:hint => "APIキーは<a href='www.example.com/api_key' target='_blank'>こちら</a>で確認できます"
:optional => false
}
],
:base_uri => lambda do |connection|
'https://api.mediavalet.com' + '/'
end
},
:test => lambda do
true
end,test APIリクエストの追加
コネクター内のtest lambdaには、ユーザーが指定した認証情報を利用し、2XX HTTPレスポンスを期待するシンプルなAPIテストを含めることを意図しています。 これにより、ユーザーが提供した認証情報が有効であることがWorkatoに通知されます。 ただし、コネクターを生成すると、test lambdaの出力が静的にブール値trueに設定されていることがわかります。これにより、ユーザーが認証情報を指定したときに誤検知が発生する可能性があります。
以下は、testブロックがtrueに設定された生成コードのサンプルです。
:connection => {
:authorization => {
:type => "api_key",
:apply => lambda do |connection|
headers(:"Ocp-Apim-Subscription-Key" => connection['Ocp-Apim-Subscription-Key'])
end
},
:fields => [
{
:name => "Ocp-Apim-Subscription-Key",
:label => "APIキー",
:control_type => "password",
:hint => "APIキーは<a href='www.example.com/api_key' target='_blank'>こちら</a>で確認できます"
:optional => false
}
],
:base_uri => lambda do |connection|
'https://api.mediavalet.com' + '/'
end
},
:test => lambda do
true
end,コネクターを調整するには、テストリクエストとしてユーザー入力をあまり必要としないシンプルなAPIエンドポイントを見つける必要があります。 一般的な例として、特定のレコードタイプのリストを取得し、結果セットを制限するエンドポイントが考えられます。
以下は、testブロックがassetsエンドポイントへのGETリクエストに設定され、1件の結果を取得する生成コードのサンプルです。
:connection => {
:authorization => {
:type => "api_key",
:apply => lambda do |connection|
headers(:"Ocp-Apim-Subscription-Key" => connection['Ocp-Apim-Subscription-Key'])
end
},
:fields => [
{
:name => "Ocp-Apim-Subscription-Key",
:label => "APIキー",
:control_type => "password",
:hint => "APIキーは<a href='www.example.com/api_key' target='_blank'>こちら</a>で確認できます"
:optional => false
}
],
:base_uri => lambda do |connection|
'https://api.mediavalet.com' + '/'
end
},
:test => lambda do
get('assets', top: 1)
end,デバッガーを使用してコネクションのテストを続け、正しく機能していることを確認できます。
各アクションのタイトル、ヘルプなどの調整
コネクターは、アクションとトリガーについて、Create AssetやSearch Invoicesなどの特定の命名規則に従う必要があります。 これは、コネクターのベストプラクティスで詳しく説明しています。 ただし、OASからアクションを生成する場合、アクションのタイトル、サブタイトル、説明、ヘルプが当社の推奨事項に従う保証はありません。 エンドユーザーに一貫したエクスペリエンスを提供するため、これらのベストプラクティスに従うことを確認する責任はコネクター開発者にあります。
生成されたアクションのサンプル
:Assets_AddAttributesToAsset => {
:title => "アセット属性の作成",
:subtitle => "NextGen APIでアセット属性を作成",
:help => "アセットに属性を追加します。",
:input_fields => lambda do |object_definitions|
object_definitions['Assets_AddAttributesToAsset_input']
end,
:output_fields => lambda do |object_definitions|
object_definitions['Assets_AddAttributesToAsset_200_output']
end,
:execute => lambda do |connection, input, extended_input_schema|
call(:Assets_AddAttributesToAsset_execute, connection, input, extended_input_schema)
end
},各アクションについて、各title、subtitle、help属性を確認し、必要に応じて値を調整する必要があります。 エンドユーザーにとってより明確になるように、追加情報を加えることもできます。
以下は、subtitleとhelpを調整した生成アクションのサンプルです。
:Assets_AddAttributesToAsset => {
:title => "アセット属性の作成",
:subtitle => "アセット属性（MIME TypeやSourceなど）を作成",
:help => "アセットに属性を追加します。アセットをさらに分類するために、MIME TypeやSourceなど、アセットの任意の属性を追加できます。",
:input_fields => lambda do |object_definitions|
object_definitions['Assets_AddAttributesToAsset_input']
end,
:output_fields => lambda do |object_definitions|
object_definitions['Assets_AddAttributesToAsset_200_output']
end,
:execute => lambda do |connection, input, extended_input_schema|
call(:Assets_AddAttributesToAsset_execute, connection, input, extended_input_schema)
end
},アクションのさまざまな属性の詳細を確認してください。
アクションの入力/出力フィールドの調整
アクションの入力フィールドと出力フィールドが、期待どおりの形式になっていない場合があります。たとえば、これらのフィールドに指定されたラベルの軽微な調整や、追加のヒントが必要になることがあります。 生成されたアクションのスキーマは、任意のアクションのinput_fieldsおよびoutput_fields lambdaで参照されているobject_definition内にあります。スキーマを調整するには、そこで定義されているWorkatoスキーマを変更するだけです。
たとえば、生成されたアクションのサンプルでは、
:Assets_AddAttributesToAsset => {
:title => "アセット属性の作成",
:subtitle => "NextGen APIでアセット属性を作成",
:help => "アセットに属性を追加します。",
:input_fields => lambda do |object_definitions|
object_definitions['Assets_AddAttributesToAsset_input']
end,
:output_fields => lambda do |object_definitions|
object_definitions['Assets_AddAttributesToAsset_200_output']
end,
:execute => lambda do |connection, input, extended_input_schema|
call(:Assets_AddAttributesToAsset_execute, connection, input, extended_input_schema)
end
},Workatoスキーマを保持する:Assets_AddAttributesToAsset_inputおよびAssets_AddAttributesToAsset_200_outputというobject_definitionsを見つけることができます。 object_definitionsは複数のアクションで使用される可能性があるため、1つの変更が他のレシピに影響する場合があることに注意してください。 生成されたWorkatoスキーマには、direction、location、original_nameなど、見慣れないフィールドが含まれている場合もあります。 これらの属性を変更または削除しないでください。
トリガーの追加
コネクターを生成してもトリガーは作成されませんが、生成されたコネクター内の既存のコンポーネントを再利用してトリガーを作成できます。 類似する"Search records"アクション用に生成された同じmethodsとobject_definitionsを再利用して、これらのトリガーを作成できます。 または、必要に応じてこれらのトリガーをゼロから構築することもできます。
Last updated: