> ## Documentation Index
> Fetch the complete documentation index at: https://docs.core.sprocket.bz/llms.txt
> Use this file to discover all available pages before exploring further.

# 自動処理（ワークフロー）：ステップの種類

> ワークフローで使えるステップ（インポート、プロセス、エクスポート、同期、条件分岐、通知など）の役割と主な設定を説明します。

> この記事は Spumote のソースコードから生成した試験出力です。内容は確認中のため、正式な仕様は担当者に確認してください。

## この機能でできること

ワークフローは「ステップ」を組み合わせて作ります。ステップには、データを動かすもの・加工するもの・処理の流れをつなぐもの・失敗に備えるものがあります。エディタの「ステップを追加」では、次の 4 つのグループに分かれて表示されます。

| グループ | ステップ（画面表示） | ひとことで |
| - | - | - |
| 動かす | インポート / エクスポート / BigQuery コピー / エンゲージ同期 | データを取り込む・書き出す・移す・エンゲージへ送る |
| 加工する | プロセス / ストレージ操作 | SQL で加工する・ファイルを移動/コピー/削除する |
| つなぐ | 条件分岐 / 通知 / アセット更新の記録 | 分岐する・知らせる・「できた」を記録して次を動かす |
| 備える | エラーハンドラ | 失敗を受け止めて後始末する |

## 画面の場所

データ › 自動処理（ワークフロー）› 処理一覧 › （ワークフローを開く）› ステップを追加

追加したステップを選ぶと設定画面が開きます。設定は全種類共通で次の 4 ブロックの順に並びます。

1. 基本（ジョブ型のステップでは「ジョブ設定」。ここで「ジョブを作成」します）
2. 設定（種類ごとの設定）
3. 実行時の振る舞い（結果チェック・リトライ。既定は折りたたみ）
4. 前後関係（このステップが生むアセット・依存ステップ。既定は折りたたみ）

## 各ステップの役割と主な設定

### インポート（import）

外部（S3 / GCS / SFTP）のファイルを BigQuery に取り込みます。ステップごとに専用の「ジョブ」を持ち、「ジョブ設定」ブロックの「ジョブを作成」から作り、作成後は「ジョブ設定を編集」（キャンバス上のステップを右クリックしたメニューでは「ジョブを編集」）で直せます。主な設定は取込元（接続先・パス）、ファイル形式、取込先テーブル、取込モード（S3 のみ「全件取込」「増分取込」から選べます。GCS と SFTP は毎回テーブルを上書きする全件取込です）です。

### プロセス（processing）

BigQuery の SQL でデータを集計・加工し、結果を出力先テーブルに書き込みます。書き込み方法は画面では「Append (追記)」「Overwrite (上書き)」から選びます。

### エクスポート（export）

BigQuery のテーブルまたは SQL の結果を、S3 / GCS / SFTP へファイルとして書き出します。画面で選べる形式は CSV と Parquet です（Parquet は形式内蔵の圧縮が使われ、圧縮は選べません）。CSV では圧縮を選べます。

### BigQuery コピー（bq\_copy）

BigQuery のテーブルや partition（日付などで区切られたテーブルの一部）を、そのまま別のテーブルへコピーします。SQL を使わないためスキャン課金が発生せず、リージョンをまたぐコピーにも対応します。

| 設定項目 | 内容 |
| - | - |
| コピー元テーブル / コピー先テーブル | プロジェクト ID（省略可）・データセット ID・テーブル ID |
| 書き込みモード | 洗い替え（WRITE\_TRUNCATE） / 追記（WRITE\_APPEND） |
| partition 範囲コピー | 開始（inclusive）〜終了（exclusive）の各日を partition 単位でコピー |

### エンゲージ同期（engage\_sync）

BigQuery のデータをエンゲージ（顧客管理・配信の機能）へ同期します。ステップの「設定」ブロックで設定します。

| 同期モード | 内容 |
| - | - |
| コンタクト（属性同期） | BQ の 1 行 = 1 顧客として、会員 ID ごとに属性を更新します |
| イベント（backfill） | BQ の 1 行 = 1 イベントとして、過去の購買などの行動履歴を取り込みます |

主な設定項目:

