From f5436c7b632b27bd81ebc9ed4b0b676dae028804 Mon Sep 17 00:00:00 2001 From: Warren Date: Wed, 25 Mar 2026 15:27:47 +0800 Subject: [PATCH] docs: add training manual and workflow guide for marcom team --- docs/API_TRAINING_MARCOM.md | 258 +++++++++++++++++++++++++++++ docs/API_WORKFLOW_WORDPRESS_N8N.md | 201 ++++++++++++++++++++++ 2 files changed, 459 insertions(+) create mode 100644 docs/API_TRAINING_MARCOM.md create mode 100644 docs/API_WORKFLOW_WORDPRESS_N8N.md diff --git a/docs/API_TRAINING_MARCOM.md b/docs/API_TRAINING_MARCOM.md new file mode 100644 index 0000000..dc2e79f --- /dev/null +++ b/docs/API_TRAINING_MARCOM.md @@ -0,0 +1,258 @@ +# Momentry Core API 教育訓練手冊 + +> **對象**: marcom 團隊 +> **版本**: V1.0 | **日期**: 2026-03-25 + +--- + +## 1. 快速開始 + +### 基本資訊 + +| 項目 | 值 | +|------|-----| +| API 網址 | `https://api.momentry.ddns.net` | +| 認證方式 | Header `X-API-Key` | +| 格式 | JSON | + +### API Key + +``` +X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69 +``` + +--- + +## 2. 快速範例 + +### 查詢所有影片 + +```bash +curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ + "https://api.momentry.ddns.net/api/v1/videos" +``` + +### 查詢單一影片 + +```bash +curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ + "https://api.momentry.ddns.net/api/v1/videos/{uuid}" +``` + +### 查詢處理任務狀態 + +```bash +curl -s -H "X-API-Key: muser_68600856036340bcafc01930eb4bd839_1774418104_97221b69" \ + "https://api.momentry.ddns.net/api/v1/jobs/{uuid}" +``` + +--- + +## 3. API 端點說明 + +### 3.1 影片相關 + +#### GET /api/v1/videos +取得所有影片列表 + +**回應範例**: +```json +{ + "videos": [ + { + "uuid": "5dea6618a606e7c7", + "filename": "demo_video.mp4", + "duration": 123.45, + "status": "ready", + "created_at": "2026-03-25T10:00:00Z" + } + ] +} +``` + +#### GET /api/v1/videos/:uuid +取得單一影片詳情 + +#### GET /api/v1/videos/:uuid/chunks +取得影片的分段資訊 + +**回應範例**: +```json +{ + "chunks": [ + { + "chunk_id": "time_00001", + "start_time": 0.0, + "end_time": 10.0, + "type": "time_based" + } + ] +} +``` + +### 3.2 任務相關 + +#### GET /api/v1/jobs/:uuid +查詢處理任務狀態 + +**回應範例**: +```json +{ + "uuid": "9760d0820f0cf9a7", + "video_uuid": "5dea6618a606e7c7", + "status": "completed", + "progress": 100, + "created_at": "2026-03-25T10:00:00Z", + "completed_at": "2026-03-25T10:05:00Z" +} +``` + +#### GET /api/v1/jobs +查詢所有任務 + +**查詢參數**: +| 參數 | 說明 | 範例 | +|------|------|------| +| `status` | 篩選狀態 | `pending`, `processing`, `completed`, `failed` | +| `limit` | 回傳數量 | `10` | + +**範例**: +```bash +curl -s -H "X-API-Key: ..." \ + "https://api.momentry.ddns.net/api/v1/jobs?status=completed&limit=5" +``` + +### 3.3 健康檢查 + +#### GET /health +服務健康狀態（**無需認證**） + +**回應**: +```json +{ + "status": "ok", + "version": "0.9.20260325_144654" +} +``` + +--- + +## 4. n8n Workflow 範例 + +### 4.1 基本設定 + +在 n8n workflow 中使用 HTTP Request 節點： + +``` +┌─────────────────┐ +│ HTTP Request │ +├─────────────────┤ +│ Method: GET │ +│ URL: https://api.momentry.ddns.net/api/v1/videos +│ Headers: │ +│ X-API-Key: │ +│ [YOUR_KEY] │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ 處理回應資料 │ +└─────────────────┘ +``` + +### 4.2 範例：檢查任務狀態 + +```javascript +// n8n Function Node 範例 +const jobUuid = $input.item.json.uuid; + +return [{ + json: { + method: "GET", + url: `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`, + headers: { + "X-API-Key": "YOUR_API_KEY" + } + } +}]; +``` + +### 4.3 範例：擷取影片分段 + +```javascript +const videoUuid = $input.item.json.uuid; + +return [{ + json: { + method: "GET", + url: `https://api.momentry.ddns.net/api/v1/videos/${videoUuid}/chunks`, + headers: { + "X-API-Key": "YOUR_API_KEY" + } + } +}]; +``` + +--- + +## 5. 常見問題 + +### Q: 返回 401 錯誤怎麼辦？ +確認 Header 中有正確的 `X-API-Key` 值 + +### Q: 如何確認影片處理完成？ +``` +GET /api/v1/jobs/{uuid} +``` +檢查 `status` 是否為 `completed` + +### Q: 查不到資料？ +確認 UUID 格式正確（16碼 hex 字串） + +--- + +## 6. 快速參考卡 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Momentry API 速查 │ +├─────────────────────────────────────────────────────────────┤ +│ 查詢所有影片 GET /api/v1/videos │ +│ 查詢單一影片 GET /api/v1/videos/:uuid │ +│ 查詢影片分段 GET /api/v1/videos/:uuid/chunks │ +│ 查詢任務狀態 GET /api/v1/jobs/:uuid │ +│ 查詢所有任務 GET /api/v1/jobs │ +│ 健康檢查 GET /health (免認證) │ +├─────────────────────────────────────────────────────────────┤ +│ Header: X-API-Key: [YOUR_KEY] │ +│ URL: https://api.momentry.ddns.net │ +└─────────────────────────────────────────────────────────────┘ +``` + +--- + +## 附錄：回應狀態說明 + +### 任務狀態 (status) + +| 狀態 | 說明 | +|------|------| +| `pending` | 等待處理 | +| `processing` | 處理中 | +| `completed` | 已完成 | +| `failed` | 處理失敗 | + +### 影片狀態 (status) + +| 狀態 | 說明 | +|------|------| +| `uploading` | 上傳中 | +| `pending` | 等待處理 | +| `processing` | 處理中 | +| `ready` | 已就緒 | +| `error` | 錯誤 | + +--- + +**文件版本**: V1.0 +**最後更新**: 2026-03-25 diff --git a/docs/API_WORKFLOW_WORDPRESS_N8N.md b/docs/API_WORKFLOW_WORDPRESS_N8N.md new file mode 100644 index 0000000..d196dc1 --- /dev/null +++ b/docs/API_WORKFLOW_WORDPRESS_N8N.md @@ -0,0 +1,201 @@ +# Momentry API 使用流程 + +> **目標**: 從影片上傳到搜尋的完整流程 +> **適用**: WordPress / n8n 整合 + +--- + +## 流程總覽 + +``` +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ 1. 上傳 │ → │ 2. 註冊 │ → │ 3. 確認 │ → │ 4. 處理 │ → │ 5. 搜尋 │ +│ SFTPGo │ │ 自動完成 │ │ UUID │ │ 查詢進度 │ │ 測試 │ +└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ +``` + +--- + +## Step 1: 上傳影片 + +### 方式 A: SFTP 上傳（推薦） + +```bash +# 連線資訊 +主機: momentry.ddns.net +連接埠: 2022 +用戶名: demo +密碼: demopassword123 +``` + +使用 FileZilla 或 SFTP 客戶端上傳到 `/` 目錄 + +### 方式 B: SFTP 命令列 + +```bash +sshpass -p "demopassword123" sftp -P 2022 demo@momentry.ddns.net +``` + +上傳後確認檔案在 SFTPGo 中的位置 + +--- + +## Step 2: 自動註冊 + +上傳後，系統會自動： +1. 偵測新檔案 +2. 計算 UUID（SHA256） +3. 建立資料庫記錄 + +**無需手動操作** + +--- + +## Step 3: 確認註冊成功 + +### 查詢所有影片 + +```bash +curl -s -H "X-API-Key: YOUR_API_KEY" \ + "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos | length' +``` + +### 查詢特定檔案 + +```bash +curl -s -H "X-API-Key: YOUR_API_KEY" \ + "https://api.momentry.ddns.net/api/v1/videos" | jq '.videos[] | select(.file_name | contains("你的檔案名"))' +``` + +### 預期回應 + +```json +{ + "uuid": "952f5854b9febad1", + "file_path": "/Users/accusys/momentry/var/sftpgo/data/demo/你的檔案.mp4", + "file_name": "你的檔案.mp4", + "duration": 123.45, + "width": 1920, + "height": 1080 +} +``` + +**確認要點**: +- ✅ UUID 已產生（16位 hex） +- ✅ `file_path` 正確 +- ✅ `duration` > 0 + +--- + +## Step 4: 查詢處理進度 + +### 取得任務 UUID + +```bash +# 從影片資訊取得 job_id +curl -s -H "X-API-Key: YOUR_API_KEY" \ + "https://api.momentry.ddns.net/api/v1/videos" | \ + jq '.videos[] | select(.file_name == "你的檔案.mp4") | {uuid, job_id}' +``` + +### 查詢任務狀態 + +```bash +curl -s -H "X-API-Key: YOUR_API_KEY" \ + "https://api.momentry.ddns.net/api/v1/jobs/{uuid}" +``` + +### 任務狀態說明 + +| status | 說明 | 動作 | +|--------|------|------| +| `pending` | 等待處理 | 等待中 | +| `processing` | 處理中 | 繼續輪詢 | +| `completed` | 已完成 | 可進入 Step 5 | +| `failed` | 處理失敗 | 檢查錯誤 | + +### n8n 輪詢範例 + +```javascript +// n8n Workflow: 檢查處理狀態 +const jobUuid = $input.item.json.job_uuid; + +const response = await fetch( + `https://api.momentry.ddns.net/api/v1/jobs/${jobUuid}`, + { + headers: { + "X-API-Key": "YOUR_API_KEY" + } + } +); + +const job = await response.json(); + +// 狀態檢查 +if (job.status === 'completed') { + return [{ json: { done: true, video_uuid: job.video_uuid } }]; +} else { + return [{ json: { done: false, status: job.status } }]; +} +``` + +--- + +## Step 5: 搜尋測試 + +處理完成後，資料會入庫到向量資料庫，可進行搜尋測試。 + +### 測試向量搜尋 + +```bash +curl -s -X POST "https://api.momentry.ddns.net/api/v1/search" \ + -H "X-API-Key: YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "query": "測試關鍵字", + "top_k": 5 + }' +``` + +--- + +## 完整 n8n Workflow 範例 + +``` +┌──────────────┐ +│ 觸發 (定時) │ +└──────┬───────┘ + ▼ +┌──────────────┐ ┌──────────────┐ +│ 查詢影片 │────►│ 比對新檔案 │ +│ /videos │ │ │ +└──────┬───────┘ └──────────────┘ + │ │ + ▼ ▼ +┌──────────────┐ ┌──────────────┐ +│ 等待處理 │◄────│ 輪詢任務狀態 │ +│ /jobs/:uuid │ │ /jobs/:uuid │ +└──────┬───────┘ └──────────────┘ + │ + ▼ (completed) +┌──────────────┐ +│ 搜尋測試 │ +│ /search │ +└──────────────┘ +``` + +--- + +## 快速參考 + +| 步驟 | API | 用途 | +|------|-----|------| +| 查詢影片 | `GET /api/v1/videos` | 確認上傳成功 | +| 查詢任務 | `GET /api/v1/jobs/:uuid` | 查看處理進度 | +| 搜尋內容 | `POST /api/v1/search` | 測試搜尋功能 | + +--- + +**注意**: +- 處理時間視影片長度而定（1分鐘影片約需 2-5 分鐘處理） +- 大量影片時建議分批上傳