docs: add training manual and workflow guide for marcom team
This commit is contained in:
Warren
258
docs/API_TRAINING_MARCOM.md
Normal file
258
docs/API_TRAINING_MARCOM.md
Normal file
@@ -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
|
||||
201
docs/API_WORKFLOW_WORDPRESS_N8N.md
Normal file
201
docs/API_WORKFLOW_WORDPRESS_N8N.md
Normal file
@@ -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 分鐘處理）
|
||||
- 大量影片時建議分批上傳
|
||||
Reference in New Issue
Block a user