レターフローはステップを1つの配信経路につなぎます。
LetterflowはAPIリクエスト、値、判断を非同期処理につなぎます。ビジュアルビルダーでコンポーネントを配置・接続し、前の結果を次の処理に渡します。
下書き、検証、そして配達
未完成のグラフは下書きとして保存できます。Validateで必須項目、式、現在の依存関係を確認します。警告は該当コンポーネントを示し、準備が整うまでRunは使えません。編集すると以前の検証結果は消去されます。
グラフとValue・Conditionの結果を保存するCoordinatorリージョンを選びます。TinkererではすべてのLetterがそのリージョンを使います。有料プランでは複数の利用可能なリージョンを使えます。各Letterでリージョンと配達ポリシーを選んでください。
Letterflowの仕組み
Letterflowは有向グラフです。Startが実行を始め、経路が次に実行する処理を決めます。各コンポーネントの結果はStep IDで参照でき、認証、データ準備、分岐、後続リクエストに利用できます。
ビジュアルキャンバスで作成する
コンポーネントを追加
パレットのコンポーネントをクリックまたはタップすると、次の空き位置に配置されます。正確に配置したい場合はパレットからドラッグします。
ポートを接続
コンポーネント下部の出力ポートを、次のコンポーネント上部の入力ポートにつなぎます。タッチ端末では出力、接続先の入力の順にタップします。
キャンバスを移動
キャンバスは上から下へ流れます。空白をドラッグすると全体を移動でき、コンポーネント本体をドラッグするとその位置だけを変えられます。
設定
追加したコンポーネントは自動選択されます。あとから選択してもProperties Panelで設定を編集できます。
利用できるコンポーネント
開始
必須の開始点です。設定は必要なく、実行は必ずここから始まります。
レター
コンポーネント内で設定したリクエストを実行します。ステータス、ヘッダー、ボディ、解析済みJSONを後続のステップで使えます。
メール
前のステップの値を使い、1人の宛先へ通知を1通送ります。複数のメールコンポーネントを追加でき、実際に到達したステップだけが割り当てを使用します。有料プランで利用できます。
バリュー
リテラル、変数、補間関数を含むテキストを評価します。後続のコンポーネントはステップIDで出力を参照できます。最後に配置すると、単一の値がレターボックスに保存されます。
条件
条件文を評価し、trueならOutput 1、falseならOutput 2へ実行を分岐します。
Letterコンポーネントの設定
- リクエストを設定する。
メソッド、URL、ヘッダー、ボディをコンポーネントで直接設定します。これらの項目は前のステップの値を利用できます。
- Step IDを設定する。
loginやfetch_dataのような短く一意な識別子を使います。後続のコンポーネントはこの名前でレスポンスを参照できます。
- リダイレクトに従う
コンポーネントのリダイレクト上限回数を選びます。到達した各ホップは時間あたりの使用量に数えられます。
- フローのセッションを使用
ログイン用のLetterと、そのCookieを必要とする後続のHTTP/HTTPS Letterで「フローのセッションを使用」を有効にしてください。有効なLetterはCookieを送信・保存し、無効なLetterはセッションを変更しません。実行ごとに空のセッションから開始します。
メールコンポーネントを設定する
To、件名、本文と任意のReply-Toを設定します。4項目とも前のステップの変数や補間関数を使用できます。送信元はHatoが検証済みのアドレスを設定します。ToとReply-Toは各1件のみで、アドレスの一覧、CC/BCC、添付ファイル、独自ヘッダー、送信元の変更には対応しません。
プレーンテキストまたはHTMLを選択します。変数展開後の本文はUTF-8で64 KiB、件名は255バイトまでです。エンコード後のメール全体は256 KiBまでです。HTML内の変数はエスケープされ、実行可能な内容や画像は除去されます。基本書式、表、安全なリンクを使用できます。HTMLのエスケープ解除はできません。LetterboxではHTMLを実行せずソースを表示します。
To: {{ lookup.json.email }} · Subject: Result {{ lookup.status_code }}
Aspiring は暦月あたり1,000通、直近1時間あたり20通です。Coder は月3,000通、直近1時間あたり60通です。すべてのフローとリージョンで上限を共有し、月間割り当ては毎月1日00:00 UTCにリセットされます。Hubの使用量パネルで使用済み・予約済み・残りを確認できます。
受け付け済み、または送信結果が不明のメールは割り当てに計上されます。明確に拒否された送信の予約は解放され、入力エラーや割り当て超過による送信拒否は計上されません。後からバウンスしても計上は維持されます。履歴の削除やプラン変更では使用量はリセットされません。サービス全体の送信上限で送れない場合もあります。
Step IDまたはprev.outputからsuccess、status、error_code、error、message_idを参照できます。statusはaccepted、simulated、failed、unknownです。acceptedはプロバイダーの受付を意味し、受信箱への到達を保証しません。後から届くSESの配信・バウンス・苦情イベントは配信履歴を更新しますが、実行済みの経路は変更しません。開発時の初期設定はシミュレーションで、SendPulse SMTPでは受付のみを記録します。
エラー発生時の動作を選ぶ
メールとLetterには「エラー時：停止／続行」があり、初期値は停止です。メールの割り当て超過、変数展開後の入力エラー、送信失敗には、この設定を直ちに適用します。送信結果が不明なメールを自動再送することはありません。
Letterでは、HTTP 4xx、HTTP 5xx、接続失敗（DNS、TLS、タイムアウトを含む）のどれをエラーと扱うかを選択できます。初期状態ではすべて選択されています。Delivery Policyの再試行とリダイレクト後の最終結果で判定します。選択していない結果は通常の出力として続行し、接続失敗ではステータスコードがありません。その他のコンポーネントエラーは「エラー時」の設定に従いますが、キャンセルや実行の整合性を保てない失敗は常に停止します。
続行を選ぶと、失敗したステップとエラー詳細を残し、通常の出力先へ進みます。後続の条件やメールから失敗結果を参照できます。経路を最後まで実行すると「警告付きで完了」になります。Letterで選択していないエラー分類は警告に計上されません。
{{ fetch.error_code }} · {{ notice.status }}
バリューコンポーネントをテスト
Input欄はLetterflowの出力を定義します。Test欄ではCoordinator上でリテラルと静的なValue・Condition参照を評価できます。Letterの送信や結果の保存は行いません。実際のLetter出力はLetterflow実行時のみ利用できます。
{{ "hello world" | upper }}
このテストはHELLO WORLDを出力します。式は最大64 KiB、出力は最大1 MiBです。評価に失敗するとLetterflowが停止し、Conditionのfalseとは区別されます。
式やキャンバスのビルダーでto_text、to_json、to_xml、to_headerを使用できます。元の値は変更されません。to_headerは最上位の全キーを使用し、nullやネストしたオブジェクトを含む値全体をテキストに変換します。型を保持するにはValueでHeaders出力を選択してください。
JSONとXMLを編集
キャンバス右上の式ビルダーを開き、変数と対応する関数・引数を選び、生成した式をコピーして貼り付けてください。型の変更で後続の関数を削除する前に確認します。下書きはこのページ内にのみ保持され、コンポーネントを変更しません。ValueはJSON/XML出力に引き続き対応します。
Step IDと変数を使う
キャンバスの式ビルダーで変数を選択し、式をコピーしてコンポーネントのフィールドに貼り付けます。型ラベルは内容を読み込まずに参照元を示します。別の画面で行ったDirectoryの変更は再読み込みで反映されます。
各コンポーネントはStep IDをキーにLetterflowコンテキストへ結果を保存します。URL、ヘッダー、ボディ、Email欄、Value入力、Conditionで二重波括弧を使って前の値を参照できます。
| 参照元 | 例 | 用途 |
|---|---|---|
| バリュー | {{ my_value }} | 評価されたテキストを挿入します。 |
| Letterのステータス | {{ login.status_code }} | Condition（条件分岐）でレスポンスステータスを確認します。 |
| LetterのJSON | {{ login.json.token }} | パースされたJSONの値を後続のリクエストに渡します。 |
| 直前のコンポーネント | {{ prev.output }} | Step IDを指定せずに直前の結果を使用します。 |
Letterの場合、直前のコンポーネントの出力からレスポンスヘッダー、リクエストとレスポンスのボディ、URL、メソッド、ステータスも取得できます。
補間関数
補間関数は左側の値を変換します。URL、ヘッダー、本文、メールの各項目、値の入力、条件でパイプを使って連結できます。Jinjaのフィルターと同じ概念です。
{{ login.json.token | default "no-token" | trim | urlenc }}
引数にはGrafana形式のスペース区切り構文を使います。複数引数の関数ではJinja標準の括弧構文も利用できます。
| 関数 | 例 | 用途 |
|---|---|---|
default | {{ value | default "fallback" }} | 値が存在しないか空の場合に代替値を返します。 |
upper, lower | {{ name | upper }} | 英字の大文字・小文字を変換します。 |
b64enc, b64dec | {{ token | b64enc }} | UTF-8テキストをBase64でエンコード・デコードします。 |
printf | {{ name | printf "Hello, %s" }} | printf形式の書式文字列で値を整形します。 |
replace | {{ text | replace "old" "new" }} | 一致する箇所をすべて置換します。3つ目の引数で置換回数を制限できます。 |
urlenc, urldec | {{ value | urlenc }} | テキストをURLクエリ用にエンコード・デコードします。 |
re_replace | {{ text | re_replace "[0-9]+" "#" }} | 正規表現に一致する箇所をすべて置換します。 |
substr | {{ text | substr 5 }}{{ text | substr 2 5 }} | 引数が1つなら先頭n文字を取得します。2つなら開始位置を含み終了位置を含まない範囲の文字を取得します。 |
trim, ltrim, rtrim | {{ text | trim }} | 両端、左端、右端の空白を除去します。 |
re_exists | {{ text | re_exists "error" }} | 正規表現が一致すればTrue、一致しなければFalseを返します。 |
add | {{ value | add 1 2 -3 }} | 1つ以上の数値（整数、小数、負数）を値に加算します。 |
sub | {{ value | sub 5 2 }} | 値から1つ以上の数値を減算します。 |
mul | {{ value | mul 2 3 }} | 値に1つ以上の数値を乗算します。 |
div | {{ value | div 2 }} | 値を1つ以上の数値で除算します。 |
mod | {{ value | mod 3 }} | 指定した数で割った余り（剰余）を返します。 |
round | {{ value | round "up" 2 }} | 数値を丸めます。小数点以下の桁数を指定でき、初期値は0です。 |
条件と分岐
Conditionには2つの出力があります。trueの場合はOutput 1、falseの場合はOutput 2へ続きます。条件は評価前にテキストとしてレンダリングされるため、比較方法を意識して選択してください。
緩い等価比較
数値や基本的な確認では、値を引用符で囲みません。200または文字列の200としてレンダリングされたステータスコードを、200 == 200として比較できます。
{{ login.status_code }} == 200
厳密な文字列比較
完全一致のテキスト比較では、両辺を引用符で囲みます。数値と引用符付き文字列を混ぜると、比較がfalseになることがあります。
"{{ status_text }}" == "Success"
モバイル操作
| 目的 | タッチ操作 |
|---|---|
| コンポーネントを追加する | パレットのコンポーネントをタップするか、押したままキャンバスへドラッグします。 |
| コンポーネントを移動する | コンポーネント本体を押してドラッグします。縦横に移動できます。ポートやフォーム部品以外の場所から始めてください。 |
| キャンバスをパン | 空白のキャンバスをドラッグすると全体が移動します。コンポーネント本体をドラッグすると、そのコンポーネントだけが移動します。 |
| コンポーネントをつなぐ | 出力ポートをタップしてから入力ポートをタップします。有効な入力を選択するまで、アクティブな出力は選択されたままです。 |
| コンポーネントを編集する | コンポーネントをタップしてProperties Panelを使います。新規追加時には自動で開きます。 |
| コンポーネントを削除する | コンポーネントを選び、Properties PanelのDelete componentを選択して削除を確認します。 |
検証と実行のルール
- 有効なフローはStartコンポーネントから始まります。
- Hato APIは循環、1つの出力からの複数接続、1つの入力への複数接続を許可しません。
- 検証で循環を拒否します。ループ実行はサポートしていません。
- Letterflowは非同期で実行されるため、ジョブを監視し、配信後にレターボックスを確認します。
- 値・条件・メールの入力と結果はCoordinatorリージョンに保存されます。Letterのアーティファクトは各実行リージョンに残ります。保持された実行内容はすべて有効期限と削除の対象になります。
- LetterはDelivery Policyのタイムアウト、再試行、ペイロードサイズの上限に従います。メールコンポーネントは専用のメッセージサイズと送信上限を使用します。
分岐フローの手順
- フローを作る。
ダッシュボードでCreate Flowを選びます。Startコンポーネントは自動で配置されます。
- ログイン用Letterを追加する。
Letterコンポーネントを配置し、Startから接続してStep IDをloginにします。
- Conditionを追加する。
loginの結果をConditionに接続し、ステータスコードを200と比較します。
- 成功分岐を作る。
Output 1をfetchというLetterに接続し、loginのトークンをヘッダーへ渡します。
- もう一方の分岐を作る。
成功したリクエストの比較が偽の場合は出力2に接続します。HTTPや接続エラーを条件で調べるには、Letterの該当エラー分類のチェックを外すか、「エラー時：続行」を選択してください。
- 保存、検証、実行する。
名前を付けて保存し、Validateを押します。準備が整ったら実行し、固定された経路と保存済みの各コンポーネントをLetterboxで確認しましょう。
テンプレートの評価には CPU、メモリ、実行時間の制限があります。制限を超えた式は、コンポーネントを完了せずに失敗します。アップロードと鍵生成の許可は 1 回限り有効で、操作の受付にはレート制限があります。