|
| 本文の表 | レコードをHTMLの表としてメール本文に描画 | 
|
| CSV添付 | レコードをCSVファイルとして添付 | 
|
「概要は本文の表で見せて、明細は CSVで渡す」といった使い分けができます。ただし、CSV 添付とテキスト添付は排他で、どちらか一方しか選べません。
## 要点の通知が主な目的
ここが一番大事なポイントです。Email Reportはダイジェストと通知のためのコンポーネントであり、大量データのエクスポート用ではありません。
出力にははっきりとした上限があります。
| 出力 | 上限 |
| - | - |
| メール本文の表 | 最大1,000行 |
| CSV／テキスト添付 | 最大500,000行、かつ20MB |
つまり「異常データ20件を担当者に知らせる」「日次KPIを1行で送る」「例外リストを300行のCSVで渡す」、こういった用途にはぴったりです。一方、「全顧客マスタ800万行を毎日送る」といった要件には向きません。データセットそのものを渡したいときは、S3やSnowflakeなどのファイル／ウェアハウス系のデスティネーション・コンポーネントを使い、Email Reportは\*\*「処理が終わったこと」と「要点」を知らせる役割に留めるのが定石\*\*です。
## 設定してみる
パッケージ画面でEmail Reportコンポーネントを配置し、上流のコンポーネント（変換や集計の出力）と接続したら、設定画面を開きます。設定は3つのセクションに分かれています。
### 1. Recipients & Message（宛先とメッセージ）
| 項目 | 説明 |
| - | - |
| Send to | 受信者のメールアドレス。カンマ区切りで複数指定できます |
| Subject | 件名。`${variable}` 形式の変数参照が使えます |
| Intro text（任意） | 表の上に表示される本文テキスト。プレーンテキストでもHTMLでも記述でき、こちらも変数参照が使えます |
**件名と本文で変数が使える**、というのがこのコンポーネントの地味に効くポイントです。変数は実行時に解決されるので、
```
件名: [日次チェック] 取り込みエラー ${_JOB_SUBMISSION_TIMESTAMP}
```
のように書いておけば、実行ごとに日時の入ったユニークな件名になります。受信トレイでスレッドが1本にまとまってしまう問題を避けられますし、後から「どの実行のメールか」を追いやすくなります。
利用できる変数は、下記の2種類です。
| 項目 | 説明 |
| - | - |
| ユーザ定義変数 | パッケージ変数として定義した値。たとえば`${client}`に得意先名を入れておけば、`件名: ${client}様向け月次レポート`のように差し込める |
| 事前定義変数 | `${_JOB_ID}`（ジョブ識別子）、`${_JOB_SUBMISSION_TIMESTAMP}`（ジョブ投入時刻のUTC・ISO-8601形式）など |
事前定義変数の一覧は[ETL: System and Pre-Defined Variables](https://www.integrate.io/docs/etl/system-and-pre-defined-variables)を参照してください。
Intro textには「このレポートは自動送信です」「件数が0件の場合は異常ありません」といった受信者向けの前置きを入れておくと、問い合わせがぐっと減ります。HTMLが使えるので、``で強調したり、社内Wikiへのリンクを張ったりもできます。
### 2. Email Contents（メールの中身）
ここで先ほどの3つの出力形式を選びます。**最低1つは選択** が必要です。また、選択可能な添付ファイルは1種類だけです。
* **Preview the rows as a table in the email body**
* レコードをHTMLの表として本文に描画（最大1,000行）
* **Attach the rows as a CSV file**
* CSVとして添付。ファイル名を指定可能（既定`report.csv`）
* **Attach the rows as a text file**
* タブ区切りテキストとして添付。ファイル名を指定可能（既定`report.txt`）
ファイル名は既定のままでも動きますが、`report.csv`が毎日届くとダウンロードフォルダで衝突します。`daily_errors.csv`のように用途が分かる名前に変えておくことをおすすめします。
### 3. Delivery Options（配信オプション）
* **Fail the job if the report email cannot be sent**
* 既定で有効で、メールを送信できなかった場合にジョブを失敗させます
* **When the input is too large for one email**
* Truncate and send（既定・データをサンプリングして送信）
* Fail the job（ジョブを停止）から選択します
1つ目のオプションは、既定の有効のままにしておくのが基本です。これを無効にすると、メールが届かなくてもジョブは「成功」として終わります。通知が届かなかったことに誰も気づかない、という一番まずい状態になりかねません。**「届かなかった」をジョブ失敗として可視化する**、という設計思想です。
2つ目は、データが上限を超えたときの挙動です。「件数が多いこと自体が異常のサイン」であれば`Fail the job`、「上位数百件だけ見えれば十分」であれば`Truncate and send`を選びます。
## 実践：「注文失敗を通知する」パッケージ
前日の取り込みでバリデーションに引っかかった注文レコードを、注文担当にメールする例を見てみましょう。
### パッケージ構成
```
[Database Source: staging_orders]
│
▼
[Filter: status = 'failed']
│
▼
[Select: order_id, customer_id, error_reason, created_at]
│
▼
[Email Report Destination]
```
### 設定内容
| セクション | 設定 |
| - | - |
| Send to | `data-quality@example.com, ops-lead@example.com` |
| Subject | `[Daily_report]Failed order list(${_JOB_SUBMISSION_TIMESTAMP})` |
| Intro text | `失敗した注文処理一覧です。対応手順は社内ウィキをご確認ください。
` | | Email Contents | 本文の表 ✅ ／ CSV添付 ✅（ファイル名`failed_orders_report.csv`） | | Delivery Options | 送信失敗時にジョブを失敗させる: 有効 ／ 入力が大きすぎる場合: `Truncate and send` | #### 受け取るメールのイメージ
ここでポイントになるのが、手順3の**Selectで列を絞っている**ところです。Email Reportは上流から来た列をそのまま出力するので、絞り込みをしないと内部IDやハッシュ値まで並んだ、読みづらい表がそのまま届きます。「メールに載せる直前に整える」。この一手間が、レポートの読みやすさを決めます。
### 差出人アドレスを自社ドメインにする
既定の差出人は`reports@integrate.io`です。社内向けの通知ならこのままでも実用上は困りませんが、顧客にレポートを送る用途では自社ドメインにするのが適切です。
自社ドメインは **Settings > Account Settings > Email Sender** で設定します。
| 項目 | 説明 |
| - | - |
| From address | 送信元アドレス |
| From name（任意） | 受信者に表示される表示名 |
| Reply-to（任意） | 返信先アドレス |
なお、**カスタムドメインの利用にはアカウントの承認が必要**です。利用を予定している場合は、早めにサポートへ申請しておきましょう。あわせて、そのドメインでSPF／DKIMなどの送信ドメイン認証を設定しておくと、迷惑メール判定を避けられます。
## つまずきやすいポイントと運用のコツ
**1. 上流で絞る。メールで絞らない。**
Email Reportには「先頭のN件だけ送る」という設定はないので、件数のコントロールは上流のフィルター(Filter)や集計(Aggregate)で行うのが前提です。「本文の表は1,000行まで」という上限は、その設計思想の表れでもあります。
**2. 「0件のときも送るか」を決めておく。**
エラー通知の場合、0件なら送らない方が親切に見えますが、「今日は届かなかった」が「異常なし」なのか「ジョブが動かなかった」なのか区別できなくなります。**0件でも送る**（Intro textに「0件＝異常なしです」と明記しておく）方が、運用上は安全です。
**3. 件名は必ず変数で一意にする。**
毎日同じ件名のメールは、メールクライアント側で1スレッドに畳まれてしまいます。`${_JOB_SUBMISSION_TIMESTAMP}`を件名に入れておくだけで、この問題は避けられます。
**4. 送信失敗時のジョブ失敗は、有効のままにする。**
既定で有効になっている理由を尊重しましょう。「通知が届かないこと」に気づける仕組みは、通知そのものと同じくらい重要です。
**5. 機微なデータを本文に載せない。**
メールは転送されますし、受信者の端末にも残ります。個人情報や決済情報を扱うパイプラインでは、メールには「件数と概要」だけを載せ、明細はS3などの安全な場所に出力して、そのリンクだけをIntro textに書く、という設計を検討してください。
## まとめ
Email Report Destinationは、派手な機能ではありません。けれど「データは出ているのに、見てほしい人に届いていない」という、データ基盤でよく起きる最後のギャップを埋めてくれます。
* 通知・ダイジェスト向け。大量エクスポートには使わない（本文1,000行／添付500,000行・20MB）
* 件名と本文で変数が使えるので、実行ごとに文脈のあるメールを送れる
* 送信失敗をジョブ失敗として扱える（既定で有効）ので、通知の不達に気づける
* 読みやすさは上流のFilter／Selectで決まる
まずは、既存のパッケージの終端に1つ足してみるところから。所要時間は10分もかかりません。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.