OIso 开放能力指北

0. 前言

OIso 是一个开放的平台。为了让有限的资源实现最大利用，我们决定将 OIso 的接口进行开放。以下接口均有一定的频率限制，请勿滥用接口。

文档中一切路径的 BaseURL 为 https://online.oiso.cf ，这是全球通用稳定接口。如果您寻求更快速的国内接口，请联系开发组洽谈。

1. 搜索相关

1.1 智能联想

智能联想是根据用户输入的词语或拼音，推断出用户想要搜索的内容。

• 路径： /suggestion?q=<text>
• 方法：POST / GET
• 字段：
  • text ：需要被联想的源文本
• 响应格式：JSON
• 响应示例：

  {
  "hits": {
    "hits": [
      {
        "_id": "\u6d1b\u8c37",
        "_score": 4.248307,
        "_source": {
          "name": "\u6d1b\u8c37"
        }
      },
      {
        "_id": "luogu",
        "_score": 4.248307,
        "_source": {
          "name": "luogu"
        }
      },
      ...
    ],
    "max_score": 4.248307,
  },
  "took": 2
  }
  

• 响应说明：
  • hits.hits ：包含 $10$ 条联想结果。
  • hits.hits[]._source.name ：联想结果的文本。
  • hits.hits[]._score ：该条目的匹配分数，越高越匹配。
  • took ：索引耗时（单位：毫秒）。

1.2 具体搜索

具体搜索支持搜索维基、题目、讨论、文章、页面等。

• 路径: /<type>?q=<text>&page=<page>&sort=<sort>
• 方法：POST / GET
• 字段：
  • type ：搜索类型，有以下几种可选值：
    • search ：综合搜索，包含了下面所有的类型；
    • wiki ：维基；
    • problem ：题目；
    • bbs ：讨论；
    • article ：文章；
    • pages ：页面。
  • text ：搜索的关键词。超过 $100$ 字会被自动截取。
  • page ：搜索的页码，默认一页 $20$ 条。默认为 $1$ 。
  • sort ：排序方式，默认为 matching_desc 。有以下几种取值：
    • matching_desc ：最匹配的；
    • time_desc ：更新时间最近的；
    • time_asc ：更新时间最远的。
• 响应格式：生文本
• 响应示例：

  {
    "took":5,
    "hits":{
        "total":{
            "value":5,
            "relation":"eq"
        },
        "max_score":19.994299,
        "hits":[
            {
                "_index":"articles",
                "_id":"https://www.luogu.com.cn/blog/765440/oiso-api",
                "_score":19.994299,
                "_source":{
                    "platform":"luogu",
                    "title":"OIso API\u6574\u7406 - HJR - \u202e\uff1f - \u6d1b\u8c37\u535a\u5ba2",
                    "content":"... OIso API\u6574\u7406 - HJR - \u202e\uff1f - \u6d1b\u8c37\u535a\u5ba2 \u63d0\u524d\u58f0\u660e\uff1a\u6211\u53ea\u662f\u642c\u8fd0\u5de5\uff0c\u522b\u95ee\u6211\uff0c\u6211\u7b54\u4e0d\u4e0a\u6765\u3002 ... \u53c2\u8003\uff1ahttps://github.com/oiso-developer-team/OIso-frontend/issues/5 ... ",
                    "url":"https://www.luogu.com.cn/blog/765440/oiso-api",
                    "time":1690486384.6621897
                }
            },
            ...
        ]
    }
  }
  

• 响应说明：
  • hits.total.value ：匹配的条目数，上限 $10000$ 。
  • hits.hits ：包含 $20$ 条结果（如果有那么多的话）。
  • hits.hits[]._source.content ：结果的文本。已赋予了一定的 HTML 格式。
  • hits.hits[]._source.title ：结果的标题。
  • hits.hits[]._source.url ：结果的链接地址。
  • hits.hits[]._source.time ：结果的最后更新时间戳。
  • hits.hits[]._score ：该条目的匹配分数，越高越匹配。
  • took ：索引耗时（单位：毫秒）。

2. 功能相关

2.1 手气不错

手气不错能随机返回索引库里的一项条目。

• 路径： /random
• 方法：POST / GET
• 响应格式：JSON
• 响应示例：

  {
  "hits": {
    "hits": [
      {
        "_id": "https://www.luogu.com.cn/discuss/390507",
        "_index": "lgbbs",
        "_score": null,
        "_source": {
          "content": "\n\n\n\n    P1059 \u6c42\u5e2e\u52a9\n\n\n\n    \n @\u6768\u5927\u4ed9\n2021-12-18 08:50\n\n\n\n\n\u6211\u592a\u96be\u4e86\n\n\n\n\n @LYqwq\n2021-12-18 08:57\n\n\n\n\n\n?\n\n\n",
          "time": 1690388193.605151,
          "title": "P1059 \u6c42\u5e2e\u52a9",
          "url": "https://www.luogu.com.cn/discuss/390507"
        }
      }
    ]
  }
  }
  

• 响应说明：
  • hits.hits ：包含 $1$ 条随机条目。
  • hits.hits[]._source.url ：该条目的链接。

3. 登录相关

3.1 获取验证码

能够获取一个验证码，用来复制到洛谷剪贴板里。

• 路径：/key_request
• 方法：POST / GET
• 响应格式：生文本
• 响应示例：

  N0r5XpfMyR3bVxoQ5XiP
  

• 响应说明：一个字符串，就是验证码了。

3.2 验证登录

用户创建完剪贴板后，将剪贴板网址提交给服务器进行验证。

• 路径：/key_check?url=<url>
• 参数说明：
  • url ：完整的洛谷剪贴板路径。
• 方法：POST / GET

3.3 个人资料

获取当前用户的详细信息。请求需携带 Cookies 。

• 路径： /profile
• 方法：POST / GET
• 响应格式：JSON
• 响应示例：

  {
    "cookie": "H********Br**64***********C",
    "expires": 1693130810.3191907,
    "name": "diyanqi",
    "uid": 222419,
    "vip": {
        "expire": 1145144771010,
        "level": 3
    }
  }
  

• 响应说明：
  • cookie ：用户令牌。
  • expires ：登录过期时间。
  • name ：用户名称。
  • uid ：用户在洛谷上的 uid 。
  • vip.level ：会员等级。
  • vip.expire ：会员到期时间。