# OAS Generateコネクタの拡張
コネクタの生成は、通常、コネクタの構築の始まりに過ぎません。以下では、コネクタをさらに改善するための推奨事項とガイドラインを紹介します。
TIP
以下のポインタの多くは、WorkatoのConnector SDKフレームワークについての知識があることを前提としています。可能な限り、関連するトピックのリンクを提供しますので、詳細な情報を読むことができます。
# 接続フィールドの調整
コネクタを生成する際、接続のフィールド（例：APIキー）がユーザーにとって見つけにくい場合があります。これらのフィールドにヒントを追加して、ユーザーがこれらの認証情報を簡単に見つける方法を理解しやすくすることをおすすめします。これは、:connectionハッシュの:fields属性で定義されたフィールドに追加できます。たとえば、各フィールドに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ラムダには、ユーザーが指定した認証情報を利用し、2XXのHTTPレスポンスを期待する単純なAPIテストを含めることができます。これにより、ユーザーが有効な認証情報を提供したことをWorkatoに伝えることができます。ただし、コネクタを生成する際には、testラムダの出力が静的に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ブロックがGETリクエストでassetsエンドポイントに設定され、単一の結果を取得する場合のサンプル生成コードです。
: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 => "Create Asset Attributes",
:subtitle => "Create Asset Attributes in NextGen API",
:help => "Add attributes to an asset.",
: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 => "Create Asset Attributes",
:subtitle => "アセットの属性を作成します（例：MIMEタイプ、ソース）",
:help => "アセットに属性を追加します。アセットのMIMEタイプやソースなど、アセットのさらなる分類のための属性を追加できます。",
: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のラムダで言及されているobject_definition内の生成されたアクションのスキーマを見つけることができます。スキーマを調整するには、そこで定義されたWorkatoスキーマを変更するだけです。
例えば、サンプルの生成されたアクションの場合
:Assets_AddAttributesToAsset => {
:title => "Create Asset Attributes",
:subtitle => "Create Asset Attributes in NextGen API",
:help => "Add attributes to an asset.",
: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
},
Assets_AddAttributesToAsset_inputとAssets_AddAttributesToAsset_200_outputという名前のobject_definitionsを見つけることができます。ただし、object_definitionsは複数のアクションで使用される場合があるため、1つの変更が他のレシピに影響を与える可能性があります。また、生成されたWorkatoスキーマには、direction、location、original_nameなどの見慣れないフィールドが含まれている場合があります。これらの属性を変更または削除しないでください。
# トリガーの追加
コネクタを生成する際にはトリガーはありませんが、生成されたコネクタの既存のコンポーネントを再利用してトリガーを作成することができます。同様の「レコードの検索」アクションに対して生成された methods と object_definitions を再利用してこれらのトリガーを作成することができます。必要に応じて、これらのトリガーをゼロから構築することもできます。
Last updated: 2024/2/13 16:59:53