Skip to content

对接 Web Clipper #1266

Closed
Closed
@DiamondYuan

Description

@DiamondYuan

你在什么场景下需要该功能? In what scenarios do you need this function?

support web clipper.

描述最优的解决方案 Describe the optimal solution

提供一个本地的 http 服务,只需要 3 个接口

  1. 获取目录树
  2. 上传图片
  3. 新建文档

就可以适配 web clipper https://github.com/webclipper/web-clipper

其他信息 Other information

Activity

self-assigned this
on Jan 25, 2021
changed the title [-]http api[/-] [+]对接 Web Clipper[/+] on Jan 26, 2021
added this to the backlog milestone on May 28, 2021
modified the milestones: backlog, 1.2.2 on Jul 19, 2021
88250

88250 commented on Jul 19, 2021

@88250
Member

你好,我想象中整体流程大概是这样的,请看是否适合:

  1. Web Clipper HTML 转换 Markdown
  2. 列出笔记本,让用户选择存放到某个笔记本下
  3. 上传资源文件,思源会生成 ID 附加到文件名后面
  4. 创建文档,这一步需要修改之前的 Markdown 中的资源文件链接为上一步返回的路径

接口端点、参数和返回值

  • 端点:http://127.0.0.1:6806

  • 均是 POST 方法,目前不需要验证

  • 需要带参的接口,参数为 JSON 字符串,放置到 body 里,标头 Content-Type 为 application/json

  • 返回值

    {
      "code": 0,
      "msg": "",
      "data": {}
    }
    • code:非 0 为异常情况
    • msg:正常情况下是空字符串,异常情况下会返回错误文案
    • data:可能为 {}[] 或者 NULL,根据不同接口而不同

列出笔记本

  • /api/notebook/ls

  • 不带参

  • 返回值

    {
      "code": 0,
      "msg": "",
      "data": {
        "files": [
          "F:\\SiYuan\\data/思源笔记用户指南",
          "F:\\SiYuan\\data/测试笔记本"
        ]
      }
    }
    • files:笔记本路径,截取最后一个 / 后面的字符串即笔记本名称

上传资源文件

  • /api/asset/upload

  • 参数为 HTTP Multipart 表单

    • assetsDirPath:资源文件存放的文件夹路径,实参有以下三种情况

      1. "/assets/":工作空间 assets 文件夹
      2. "/测试笔记本/assets/":测试笔记本下的 assets 文件夹
      3. "/测试笔记本/foo/assets/":测试笔记本下 foo 文件夹下的 assets 文件夹

      建议用第三种,其中文件夹 foo 是创建文档时的文件夹,如果没有文件夹的话就是第二种情况。

    • file[]:上传的文件列表

  • 返回值

    {
      "code": 0,
      "msg": "",
      "data": {
        "errFiles": [""],
        "succMap": {
          "foo.png": "assets/foo-20210719092549-9j5y79r.png"
        }
      }
    }
    • errFiles:处理时遇到错误的文件名
    • succMap:处理成功的文件,key 为上传时的文件名,value 为 assets/foo-id.png,用于将已有 Markdown 内容中的资源文件链接地址替换为上传后的地址

通过 Markdown 创建文档

  • /api/filetree/createDocWithMd

  • 参数

    {
      "notebook": "测试笔记本",
      "path": "/foo/bar.sy",
      "markdown": ""
    }
    • notebook:笔记本名称
    • path:文档路径,需要以 / 开头并以 .sy 结尾,中间使用 / 分隔层级
    • markdown:GFM Markdown 内容
  • 返回值

    {
      "id": "文档 ID"
    }
DiamondYuan

DiamondYuan commented on Jul 22, 2021

@DiamondYuan
Author

image

DiamondYuan

DiamondYuan commented on Jul 22, 2021

@DiamondYuan
Author

image

DiamondYuan

DiamondYuan commented on Jul 22, 2021

@DiamondYuan
Author

我参数传错了?

88250

88250 commented on Jul 23, 2021

@88250
Member

image
表单中文件字段的 name 是 file[]

88250

88250 commented on Jul 27, 2021

@88250
88250

88250 commented on Jul 29, 2021

@88250
Member

@DiamondYuan API 鉴权 #2537

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Relationships

None yet

    Development

    No branches or pull requests

      Participants

      @88250@DiamondYuan

      Issue actions

        对接 Web Clipper · Issue #1266 · siyuan-note/siyuan