OIso 开放能力指北

0. 前言#

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

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

1. 搜索相关#

1.1 智能联想#

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

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

1
{
2
  "hits": {
3
    "hits": [
4
      {
5
        "_id": "\u6d1b\u8c37",
6
        "_score": 4.248307,
7
        "_source": {
8
          "name": "\u6d1b\u8c37"
9
        }
10
      },
11
      {
12
        "_id": "luogu",
13
        "_score": 4.248307,
14
        "_source": {
15
          "name": "luogu"
16
        }
17
      },
18
      ...
19
    ],
20
    "max_score": 4.248307,
21
  },
22
  "took": 2
23
}

响应说明：
- 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 ：更新时间最远的。
响应格式：生文本
响应示例：

1
{
2
    "took":5,
3
    "hits":{
4
        "total":{
5
            "value":5,
6
            "relation":"eq"
7
        },
8
        "max_score":19.994299,
9
        "hits":[
10
            {
11
                "_index":"articles",
12
                "_id":"https://www.luogu.com.cn/blog/765440/oiso-api",
13
                "_score":19.994299,
14
                "_source":{
15
                    "platform":"luogu",
16
                    "title":"OIso API\u6574\u7406 - HJR - \u202e\uff1f - \u6d1b\u8c37\u535a\u5ba2",
17
                    "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 ... ",
18
                    "url":"https://www.luogu.com.cn/blog/765440/oiso-api",
19
                    "time":1690486384.6621897
20
                }
21
            },
22
            ...
23
        ]
24
    }
25
}

响应说明：
- 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
响应示例：

1
{
2
  "hits": {
3
    "hits": [
4
      {
5
        "_id": "https://www.luogu.com.cn/discuss/390507",
6
        "_index": "lgbbs",
7
        "_score": null,
8
        "_source": {
9
          "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",
10
          "time": 1690388193.605151,
11
          "title": "P1059 \u6c42\u5e2e\u52a9",
12
          "url": "https://www.luogu.com.cn/discuss/390507"
13
        }
14
      }
15
    ]
16
  }
17
}

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

3. 登录相关#

3.1 获取验证码#

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

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

1
N0r5XpfMyR3bVxoQ5XiP

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

3.2 验证登录#

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

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

3.3 个人资料#

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

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

1
{
2
    "cookie": "H********Br**64***********C",
3
    "expires": 1693130810.3191907,
4
    "name": "diyanqi",
5
    "uid": 222419,
6
    "vip": {
7
        "expire": 1145144771010,
8
        "level": 3
9
    }
10
}

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