| 項目 | 内容 |
| - | - |
| 同期元 BigQuery | プロジェクト ID・データセット ID・テーブル / ビュー ID |
| member\_id 列（必須） | 顧客を特定する列。空の行はスキップして件数を記録 |
| 属性同期する列 / 列名 → 属性名の rename | 同期する列の指定と名前の付け替え（省略時は member\_id 列以外すべて） |
| フル同期（コンタクト） | ソースから消えた顧客に「source\_missing」の印を付ける（削除はしない） |
| イベント名 / 発生時刻の列 / 一意キー列 / properties に入れる列（イベント） | 固定名か列参照でイベント名を指定。一意キーで重複取り込みを防ぐ |
| 同期後にセグメントを再評価 | 同期完了後にセグメントのフル評価を 1 回実行 |

### アセット更新の記録（asset\_materialization）

実際の処理は行わず、「このデータができた」という記録（アセットの実体化）だけを残すステップです。記録すると、そのアセットを待っている他のワークフローが動きます。区切り単位は「変数から」「固定値」「なし（マスタデータ）」から選びます。

### 条件分岐（switch）

前のステップの結果に応じて、次に進むステップを選びます。

| 条件タイプ | 内容 |
| - | - |
| 結果値 | 参照ステップの結果のカラムが「一致する値」と同じかで判定 |
| ステップ状態 | 参照ステップのステータス（成功 / 失敗 / スキップ）で判定 |

ケースは複数追加でき、どれにも一致しない場合の行き先を「デフォルト（一致なし）」で決めます。

### エラーハンドラ（error\_handler）

指定した対象が失敗したときに起動し、下流に通知やプロセスをつなげられます。新規作成したワークフローには「全体」を監視するエラーハンドラが最初から入っています。

| 項目 | 選択肢 |
| - | - |
| エラー監視対象 | ワークフロー全体（任意のステップ失敗時） / 個別のステップ |
| ハンドラチェーン完了後の動作 | ワークフローを中止 / 次のステップに続行 |

### 通知（notification）

メール・Webhook で通知を送ります。送り先は「通知セット」（設定 › 通知 で作成）から選び、「メール件名」「メール本文」「Webhook JSON ペイロード」を編集できます。本文には \{\{workflow\_name}} \{\{workflow\_run\_id}} \{\{step\_name}} \{\{error\_message}} \{\{run\_timestamp}} の差し込みが使えます。

### ストレージ操作

S3 / GCS 上のファイルを操作します。プロバイダ、認証情報、バケット、ソース プレフィックス、移動先 プレフィックスと、操作（移動 / コピー / 削除 / 一覧取得）を設定します。

## 活用例

* **取り込み後の整理**: インポートの後にストレージ操作（移動）で処理済みフォルダへファイルを移し、二重取り込みを防ぐ。
* **配信リストの自動更新**: プロセスで「直近 30 日購入者」の属性を集計 → エンゲージ同期（コンタクト）で反映 → 同期後にセグメントを再評価。

## 注意点・制限

* インポート / エクスポートはジョブの指定が必須、プロセスはジョブかストレージ操作の設定が必須です。条件分岐はケースが 1 件以上、アセット更新の記録はアセットが 1 件以上必要です。
* 通知の件名は 500 文字、本文は 5,000 文字、Webhook ペイロードは 10,000 文字まで。
* BigQuery コピーの追記（WRITE\_APPEND）はリトライ時に二重追記になるため、再実行する運用では partition 指定＋洗い替えが推奨されています。partition 範囲コピーの範囲は最大 400 日、1 回のコピー完了待ちは最大 35 分です。

## 詳しい設定（データ担当者向け）

* **BigQuery コピーの partition 指定**: テーブル ID に decorator を付けます（例: events$20260801 = DAY、10 桁で HOUR。変数なら events$$\{BATCH_DATE\}）。partition 範囲コピー有効時はテーブル ID に「$」を含められません。範囲コピーには「同一リージョン向け（各日を直接コピー）」と「リージョンをまたぐ向け（ステージ表を経由して 2 段でコピー）」の 2 方式があり、リージョンをまたぐ場合はコピー先の partition 指定・追記ができないため後者を使います。
* **エンゲージ同期のイベント重複防止**: 一意キー列を指定するとその値から、省略時はテーブル・会員 ID・イベント名・発生時刻から決まる ID を作り、同じイベントを 2 回取り込んでも 1 件になります。

## 関連ページ

* [02-3-1 自動処理（ワークフロー）：基本と作り方](/dsv2/workflow-basics)
* [02-3-3 自動処理（ワークフロー）：実行タイミングと変数](/dsv2/workflow-triggers-and-variables)
* [02-3-4 自動処理（ワークフロー）：失敗への備えと運用](/dsv2/workflow-failure-and-operations)
* [02-5 生成データ（アセット）](/dsv2/assets)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.