添加 lark_document_upload_images.md
This commit is contained in:
parent
3714abbe17
commit
1171b004da
114
lark_document_upload_images.md
Normal file
114
lark_document_upload_images.md
Normal file
@ -0,0 +1,114 @@
|
||||
# 飞书文档原生插入图片/视频 — 干货速查
|
||||
|
||||
> `TOKEN` 所有 API 通用,`DOC_ID` 为文档 ID。下面全部 curl 可直接复制执行。
|
||||
|
||||
## 0. 前置:获取 Token & 创建文档
|
||||
|
||||
```bash
|
||||
# Token (2h 有效)
|
||||
TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}' \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['tenant_access_token'])")
|
||||
|
||||
# 创建空白文档
|
||||
DOC_ID=$(curl -s -X POST "https://open.feishu.cn/open-apis/docx/v1/documents" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"title":"文档标题"}' \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['document']['document_id'])")
|
||||
```
|
||||
|
||||
## 1. 插入图片(block_type=27)
|
||||
|
||||
```bash
|
||||
# Step 1: 创建空占位块
|
||||
BLOCK_ID=$(curl -s -X POST \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"children":[{"block_type":27,"image":{}}],"index":-1}' \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['children'][0]['block_id'])")
|
||||
|
||||
# Step 2: 上传原图
|
||||
FILE_TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/medias/upload_all" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-F "file=@/path/to/image.png" -F "file_name=image.png" \
|
||||
-F "parent_type=docx_image" -F "parent_node=${BLOCK_ID}" \
|
||||
-F "size=$(stat -c%s /path/to/image.png)" \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['file_token'])")
|
||||
|
||||
# Step 3: 回填 token(不执行此步图片不显示!)
|
||||
curl -s -X PATCH \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${BLOCK_ID}?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d "{\"replace_image\":{\"token\":\"${FILE_TOKEN}\"}}" > /dev/null
|
||||
```
|
||||
|
||||
## 2. 插入视频(block_type=23,预览视图)
|
||||
|
||||
```bash
|
||||
# Step 1: 创建 File 占位块 (view_type=2=预览, view_type=1=文件卡片)
|
||||
VIEW_ID=$(curl -s -X POST \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"children":[{"block_type":23,"file":{"view_type":2}}],"index":-1}' \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['children'][0]['block_id'])")
|
||||
|
||||
# 取出内部真正的 File block ID(非 View block ID!)
|
||||
FILE_ID=$(curl -s \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${VIEW_ID}?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['block']['children'][0])")
|
||||
|
||||
# Step 2: 上传视频 (parent_node=FILE_ID,不是 VIEW_ID!)
|
||||
FILE_TOKEN=$(curl -s -X POST "https://open.feishu.cn/open-apis/drive/v1/medias/upload_all" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-F "file=@/path/to/video.mp4" -F "file_name=video.mp4" \
|
||||
-F "parent_type=docx_file" -F "parent_node=${FILE_ID}" \
|
||||
-F "size=$(stat -c%s /path/to/video.mp4)" \
|
||||
| python3 -c "import sys,json; print(json.load(sys.stdin)['data']['file_token'])")
|
||||
|
||||
# Step 3: 回填 token
|
||||
curl -s -X PATCH \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${FILE_ID}?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d "{\"replace_file\":{\"token\":\"${FILE_TOKEN}\"}}" > /dev/null
|
||||
```
|
||||
|
||||
## 3. 附加操作
|
||||
|
||||
```bash
|
||||
# 插入文本/标题块
|
||||
curl -s -X POST \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"children":[{"block_type":3,"heading1":{"elements":[{"text_run":{"content":"章节标题","text_element_style":{}}}],"style":{}}}],"index":-1}' > /dev/null
|
||||
# block_type: 2=正文, 3=Heading1, 4=Heading2, ...
|
||||
|
||||
# 批量删除子块 (左闭右开 [start, end))
|
||||
curl -s -X DELETE \
|
||||
"https://open.feishu.cn/open-apis/docx/v1/documents/${DOC_ID}/blocks/${DOC_ID}/children/batch_delete?document_revision_id=-1" \
|
||||
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
|
||||
-d '{"start_index":0,"end_index":3}' > /dev/null
|
||||
```
|
||||
|
||||
## 4. 图片 vs 视频 对照
|
||||
|
||||
| | 图片 | 视频 |
|
||||
|---|---|---|
|
||||
| block_type | 27 | 23 |
|
||||
| 占位块 JSON | `{"block_type":27,"image":{}}` | `{"block_type":23,"file":{"view_type":2}}` |
|
||||
| 实际产物 | Image block | View(33) 包裹 File(23) 复合块 |
|
||||
| upload `parent_type` | `docx_image` | `docx_file` |
|
||||
| upload `parent_node` | Image block ID | **File block ID**(非 View ID!) |
|
||||
| PATCH 字段 | `replace_image` | `replace_file` |
|
||||
| PATCH 目标 | Image block | **File block** |
|
||||
|
||||
## 5. 坑
|
||||
|
||||
| 症状 | 根因 | 解法 |
|
||||
|------|------|------|
|
||||
| 图片/视频上传后不显示 | token 不回填 | 必须 PATCH `replace_image`/`replace_file` |
|
||||
| 视频永久转圈 | `parent_node` 填了 View ID | 取 View.children[0] 得到 File ID |
|
||||
| 创建 file 块报 1770001 | 预设了 `name`/`token` | 只传 `{"view_type":2}`,name/token 后续回填 |
|
||||
| 视频只有文件卡片无播放器 | 未设 view_type=2 | 创建时 `"file":{"view_type":2}`,创建后**无法修改** |
|
||||
| 旧 import API 图片不渲染 | base64 data URI 不支持 | 用本文档原生流程 |
|
||||
Loading…
x
Reference in New Issue
Block a user