# 公式APIの無い録音サービスから、別のSaaSへ音声を自動取り込みする指示書 ICレコーダー/録音アプリのクラウド（例: Plaud）にたまる音声を、文字起こし・要約SaaS（例: tl;dv）へ**無人で流し込む**ための指示書。音声の変換もストレージも使わず、中継URLを1枚挟むだけで成立する。 想定読者は AI エージェント。この MD を読ませればそのまま実装できる粒度で書く。 --- ## 0. 結論（先に読む） - 取り込み先の import API は **URL を渡す方式**が多い。素直に「元サービスの署名付きダウンロードURL」を渡すと、**成功レスポンスが返るのに何も起きない**という無言の失敗に高確率で当たる。 - 原因は次の2つで、どちらも中継プロキシ1枚で同時に解決する。 1. 取り込み先は取得前に **HEAD** を打つが、S3 等の署名付きURLは**署名がメソッド単位**なので HEAD に 403 を返す（GET は 200/206 で成功する）。 2. 取り込み先の URL 長制限（実測で **約2000文字**）。署名付きURLは 1500文字級あり、トークンに埋め込むと超える。 - **`jobId` が返っても取り込めたとは限らない**。必ず取り込み先の一覧を read-back して実体を確認する。 --- ## 1. 全体構成 ``` 元サービスのクラウド ──(署名付きURL)──> 中継プロキシ ──> 取り込み先SaaS ▲ │ └────────── 定期実行するCLI（状態管理・冪等） ◀──────┘ ``` - **CLI**（PC の定期実行）: 新着録音を検知 → 中継URLを組み立て → 取り込み先の import API を叩く → 取り込み済みを記録 - **中継プロキシ**（サーバーレス1関数）: HEAD/GET の両方に正しく応答し、実体は元サービスから都度読んで流すだけ。**音声は保存しない** --- ## 2. 元サービスの認証（公式APIが無い場合の典型） ブラウザのセッションを借りる形になる。多くのサービスが次の3段構成を取る。 | 種別 | 寿命の例 | 用途 | |---|---|---| | ユーザートークン (UT) | 1日 | ワークスペース一覧の取得、WT の発行 | | 更新トークン (URT) | 30日前後 | UT の更新 | | ワークスペーストークン (WT) | 数時間 | ファイル一覧・ダウンロードURL取得の実 bearer | ### 落とし穴 - **更新トークンの Cookie は `Path=/auth/refresh...` のようにパス限定で発行されることがある**。この場合ブラウザの Cookie 一覧に出てこないので「無い」と誤判定しやすい。 - **更新APIの応答は Set-Cookie ではなく body に入ることがある**（`access_token` / `refresh_token`）。Set-Cookie だけを見る実装は、更新期限が来た瞬間に必ず壊れる。**両方から拾う**こと。 - **更新してもトークンの有効期限が延びない**サービスがある（セッション単位で固定寿命）。この場合は定期的に人手での取り直しが要る。→ §6 の通知を必ず作る。 - **WT は有効期限前でも無効化される**（別クライアントが発行し直すと失効する）。`exp` だけを見ず、**失効を表すエラーを検出したら発行し直して1回だけ再試行**する。 - リージョンごとに API ホストが分かれる場合がある。トークン(JWT)の `region` クレームが最も確実な接続先の判定材料。ホストの許可リストは「既知の一覧」に加えて「そのサービスのドメイン配下なら受け入れる」ようにしておくと、増設に追従できる。 ### 更新トークンの取り出し方（人手が1回だけ要る場合） HttpOnly Cookie はスクリプトから読めない。ブラウザの Console で**そのサービス自身の更新APIを呼ぶ**と、応答 body に両方のトークンが返る。 ```js fetch('/auth/refresh-user-token', { method: 'POST', credentials: 'include', headers: { 'content-type': 'application/json' }, body: '{}' }).then(r => r.json()).then(j => console.log('COPY:' + JSON.stringify({ a: j.access_token, r: j.refresh_token }))) ``` Chrome は初回の貼り付けを拒否するので、**Console に `allow pasting` と手入力させる**手順を必ず案内に含める。 --- ## 3. 中継プロキシ（サーバーレス1関数・依存ゼロ） ### URL の形 ``` https:///a//audio. ``` - **トークンとファイル名は別のパスセグメントにする**。トークンは `.` を含むので、`/a/.` のような1セグメント形式にするとルーティングが誤爆する。 - `` は Content-Type の決定に使う。 ### トークンの中身 **署名付きURLを埋め込まない**（URL長制限に当たる）。代わりに「ダウンロードURLを取り直すのに必要な最小限」を入れ、**AES-256-GCM で暗号化**する。 ``` token = base64url( iv(12B) ‖ authTag(16B) ‖ ciphertext ) 平文 = {"b": , "w": <ワークスペーストークン>, "f": <ファイルID>, "x": <失効UNIX秒>} 鍵 = sha256(PROXY_SECRET) ``` - **暗号化は必須**。ワークスペーストークンは元サービスへの実アクセス権なので、平文で URL に載せると取り込み先のログに残った時点で漏洩する。 - 復号失敗 → 403 / 失効 → 410 / ベースURLがサービスのドメイン外 → 400。 ### 応答 - **HEAD**: 上流へ `Range: bytes=0-0` の GET を打ち、`Content-Range` から総サイズを得て、`200` + `Content-Type` + `Content-Length` + `Accept-Ranges: bytes` を**本文なし**で返す。これが無いと取り込みが無言で失敗する。 - **GET**: 上流へ GET（`Range` があれば転送）。ステータス(200/206)・`Content-Length`・`Content-Range`・`Accept-Ranges` を引き継ぎ、本文をストリームで流す。 - それ以外のメソッド → 405。`Cache-Control: private, no-store` を付ける。 - **取得したダウンロードURLのホストを許可リストで検査**する（オープンプロキシ化の防止）。リダイレクト追従による回避も塞ぐ。 - 秘匿値（シークレット・トークン・上流URL）をログにも応答本文にも出さない。 --- ## 4. 取り込み側 CLI ### 判定と絞り込み - ゴミ箱・取り込み済み・短すぎるもの（例: 5分未満）を除外 - **長さ上限を確認する**（例: 3時間超は受け付けない取り込み先がある）。超過分は別途分割が要るので、黙って落とさずログに出す - **初回実行では過去分を一括投入しない**。既存を「確認済み」として記録するだけにし、`--backfill` で明示された時だけ遡る。履歴が数百件ある環境で事故になる ### 時刻・長さの単位 秒とミリ秒が混在しがち。`start_time` / `end_time` があるなら**その差分と突き合わせて単位を実測で決める**。閾値だけで判定すると短い録音を取り違える。 ### 冪等性と状態 - 取り込み済みIDを状態ファイルに保存し、**書き込みは一時ファイル→rename の atomic write** - **Windows では上書き rename が `EPERM` で弾かれることがある**（ウイルス対策やインデクサが一瞬ハンドルを掴む）。取りこぼすと「取り込み済み」の記録が消えて**二重投入**になるので、短い再試行 → コピーへのフォールバックまで用意する ### 表示名 一覧APIの「ファイル名」フィールドが**ストレージ上のキー（ハッシュ.拡張子）**であることがある。人が付けた題名は別フィールドなので取り違えないこと。取り違えると取り込み先に意味不明な名前の会議が並ぶ。 --- ## 5. 検証（ここを省くと必ず嘘の完了報告になる） 1. **中継URL単体**で `HEAD` が 200 + 正しい `Content-Length`、`GET` が 206 を返すことを確認 2. **取り込み先の一覧を read-back** し、件数の増加と実体（名前・長さ）を確認 3. 可能なら**文字起こしの中身まで**確認する 4. 切り分けが必要な時は「**失効しない公開ファイルURL**」を1件流す対照実験を打つ。これが通って自前URLが通らなければ、原因は URL 側にあると確定できる 5. 対応形式は**ドキュメントより実測を優先**する。ドキュメントの対応一覧に無い形式が実際には通ることがある（逆もある） --- ## 6. 非同期処理には必ず「戻り導線」を作る 定期実行の標準出力は誰も読まない。**期限切れで止まっても誰も気付かない**のが最悪のケース。 - 残り日数がしきい値を切ったら/失敗したら、**復旧手順ごと**（URL・貼り付ける1行・完了の見え方）を通知する - 通知先は「その人が毎日必ず見る場所」かつ「実際に復旧作業をする場所」。エージェント経由で作業しているなら、エージェントのセッション開始時に提示させるのが最短 - 同じ用件は24時間に1回だけ送る（定期実行のたびに鳴らさない） - 健全に戻ったら通知を自分で消す - **webhook は使う前に生存確認する**。失効した webhook に投げ続けて「通知しているつもり」になっている事故は珍しくない --- ## 7. Windows で定期実行する場合の注意 - 登録スクリプト（.ps1）に日本語を書くなら **BOM 付き UTF-8 で保存**する。BOM 無しだと Windows PowerShell 5.1 が Shift-JIS と誤読し、コメント1行で構文エラーになる。本文を ASCII のみにするのが確実 - PC が停止していた時に追いかけ実行するオプションを付ける - 実行間隔は**後から変えられる形**にしておく（要望は必ず変わる。「15分ごと」「毎晩1回」「1時間ごと」と揺れた実例あり） --- ## 8. この構成でやらないこと - 音声の変換（多くの場合そもそも不要。まず実測で確かめる） - 音声をクラウドに保存すること（中継は都度読んで流すだけにする） - 取り込み先の資格情報を中継側に置くこと（暗号化して URL に載せる方が運用が楽） ---