Aurweb RPC 接口

来自 ArchWiki

相关条目

Aurweb RPC 接口 是一个轻量级的 RPC 接口，用于 AUR。 查询以 HTTP GET 请求的形式发送，服务器以 JSON 响应。

注意： 本文描述的是 RPC 接口 API 的 v5 版本，该版本已于 2018 年 7 月 7 日随 AUR v4.7.0 更新。

API 使用方法

查询类型

有两种查询类型

  • 搜索
  • 信息

搜索

软件包搜索可以通过发出以下形式的请求来执行

/rpc/v5/search/keyword?by=field

其中 keyword 是搜索参数，field 是以下值之一

  • name (仅按软件包名称搜索)
  • name-desc (按软件包名称和描述搜索)
  • maintainer (按软件包维护者搜索)
  • depends (搜索依赖于关键字的软件包)
  • makedepends (搜索构建依赖于关键字的软件包)
  • optdepends (搜索可选依赖于关键字的软件包)
  • checkdepends (搜索检查依赖于关键字的软件包)

可以跳过 by 参数，默认为 name-desc。可能的返回类型为 search 和 error。

如果执行维护者搜索且搜索参数留空，则返回孤立软件包的列表。

示例

搜索 package

https://aur.archlinux.org/rpc/v5/search/package

搜索由 user 维护的软件包

https://aur.archlinux.org/rpc/v5/search/user?by=maintainer

搜索将 package 作为 makedepends 的软件包

https://aur.archlinux.org/rpc/v5/search/package?by=makedepends

使用回调搜索

https://aur.archlinux.org/rpc/v5/search/package?callback=jsonp1192244621103

信息

可以通过发出以下形式的请求来检索软件包信息

/rpc/v5/info?arg%5B%5D=pkg1&arg%5B%5D=pkg2&…

其中 pkg1、pkg2 等是要检索软件包详细信息的软件包名称的精确匹配项。

可能的返回类型为 multiinfo 和 error。

示例

单个软件包的信息

https://aur.archlinux.org/rpc/v5/info?arg[]=package

多个软件包的信息

https://aur.archlinux.org/rpc/v5/info?arg[]=pkg1&arg[]=pkg2

返回类型

返回的有效负载是一种格式，目前有三种主要类型。响应将始终返回一个类型，以便用户可以确定操作结果是否为错误。

返回有效负载的格式为

{"version":5,"type":ReturnType,"resultcount":0,"results":ReturnData}

ReturnType 是一个字符串，其值之一为

  • 搜索
  • multiinfo
  • error

return data

对于 search 和 multiinfo ReturnType，ReturnData 的类型是字典对象数组；对于 error ReturnType，则为空数组。

对于 ReturnType search，ReturnData 可能包含以下字段

  • ID
  • 名称
  • PackageBaseID
  • PackageBase
  • 版本
  • 描述
  • URL
  • NumVotes
  • 受欢迎度
  • 过期
  • 维护者
  • 首次提交
  • 上次修改
  • URLPath

对于 ReturnType info 和 multiinfo，ReturnData 可能还包含以下字段

  • Depends
  • MakeDepends
  • OptDepends
  • CheckDepends
  • Conflicts
  • Provides
  • Replaces
  • Groups
  • License
  • Keywords

软件包不包含的字段将从输出中省略。

error

错误类型有一个错误响应字符串作为返回值。错误响应可以从 search 或 info 查询类型返回。

ReturnType error 的示例

{"version":5,"type":"error","resultcount":0,"results":[],"error":"Incorrect by field specified."}

搜索

搜索类型是从搜索请求操作返回的结果。

ReturnType search 的示例

{"version":5,"type":"search","resultcount":2,"results":[{"ID":206807,"Name":"cower-git", ...}]}

信息

信息类型是从信息请求操作返回的结果。

ReturnType multiinfo 的示例

 {
    "version":5,
    "type":"multiinfo",
    "resultcount":1,
    "results":[{
        "ID":229417,
        "Name":"cower",
        "PackageBaseID":44921,
        "PackageBase":"cower",
        "Version":"14-2",
        "Description":"A simple AUR agent with a pretentious name",
        "URL":"http:\/\/github.com\/falconindy\/cower",
        "NumVotes":590,
        "Popularity":24.595536,
        "OutOfDate":null,
        "Maintainer":"falconindy",
        "FirstSubmitted":1293676237,
        "LastModified":1441804093,
        "URLPath":"\/cgit\/aur.git\/snapshot\/cower.tar.gz",
        "Depends":[
            "curl",
            "openssl",
            "pacman",
            "yajl"
        ],
        "MakeDepends":[
            "perl"
        ],
        "License":[
            "MIT"
        ],
        "Keywords":[]
    }]
 }

jsonp

如果您正在使用 javascript 页面，并且需要 JSON 回调机制，您可以这样做。您只需要提供一个额外的回调变量。此回调通常通过 javascript 库处理，但这是一个示例。

示例查询

https://aur.archlinux.org/rpc/v5/search/foobar?callback=jsonp1192244621103

示例结果

/**/jsonp1192244621103({"version":5,"type":"search","resultcount":1,"results":[{"ID":250608,"Name":"foobar2000","PackageBaseID":37068,"PackageBase":"foobar2000","Version":"1.3.9-1","Description":"An advanced freeware audio player (uses Wine).","URL":"http:\/\/www.foobar2000.org\/","NumVotes":39,"Popularity":0.425966,"OutOfDate":null,"Maintainer":"supermario","FirstSubmitted":1273255356,"LastModified":1448326415,"URLPath":"\/cgit\/aur.git\/snapshot\/foobar2000.tar.gz"}]})

这将自动调用 JavaScript 函数 jsonp1192244621103，并将参数设置为 RPC 调用的结果。

局限性

  • HTTP GET 请求限制为 URI 最大长度为 8190 字节。但是，在 nginx 服务器上使用 HTTP/2 运行的官方 AUR 实例使用 默认 URI 最大长度 限制为 4443 字节。参数超过约 200 个软件包的信息请求将需要拆分。
  • 搜索查询必须至少包含两个字符。
  • 如果搜索包含 5000 个或更多结果，则搜索将失败。
  • API 速率限制为每个 IP 每天最多 4000 个请求。
注意： 部分数据可在 AUR 元数据存档 中获得，用于批量处理。

参考客户端

有时，通过示例更容易理解。一些旧规范的参考实现（jQuery、python2、ruby）以及未指定“v”参数的实现可在此处 获取。

基于新路径的 /rpc v5 API 在 python 3.12 上的实现可在此处 获取。

参见

API 文档： https://aur.archlinux.org/rpc/swagger

Retrieved from "https://wiki.archlinux.org.cn/index.php?title=Aurweb_RPC_interface&oldid=791602"