Aurweb RPC 接口

相关文章

• 官方软件仓库 Web 界面

Aurweb RPC 接口是一个为 AUR 提供的轻量级 RPC 接口。查询通过 HTTP GET 请求发送，服务器以 JSON 格式响应。

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

API 使用

查询类型

共有两种查询类型

• search
• info

search

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

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

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

• name (仅通过软件包名称搜索)
• name-desc (通过软件包名称和描述搜索)
• maintainer (通过软件包维护者搜索)
• comaintainers (通过软件包共同维护者搜索)
• depends (搜索依赖于关键字的软件包)
• makedepends (搜索构建依赖于关键字的软件包)
• optdepends (搜索可选依赖于关键字的软件包)
• checkdepends (搜索检查依赖于关键字的软件包)
• provides (通过提供关键字的软件包搜索)
• conflicts (通过与关键字冲突的软件包搜索)
• replaces (通过替换关键字的软件包搜索)
• groups (通过软件包组搜索)
• submitter (通过软件包提交者搜索)

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

info

可以通过发送如下形式的请求来获取软件包信息

/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 是一个字符串，其值为以下之一

• search
• multiinfo
• error

返回数据

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

对于 ReturnType 为 search 的情况，ReturnData 可能包含以下字段

• ID
• 名称
• PackageBaseID
• PackageBase
• 版本
• 描述
• URL
• NumVotes
• Popularity
• OutOfDate
• 维护者
• FirstSubmitted
• LastModified
• URLPath

对于 ReturnType 为 info 和 multiinfo 的情况，ReturnData 可能额外包含以下字段

• 依赖
• MakeDepends
• OptDepends
• CheckDepends
• Conflicts
• Provides
• Replaces
• 用户组
• 许可证
• Keywords

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

error

错误类型将错误响应字符串作为返回值。search 或 info 查询类型都可能返回错误响应。

ReturnType 为 error 的示例

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

search

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

ReturnType 为 search 的示例

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

info

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

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 字节。然而，运行在支持 HTTP/2 的 nginx 服务器上的官方 AUR 实例使用的是 默认 URI 最大长度限制，即 4443 字节。参数超过约 200 个软件包的信息请求需要进行拆分。
• 搜索查询必须至少包含两个字符。
• 如果搜索结果达到 5000 条或更多，搜索将失败。
• API 速率限制为每个 IP 每天最多 4000 次请求。

注意 部分数据可在 AUR 元数据存档中获取，用于批量处理。

参考客户端

有时通过示例更容易理解。这里提供了一些针对旧规范且未指定 "v" 参数的参考实现（jQuery, python2, ruby）：点击此处。

基于路径的新版本 /rpc v5 API 在 python 3.12 上的实现可在此处找到：点击此处。

AUR 元数据存档

除了现有存档外，我们还引入了两个新存档，可用作 RPC 批量查询的替代方案。所有存档均可通过 https://aur.archlinux.org/archive-name.gz 下载。

使用这些存档将大幅减轻 API 客户端给 AUR 带来的流量压力，尤其是对于那些能够进行大规模自主查询的客户端。

所有存档均支持 Last-Modified 和 ETag。每个存档大约每 5 分钟更新一次。对于任何 RPC 的批量用户，我们请您考虑将这些存档作为重复搜索或批量 "multiinfo" 请求的解决方案。

现有存档

• 所有软件包列表（以换行符分隔）：https://aur.archlinux.org/packages.gz
• 所有软件包基础列表（以换行符分隔）：https://aur.archlinux.org/pkgbase.gz
• 所有用户列表（以换行符分隔）：https://aur.archlinux.org/users.gz

元数据存档

• 完整的 type=search 格式 JSON 软件包存档：https://aur.archlinux.org/packages-meta-v1.json.gz
• 完整的 type=multiinfo 格式 JSON 软件包存档：https://aur.archlinux.org/packages-meta-ext-v1.json.gz

参见

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