# How-toガイド - ファイルストリーミングを介してファイルをダウンロードする（範囲ヘッダー）
このセグメントでは、ファイルストリーミングを介してターゲットアプリケーション内のファイルをダウンロードするアクションの作成方法について説明します。
# サンプルコネクタ - Egnyte
{
title: '私のEgnyteコネクタ',
# 他のコネクタコードがここにある
actions: {
download_object: {
title: '選択したフォルダからファイルをダウンロードする',
description: lambda do |input, picklist_label|
"<span class='provider'>Egnyte</span>で<span class='provider'>ファイル</span>をダウンロード"
end,
help: 'Egnyteの選択したフォルダからファイルの内容をダウンロードします。',
input_fields: lambda do |object_definitions|
[
{
name: 'file_path',
label: 'ファイルパス',
hint: 'ファイルのパスを選択してください。',
optional: false,
control_type: 'tree',
pick_list: 'file_path',
toggle_hint: 'ファイルを選択',
toggle_field: {
name: 'file_path',
type: 'string',
control_type: 'text',
label: 'ファイルパス',
optional: false,
toggle_hint: 'ファイルパスを使用',
hint: "ファイルの完全なパスを指定してください。例：<b>/Private/Sample/file.csv</b>"
}
}
]
end,
execute: lambda do |connection, input|
file_path = input['file_path']&.gsub(/ja/%2F/, '/')
# このAPI呼び出しはファイルのメタデータを取得します。ファイル自体ではありません。
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|
# 例：starting_byte_range = 0
# 例：ending_byte_range = 10485759
# 例：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
# ストリーミングコールバックの出力は配列である必要があります。
# まず、ファイルのチャンクを渡します
# 次に、これが最後のチャンクであるかを示すブール値
[chunk, ending_byte_range >= input['file_size']]
end
}
# 他のコネクタコードがここにある
}
# ステップ1 - アクションのタイトル、サブタイトル、説明、およびヘルプの定義
良いアクションを作成するための最初のステップは、アクションが何を行い、どのように行うのかを適切に伝え、ユーザーに追加のヘルプを提供することです。そのため、Workatoでは、アクションのタイトル、説明、ヒントを定義することができます。単純に言えば、タイトルはアクションのタイトルであり、サブタイトルはアクションの詳細を提供します。アクションの説明には、アクションが何を達成し、どのようなアプリケーションのコンテキストで接続されるかについての仕様と説明が含まれます。最後に、ヘルプセグメントでは、アクションを動作させるために必要な追加情報をユーザーに提供します。
このステップの詳細については、SDKリファレンスをご覧ください。
# ステップ2 - 入力フィールドの定義
input_fields: lambda do |object_definitions|
[
{
name: 'file_path',
label: 'ファイルパス',
hint: 'ファイルのパスを選択してください。',
optional: false,
control_type: 'tree',
pick_list: 'file_path',
toggle_hint: 'ファイルを選択',
toggle_field: {
name: 'file_path',
type: 'string',
control_type: 'text',
label: 'ファイルパス',
optional: false,
toggle_hint: 'ファイルパスを使用',
hint: "ファイルの完全なパスを指定してください。例：<b>/Private/Sample/file.csv</b>"
}
}
]
end
ダウンロードファイルの入力フィールド
このコンポーネントは、オブジェクトを取得しようとするユーザーに表示するフィールドをWorkatoに伝えます。たとえば、Egnyteでファイルを検索する場合、ユーザーはダウンロードしたいファイルのfile_pathを入力する必要があります。
オブジェクトの定義
object_definitionsが引数として渡されることに注意してください。Workatoでは、コネクタビルダーがオブジェクトの定義をobject_definitionsキーで別々に提供できるようになっています。このキーは、オブジェクトの定義が大きい場合や動的に取得できる場合に使用されます。
詳細については、SDKリファレンスをご覧ください。
# ステップ3 - execute lambdaの定義
The execute lambdaには、ジョブの実行がこの特定のステップに到達したときに呼び出されるコードが含まれています。ファイルのダウンロードアクションの場合、2つの主な目的があります。1つは関連するファイルの詳細（名前、パス、ファイルサイズなど）を取得することであり、もう1つは実際のファイルコンテンツのストリームを表すファイルストリームをインスタンス化することです。
この例では、まず入力から与えられた file_path を取り、URLエンコードされた値を実際の意図された文字で置き換えることでフォーマットします。この場合、%2F を / に置き換えます。次に、/pubapi/v1/fs/#{file_path} エンドポイントにリクエストを送信して file_details を取得します。これにより、この特定のファイルに関する必要な情報がすべて取得されます。
次に、file_details 出力に file_contents という名前の属性を追加します。これは、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(/ja/%2F/, '/')
# このAPI呼び出しはファイルのメタデータを取得します。ファイル自体ではありません。
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,
# Step 4 - 出力フィールドの定義
このセクションでは、トリガーの出力として表示するデータピルを示します。各データピルの name 属性は、execute ラムダ関数の出力ハッシュのキーと一致する必要があります。
output_fields: lambda do |object_definitions|
[
{ name: 'path' },
{ name: 'name' },
{ name: 'size' },
{ name: 'file_contents' }
]
end
出力フィールドキーの詳細については、SDKリファレンスを参照してください。
オブジェクトの定義
object_definitions は引数として渡されます。Workatoでは、コネクタビルダーがオブジェクトの定義を object_definitions キーで別々に提供できるようになっています。このキーは、オブジェクトの定義が大きく、または動的に取得できる場合に使用されます。
詳細については、SDKリファレンスを参照してください。
# Step 5 - ストリーミングラムダ関数の定義
workato.stream.out を使用してファイルストリームをインスタンス化することは、指定されたストリーミングコールバック download_file_by_path と結び付ける必要があります。これは、streams ハッシュで定義されたラムダ関数であり、このラムダ関数の主な目的は、渡された引数に基づいてファイルの特定のチャンクをダウンロードすることです。starting_byte_range から ending_byte_range までの Range ヘッダを持つ /pubapi/v1/fs-content/#{file_path} へのGETリクエストを使用します。データが純粋なバイナリデータであり、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|
# 例：starting_byte_range = 0
# 例：ending_byte_range = 10485759
# 例：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
# ストリーミングコールバックの出力は配列である必要があります。
# まず、ファイルのチャンクを渡します。
# 次に、これが最後のチャンクであることを示すブール値です。
[chunk, ending_byte_range >= input['file_size']]
end
}
TIP
ストリーミングコールバックの理解は、ストリームコンシューマと一緒に考えると最も理解しやすいです。ストリームコンシューマは、ストリーミングコールバックを制御し、まず単一のデータチャンクをリクエストし、それをダウンストリームシステムにアップロードし、その後、ファイル全体がストリームされるまでプロセスを繰り返します。したがって、starting_byte_range と ending_byte_range は、ストリーミングコンシューマから要求されたバイト範囲を表します。requested_byte_size は、ストリーム生成エンドポイントが単に提供するバイトがもうないことを示すための合成引数であり、これはファイルの終わりを示します。このシグナルは、ストリームコンシューマに送信され、レシピの継続に使用されます。
Last updated: 2024/2/13 16:59:53