ハウツーガイド：ファイルストリーミング（Rangeヘッダー）によるファイルのダウンロード
このセクションでは、ファイルストリーミングを通じてターゲットアプリケーション内のファイルをダウンロードするアクションの作成について説明します。
アクションのタイムアウト
SDKアクションには180秒のタイムアウト制限があります。
checkpoint!メソッドをファイルストリーミングアクションで使用すると、タイムアウト制限を超えるファイルを転送できます。 checkpoint!メソッドは、アクションの実行時間を確認します。 120秒を超えると、Workatoは公平な処理を確保するために、わずかな遅延を挟んでタイムアウトを更新します。
サンプルコネクター：Egnyte
{
title: 'My Egnyte connector',
# More connector code here
actions: {
download_object: {
title: 'Download file from selected folder',
description: lambda do |input, picklist_label|
"Download <span class='provider'>file</span> in <span class='provider'>Egnyte</span>"
end,
help: 'Download file contents from selected folder in Egnyte.',
input_fields: lambda do |object_definitions|
[
{
name: 'file_path',
label: 'File path',
hint: 'Select path of file.',
optional: false,
control_type: 'tree',
pick_list: 'file_path',
toggle_hint: 'Select file',
toggle_field: {
name: 'file_path',
type: 'string',
control_type: 'text',
label: 'File path',
optional: false,
toggle_hint: 'Use file path',
hint: "Provide complete path of file. Example: <b>/Private/Sample/file.csv</b>"
}
}
]
end,
execute: lambda do |connection, input|
file_path = input['file_path']&.gsub(/%2F/, '/')
# This API call retrieves metadata about the file. Not the file itself.
file_details = get("/pubapi/v1/fs/#{file_path}")
file_details['file_contents'] = workato.stream.out("download_file_by_path", { file_path: file_path, file_size: file_details['size'] })
file_details
end,
output_fields: lambda do |object_definitions|
[
{ name: 'path' },
{ name: 'name' },
{ name: 'size' },
{ name: 'file_contents' }
]
end
},
}
streams: {
download_file_by_path: lambda do |input, starting_byte_range, ending_byte_range, requested_byte_size|
# Example starting_byte_range = 0
# Example ending_byte_range = 10485759
# Example requested_byte_size = 10485760 (10MB)
chunk = get("/pubapi/v1/fs-content/#{input['file_path']}").
headers("Range": "bytes=#{starting_byte_range}-#{ending_byte_range}").
response_format_raw
# The output of the streaming callback should be an array.
# Firstly, passing the chunk of file
# Secondly, a boolean value that indicates if this is the final chunk
[chunk, ending_byte_range >= input['file_size']]
end
}
# More connector code here
}ステップ1 - アクションのタイトル、サブタイトル、説明、ヘルプ
優れたアクションを作成するための最初のステップは、アクションが何を行い、どのように実行するかを適切に伝え、ユーザーに追加のヘルプを提供することです。 そのため、Workatoではアクションのタイトルと説明を定義し、ヒントを提供できます。 簡単に言えば、タイトルはアクションのタイトルであり、サブタイトルはアクションの詳細を示します。 アクションの説明には、そのアクションが何を実現するかについての仕様と説明、および接続先アプリケーションのコンテキストが含まれます。 最後に、ヘルプセグメントでは、アクションを機能させるために必要な追加情報をユーザーに提供します。
このステップの詳細については、SDKリファレンスを参照してください
ステップ2 - 入力フィールドの定義
input_fields: lambda do |object_definitions|
[
{
name: 'file_path',
label: 'File path',
hint: 'Select path of file.',
optional: false,
control_type: 'tree',
pick_list: 'file_path',
toggle_hint: 'Select file',
toggle_field: {
name: 'file_path',
type: 'string',
control_type: 'text',
label: 'File path',
optional: false,
toggle_hint: 'Use file path',
hint: "Provide complete path of file. Example: <b>/Private/Sample/file.csv</b>"
}
}
]
end
ダウンロードファイルの入力フィールド
このコンポーネントは、オブジェクトを取得しようとしているユーザーに表示するフィールドをWorkatoに指示します。 たとえばEgnyteでファイルを見つける場合、ユーザーはダウンロードするファイルのfile_pathを入力する必要があります。
オブジェクト定義
object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義をobject_definitionsキーで別途指定できます。 このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。
この詳細については、SDKリファレンスを参照してください
ステップ3 - execute lambdaの定義
executeラムダには、ジョブの実行がこの特定のステップに到達したときに呼び出されるコードが含まれています。 ファイルダウンロードアクションの場合、主な目的は2つあります。関連するファイル詳細（名前、パス、ファイルサイズなど）を取得することと、ファイルコンテンツの実際のストリームを表すファイルストリームをインスタンス化することです。
この例では、まず入力から指定されたfile_pathを取得し、URLエンコードされた値を実際に意図した文字に置き換えて整形します。この場合は%2Fを/に置き換えます。 次に、/pubapi/v1/fs/#{file_path}エンドポイントにリクエストを送信してfile_detailsを取得します。 これにより、この特定のファイルについて必要な関連情報をすべて取得できます。
次に、file_details出力にfile_contentsという属性をもう1つ追加します。これはworkato.stream.outメソッドを使用してインスタンス化されたファイルストリームです。 このメソッドでは、使用するstreamラムダ関数download_file_by_pathを定義し、さらにハッシュ{ file_path: file_path, file_size: file_details['size'] }を渡します。このハッシュはラムダ関数への入力として渡されます。
execute: lambda do |connection, input|
file_path = input['file_path']&.gsub(/%2F/, '/')
# This API call retrieves metadata about the file. Not the file itself.
file_details = get("/pubapi/v1/fs/#{file_path}")
file_details['file_contents'] = workato.stream.out("download_file_by_path", { file_path: file_path, file_size: file_details['size'] })
file_details
end,ステップ4 - 出力フィールドの定義
このセクションでは、トリガーの出力として表示するデータピルを指定します。 各データピルのname属性は、executeラムダ関数の出力ハッシュ内のキーと一致している必要があります。
output_fields: lambda do |object_definitions|
[
{ name: 'path' },
{ name: 'name' },
{ name: 'size' },
{ name: 'file_contents' }
]
endoutput fieldsキーの詳細については、SDKリファレンスを参照してください
オブジェクト定義
object_definitionsが引数として渡されることに注意してください。 Workatoでは、コネクタービルダーがオブジェクトの定義をobject_definitionsキーで別途指定できます。 このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用します。
この詳細については、SDKリファレンスを参照してください
ステップ5：ストリーミングラムダ関数の定義
workato.stream.outを使用したファイルストリームのインスタンス化は、指定されたストリーミングコールバックdownload_file_by_pathと関連付ける必要があります。 これはstreamsハッシュで定義されるラムダ関数であり、このラムダ関数の主な目的は、渡された引数に基づいてファイルの特定のチャンクをダウンロードすることです。 /pubapi/v1/fs-content/#{file_path}に対してGETリクエストを使用し、Rangeのヘッダーを追加してstarting_byte_rangeからending_byte_rangeまでになるようにします。 サーバーから返されるデータがJSONレスポンスではなく純粋なバイナリデータである場合は、response_format_rawも追加する必要があります。
最後に、ストリーミングコールバックの出力はサイズ2の配列である必要があります。
- 最初のインデックスはバイナリデータです
- 2番目のインデックスは、ファイルの終わりを示すブール値です。 この場合、ファイルの想定サイズ（バイト単位）を取得できるため、ending_byte_rangeがファイルサイズより大きい場合、ファイルの終わりに達していることが分かります。
streams: {
download_file_by_path: lambda do |input, starting_byte_range, ending_byte_range, requested_byte_size|
# Example starting_byte_range = 0
# Example ending_byte_range = 10485759
# Example requested_byte_size = 10485760 (10MB)
chunk = get("/pubapi/v1/fs-content/#{input['file_path']}").
headers("Range": "bytes=#{starting_byte_range}-#{ending_byte_range}").
response_format_raw
# The output of the streaming callback should be an array.
# Firstly, passing the chunk of file
# Secondly, a boolean value that indicates if this is the final chunk
[chunk, ending_byte_range >= input['file_size']]
end
}TIP
ストリーミングコールバックを理解するには、ストリームコンシューマーとあわせて考えるのが最もわかりやすいです。 ストリームコンシューマーはストリーミングコールバックを制御します。まず単一のデータチャンクをリクエストし、それをダウンストリームシステムにアップロードしてから、ファイル全体がストリーミングされるまでこのプロセスを何度も繰り返します。 そのため、starting_byte_rangeとending_byte_rangeはストリーミングコンシューマーからリクエストされたバイト範囲を表します。 requested_byte_sizeは合成引数であり、ストリームを生成するエンドポイントに提供できるバイトがもうないかどうかを比較して、ファイルの終わりを示すために役立ちます。 このシグナルは、レシピを続行するためにストリームコンシューマーに送信されます。
Last updated: