コネクター構築 - 便利なコーディングパターン
Workatoのプラットフォームには、修正作業が進行中の既知の制限がいくつかあります。 それまでの間、カスタムコネクターを構築する際に発生する可能性がある制限を簡単に解決する方法をいくつか紹介します。
特殊文字の処理
既知の制限の1つは、Workatoのデータピルと密接に関連しています。 入力フィールドまたは出力フィールドがこれらの特殊文字を含む名前で定義されている場合、入力フィールドは表示されず、出力データピルは正しくレンダリングされません。
-<>!@#$%^&*()+={}:;'"`~,.?たとえば、次のように定義されたスキーマは
{
name: “due-date”
}文字列入力フィールドとして表示されず、データピルはデータピルではなく長い文字列としてレンダリングされます。
スキーマの名前に特殊文字が含まれている場合、データピルは正しくレンダリングされません
代わりに
名前の特殊文字を置き換えて、正しくレンダリングする必要があります
幸いなことに、コネクターにも組み込むことを強く推奨する回避策があります。 （適合する場合は、次の内容をコピーして貼り付けることもできます。） 各executeブロックの開始時と終了時に呼び出せる、format_schema、format_payload、format_schemaという3つのメソッドを作成します。 以前の例でアクションを定義したときにも、同様のことを行いました。
format_schema
サンプルコードスニペット:
format_schema: lambda do |schema|
if schema.is_a?(Array)
schema.map do |array_value|
call('format_schema', array_value)
end
elsif schema.is_a?(Hash)
schema.map do |key,value|
if %w[name].include?(key.to_s)
value = call('replace_special_characters',value.to_s)
elsif %w[properties toggle_field].include?(key.to_s)
value = call('format_schema', value)
end
{ key => value }
end.inject(:merge)
end
end,名前にキーが含まれるフィールドはエラーの原因となるため、無効なスキーマを受け取り、名前を処理可能な形式に変換できるサービスメソッドが必要です。 上記のメソッドは、指定されたスキーマを再帰的に検索し、特殊文字を有効な文字列に置き換えます。 例:
[
{
control_type: "text",
label: "Txn date",
type: "string",
name: "Txn-Date"
}
]次のように変換されます
[
{
control_type: "text",
label: "Txn date",
type: "string",
name: "Txn__hyp__Date"
}
]これにより、ラベルが保持されるため、エンドユーザーには違いが見えない状態でフィールドをWorkatoに表示できます。 このサービスメソッドは、静的スキーマまたは動的スキーマのいずれにも呼び出すことができます。
format_payload
サンプルコードスニペット:
format_payload: lambda do |payload|
if payload.is_a?(Array)
payload.map do |array_value|
call('format_payload', array_value)
end
elsif payload.is_a?(Hash)
payload.map do |key, value|
key = call('inject_special_characters',key)
if value.is_a?(Array) || value.is_a?(Hash)
value = call('format_payload', value)
end
{ key => value }
end.inject(:merge)
end
end,このメソッドは、ジョブからの入力がexecuteブロックを通じて渡されるときに呼び出す必要があります。 この段階で、このメソッドは入力ハッシュを再帰的に検索し、特殊文字が置き換えられたことを示すマーカーを見つけて、元の形式に戻します。 このメソッドの戻り値は、すべての特殊文字が元に戻された形式化済みペイロードです。
format_response
サンプルコードスニペット:
format_response: lambda do |payload|
if payload.is_a?(Array)
payload.map do |array_value|
call('format_response', array_value)
end
elsif payload.is_a?(Hash)
payload.map do |key, value|
key = call('replace_special_characters',key)
if value.is_a?(Array) || value.is_a?(Hash)
value = call('format_response',value)
end
{ key => value }
end.inject(:merge)
end
end,レスポンスを処理する場合でも、Workatoの有効なスキーマに照合し直す必要があります。 そのため、ネットワークトラフィックから得られるレスポンス内のキーを変換し、特殊文字を置き換える必要があります。 これは、HTTP呼び出しからレスポンスを受け取った直後に実行する必要があります。
replace_special_charactersとinject_special_characters
サンプルコードスニペット:
replace_special_characters: lambda do |input|
input.gsub(/[-<>!@#$%^&*()+={}:;'"`~,.?|]/,
'-' => '__hyp__',
'<' => '__lt__',
'>' => '__gt__',
'!' => '__excl__',
'@' => '__at__',
'#' => '__hashtag__',
'$' => '__dollar__',
'%' => '__percent__',
'^' => '__pwr__',
'&' => '__amper__',
'*' => '__star__',
'(' => '__lbracket__',
')' => '__rbracket__',
'+' => '__plus__',
'=' => '__eq__',
'{' => '__rcrbrack__',
'}' => '__lcrbrack__',
';' => '__semicol__',
'\'' => '__apost__',
'`' => '__bckquot__',
'~' => '__tilde__',
',' => '__comma__',
'.' => '__period__',
'?' => '__qmark__',
'|' => '__pipe__',
':' => '__colon__',
'\"' => '__quote__'
)
end,
inject_special_characters: lambda do |input|
input.gsub(/(__hyp__|__lt__|__gt__|__excl__|__at__|__hashtag__|__dollar__|\__percent__|__pwr__|__amper__|__star__|__lbracket__|__rbracket__|__plus__|__eq__|__rcrbrack__|__lcrbrack__|__semicol__|__apost__|__bckquot__|__tilde__|__comma__|__period__|__qmark__|__pipe__|__colon__|__quote__|__slash__|__bslash__)/,
'__hyp__' => '-',
'__lt__' => '<',
'__gt__' => '>',
'__excl__' => '!',
'__at__' => '@',
'__hashtag__' => '#',
'__dollar__' => '$',
'__percent__' => '%',
'__pwr__' => '^',
'__amper__' => '&',
'__star__' => '*',
'__lbracket__' => '(',
'__rbracket__' => ')',
'__plus__' => '+',
'__eq__' => '=',
'__rcrbrack__' => '{',
'__lcrbrack__' => '}',
'__semicol__' => ';',
'__apost__' => '\'',
'__bckquot__' => '`',
'__tilde__' => '~',
'__comma__' => ',',
'__period__' => '.',
'__qmark__' => '?',
'__pipe__' => '|',
'__colon__' => ':',
'__quote__' => '"'
)
endエンコードされたクエリパラメーターの回避
WorkatoのSDKは、GETリクエストのクエリパラメーターを自動的にエンコードするため、正確な形式を想定するAPIのリクエストが失敗する可能性があります。 これを回避するには、クエリ文字列を手動で構築し、URLに直接追加します。
例:
url = "https://api.example.com/reports"
query_string = "addressVerification=true&poi[latitude]=#{input['latitude']}&poi[longitude]=#{input['longitude']}"
get("#{url}?#{query_string}")これにより、APIで必要とされる正確な大文字小文字と構造が保持されます。 APIが生のクエリ文字列を想定している場合、またはエンコードされた文字を拒否する場合は、このパターンを使用します。
SDKコンソールでのヘッダーの大文字小文字
SDKコンソールでコネクターをテストすると、大文字と小文字が区別されるヘッダーの大文字小文字が誤って表示される場合があります。
この問題はコンソールインターフェースにのみ影響します。 SDKコンソールは表示用にヘッダー名を整形しますが、Workatoはコードで定義された正確な大文字小文字でリクエストを送信します。
例:
case_sensitive_headers(BPMCSRF: connection['BPMCSRF'],
Cookie: connection['Cookie'])コンソールでは、BPMCSRFのようなヘッダーがBpmcsrfとして表示される場合がありますが、実際のリクエストでは正しい大文字小文字が使用されます。 コードを変更する必要はありません。
概要
コネクターでは、オブジェクトベースのアクションとトリガーを強く推奨します。 これらはユーザーのユーザーエクスペリエンスを向上させるだけでなく、適切に実装すればコネクターの拡張もはるかに容易になります。 ここで取り上げた主な概念は次のとおりです。
- 各オブジェクトのベーススキーマをサービスメソッドで定義する。 アクションタイプに基づいてスキーマを調整できる入力引数を含めることを忘れないでください。
- 選択されたオブジェクトに基づいて適切な入力フィールドスキーマと出力フィールドスキーマを取得するには、object_definitionsを使用します。
- アクションまたはトリガーを定義する際は、すべてのブロック、特に
descriptionブロックを必ず宣言してください。 これにより、ユーザーにとっての使いやすさが大幅に向上します。 - 一般的な処理はexecuteブロック内に収め、個別の処理には専用のオブジェクトexecuteメソッド（
create_invoice_executeなど）を活用します。 例:create_#{object}_executeメソッドを使用する前に、executeブロックでformat_paylodとformat_responseを使用します。
使いやすさのルール
優れたコネクターは、優れたアーキテクチャを備えているだけでなく、見た目も操作感も優れています。 コネクターを使いやすくする方法について、さらに読み進めてください。
Last updated: