> ## 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.

# ファイル受け渡し（S3・GCS・SFTP）

> S3・GCS・SFTP の接続先の管理、Spumote 管理ストレージと SFTP アカウントの発行、ファイルの BigQuery への取り込みと書き出しの設定方法を説明します。

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

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

ファイル受け渡しは、社外や他システムとファイル（CSV など）をやり取りするための機能です。画面の説明文は「外部とやり取りするファイルを見る・置く。」です。

* S3（AWS のファイル置き場）、GCS（Google Cloud のファイル置き場）、SFTP（ファイル転送の仕組み）の接続先を一覧し、中のファイルを閲覧・操作する
* Spumote が用意する組織専用のファイル置き場（S3 / GCS / SFTP）を作り、取引先に渡す鍵を発行する
* 届いたファイルを BigQuery に取り込む（全件。S3 は増分も可）
* BigQuery のデータをファイル（CSV／Parquet など）に書き出して届ける

取り込み・書き出しは、自動処理（ワークフロー）のステップとして設定し、スケジュールやファイル到着をきっかけに動かします。

## 画面の場所

* ファイルの閲覧・接続先の追加: データ › つなぐ › ファイル受け渡し（S3 / GCS / SFTP）› エクスプローラー
* 接続先・鍵の管理: 設定 › 接続先 › ファイル接続先 ／ 認証情報（「02-8 接続先の設定」参照）
* 取り込み・書き出しの設定: データ › うごかす › 自動処理（ワークフロー）のステップ設定

## エクスプローラー

エクスプローラーには、組織で使えるファイル接続先が一覧表示されます。

| 列 | 意味 |
| - | - |
| 名前 | 接続先の名前。Spumote 管理の置き場には「一般」または「機密」のバッジが付きます |
| タイプ | S3／GCS／SFTP |
| 接続先 | バケット名（S3・GCS）またはホスト（SFTP） |
| パス / ユーザー | 使えるフォルダの範囲（Prefix）または SFTP のユーザー名 |
| ステータス | 有効／無効（接続テストに失敗している場合は無効） |
| 最終テスト・作成日時 | 接続テストを行った日時と作成日時 |

各行の操作:

* **開く**: ファイルブラウザが開きます。フォルダの移動（「上へ戻る」）、「フォルダ作成」、ファイルのアップロード、ファイルの「名前変更」・「削除」ができます。
* **Asset**: その置き場に関係する生成データ（アセット）の一覧を開きます。
* **削除**: 接続先（認証情報）を削除します。

接続先がまだない場合は「接続先がまだありません。接続先を追加してください。」と表示されます。

## 接続先を追加する

「接続先を追加」を押すと、次の 2 つから選べます。

| 選択肢 | 説明 |
| - | - |
| Spumote 管理ストレージ | Spumote が用意する組織専用の S3 / GCS / SFTP 置き場を使う。鍵はその場で発行されます |
| お客様管理ストレージ | お客様（取引先）が持つ S3 / GCS / SFTP の認証情報を登録する |

### Spumote 管理ストレージの作り方

1. 「Spumote 管理ストレージ」を選び、「タイプ」で S3・GCS・SFTP のいずれかを選びます。
2. 「名前」を入力します。
3. S3・GCS の場合は「権限」で Read/Write（読み書き）か Read Only（読み取りのみ）を選びます。
4. 機密レベルのロールを持つ利用者には「領域」が表示され、「一般」か「機密」を選べます（「02-9 機密データの取り扱いと組織データセット」参照）。
5. 「作成」を押すと鍵が発行され、接続情報が表示されます。シークレット（秘密の値）は一度しか表示されないため、安全な場所に保存してから「閉じる」を押します。保存を確認するまで閉じられません。

作成した鍵は、そのまま Spumote の認証情報としても登録され、取り込み・書き出しで使えます。鍵は組織専用のフォルダ（一般領域・機密領域それぞれ）の中だけにアクセスできるよう制限されます。

## SFTP アカウント

Spumote 管理の SFTP は、取引先がファイルを置く「SFTP アカウント」を組織ごとに発行できる仕組みです。認証は SSH 公開鍵のみで、パスワードは使えません。

### 作成のしかた（接続先の追加から）

1. 「Spumote 管理ストレージ」で「SFTP」を選び、「名前」を入力します。
2. 「ユーザー名の末尾（英数字・ハイフン）」を入力します。実際のユーザー名は「組織IDの短縮-入力した文字」の形で自動で作られます。
3. 鍵の作り方を選びます。
   * **鍵ペアを Spumote で作る**（既定）: 「鍵の種類」で Ed25519（推奨）か RSA 4096 を選び、「鍵ペアを生成して作成」を押します。秘密鍵は作成直後だけ表示されます。
   * **相手先の公開鍵を使う**: 「相手先の公開鍵を使う（認証情報は作成しない）」にチェックを入れ、「公開鍵」に貼り付けて「公開鍵を登録して作成」を押します。
4. 表示された接続情報（ホスト、ポート、ユーザー名、鍵など）を取引先に安全な方法で伝えます。名前は認証情報とアカウントで共通になります。

接続すると、ホームディレクトリが組織専用の領域になっており、その外は見えません。

### 鍵の管理

SFTP アカウントの一覧でアカウント名をクリックすると詳細が開き、「公開鍵」の欄で複数の公開鍵を管理できます。

* 「Spumote 用の鍵を発行」: 新しい鍵と認証情報を作ります。接続確認と利用先の切り替えを済ませてから、古い認証情報と鍵を削除します。
* 「外部用の公開鍵を登録」: 相手先が持つ鍵の公開鍵だけを登録します（認証情報は作りません）。対応する公開鍵の形式は ssh-ed25519 / ssh-rsa / ecdsa です。
* 「鍵を削除」: 不要になった鍵を外します。最後の 1 本は削除できません（別の鍵を追加するか、アカウントごと削除します）。

認証情報から参照されている鍵やアカウントは、先にその認証情報を削除しないと削除できません。接続を止めたいときは、使用中の認証情報を整理してからアカウントを削除してください。認証情報の削除だけでは、外部からの SFTP 接続は止まりません。

## 取り込み（ファイル → BigQuery）

自動処理（ワークフロー）の取り込みステップで、S3・GCS・SFTP 上のファイルを BigQuery のテーブルに読み込みます。

### 主な設定項目

| 項目 | 内容 |
| - | - |
| 認証情報 | 使う接続先。未登録の場合は先に追加します |
| パスパターン | 取り込むファイルの場所。S3・GCS では `*`（同じ階層の 0 文字以上）、`**`（階層をまたぐ）、`?`（任意の 1 文字）が使えます。S3 では日付プレースホルダ（例: `daily/{ts:%F:-1d:+0900}.csv` → 前日の日付のファイル）も書けます。SFTP は `( ) \` を含めると正規表現、含めなければ `*.csv` のようなパターンとして扱われます（混在はできません） |
| ファイル形式 | CSV / TSV ／ JSON（改行区切り / NDJSON）／ Parquet ／ Avro。S3 では「自動判定」も選べます |
| 詳細設定 | 圧縮（gzip など）、区切り文字（カンマ／タブ）、囲み文字、文字コード（UTF-8／Shift-JIS） |
| 取込モード | S3 のみ。全件取込／増分取込（下表）。GCS・SFTP は毎回テーブルを上書きする全件取込です |
| 取込先 | 取り込み先のデータセットとテーブル。どちらも選ばないと保存できません |

### 全件取込と増分取込（S3）

| 取込モード | 動き | 向いている場面 |
| - | - | - |
| 全件取込（マッチ全ファイルを毎回入替） | パスパターンに合うファイルをすべて読み、テーブルを毎回入れ替える | 毎回「全量」のファイルが届く会員マスタなど |
| 増分取込（日付 watermark / 処理済みスキップ） | ファイル名の日付を見て、前回より新しいファイルだけを取り込む | 日次の売上・行動ログなど、日付ごとにファイルが増えるもの |

増分取込では、次を設定します。

* **日付の位置**: ファイル名のどこに日付があるかを `{date}` で書きます（例: `orders_{date}.csv`、`{date}/data.csv`）。形を固定する場合は `{date:%Y%m%d}` のように書きます。入力すると「抽出例」が表示されます。
* **日付パターンの適用範囲**: 「ファイル名」か「キー全体」（フォルダ名に日付がある場合）。
* **処理済みファイルをスキップする**: 一度取り込んだファイルを再度読まないようにします。
* **詳細（正規表現）**: 「日付の位置」で表せない場合に、日付を取り出す正規表現を直接指定します。

## 出力（BigQuery → ファイル）

自動処理（ワークフロー）の出力（エクスポート）ステップで、BigQuery の SQL の結果をファイルにして S3・GCS・SFTP に置きます。

| 項目 | 内容 |
| - | - |
| 出力先タイプ | S3 ／ GCS ／ SFTP |
| 認証情報 | 出力先の接続先。S3・GCS は認証情報からバケットが自動で入ります |
| フォーマット | CSV ／ Parquet |
| 圧縮 | CSV は None（なし）か GZIP。Parquet はファイル形式に内蔵の圧縮（SNAPPY）が自動で使われます |
| 出力パス | S3・GCS はパステンプレート、SFTP はリモートパスとファイル名テンプレート |

### ファイル分割エクスポート

S3・GCS への出力では「ファイル分割エクスポート（カラム値ごとに別ファイルに出力）」が使えます。

| 項目 | 内容 |
| - | - |
| 分割カラム名 | この列の値ごとにファイルを分けます（例: リッチメニュー ID ごと） |
| 出力カラム | ファイルに含める列（カンマ区切り。空なら分割カラム以外の全列） |
| ファイル名テンプレート | `{value}`＝分割カラムの値、`{timestamp}`＝YYYYMMDD\_HHmmss、`{date}`＝YYYYMMDD、`{exportId}`＝ジョブ ID |
| ヘッダー行あり／空グループをスキップ | 列名行を入れるか、データのないグループを出さないか |
| 既存ファイルをバックアップ移動 | 出力前に既存ファイルを「バックアップ先パス」へ移します |

## 活用例

* **取引先からの日次売上ファイル**: 取引先専用の SFTP アカウントを発行し、置かれた `sales_YYYYMMDD.csv` を取り込みステップで BigQuery に読み込みます（日付ごとに増えるファイルを「前回より新しい分だけ」読みたい場合は、S3 の接続先で増分取込を使います）。データ到着チェック（センサー）と組み合わせると、ファイルが届いた時点で処理を始められます。
* **広告・配信ツールへのリスト連携**: 抽出したセグメントの会員 ID を CSV（GZIP）にして、連携先の S3 に毎朝出力します。
* **リッチメニュー別の配信リスト**: ファイル分割エクスポートで、リッチメニュー ID ごとに LINE ユーザー ID のファイルを作ります。

## 注意点・制限

* エクスプローラーからアップロードできるファイルは 1 ファイル 10GB までです。
* SFTP の認証は SSH 公開鍵のみです（パスワード不可）。公開鍵は ssh-ed25519 / ssh-rsa / ecdsa 形式に対応します。
* Spumote で生成する鍵は Ed25519 または RSA 4096 です。秘密鍵・シークレットは作成直後に一度だけ表示され、あとから再表示できません。
* SFTP アカウントの識別子は 40 文字まで、表示名は 200 文字までです。
* gzip 圧縮（.gz）のファイルは UTF-8 のみ対応で、Shift-JIS とは併用できません（保存時にエラーになります）。
* S3・GCS のパスパターンに正規表現は使えません（SFTP は使えます。S3 の増分取込の日付抽出は「日付の位置」または「詳細（正規表現）」で指定します）。
* Spumote 管理ストレージの鍵は、組織専用のフォルダの外にはアクセスできません。GCS の機密領域では、仕様上オブジェクト名の一覧は制限できません（中身の読み書きは機密領域内に限定されます）。
* 機密領域の置き場や SFTP アカウントは、機密レベルのロールを持たない利用者には表示されません。機密領域の有効化・無効化は owner（組織オーナー）のみ操作できます。
* 取り込み・書き出しの名前は、取り込みは 256 文字、書き出しは 255 文字までです。

## 関連ページ

* [02-3-1 自動処理（ワークフロー）：基本と作り方](/dsv2/workflow-basics)
* [02-3-2 自動処理（ワークフロー）：ステップの種類](/dsv2/workflow-steps)
* [02-5 生成データ（アセット）](/dsv2/assets)
* [02-6 データ到着チェック（センサー）](/dsv2/sensors)
* [02-8 接続先の設定](/dsv2/connections)
* [02-9 機密データの取り扱いと組織データセット](/dsv2/sensitive-data-and-org-dataset)


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