Aurweb RPC インターフェイス

提供: ArchWiki
2021年6月29日 (火) 16:17時点におけるKusanaginoturugi (トーク | 投稿記録)による版 (AurJson から記事を移動)
(差分) ← 古い版 | 最新版 (差分) | 新しい版 → (差分)
ナビゲーションに移動 検索に移動

esnAurweb RPC interface

関連記事

AurJson インターフェイスは AUR の軽量リモートインターフェイスです。http の GET クエリでリクエストすることで、json データとしてレスポンスを得ることができます。

ノート: この記事では2016年2月15日にリリースされた AUR v4.2.0 の RPC インターフェイス API バージョン5について説明しています。

API の使用方法

クエリタイプ

以下の2つのクエリタイプが存在します:

  • search
  • info

search

以下の形式のリクエストを実行することでパッケージを検索できます:

/rpc/?v=5&type=search&by=field&arg=keywords

keywords は検索単語に field は以下の値のどれかに置き換えてください:

  • name (パッケージ名だけで検索)
  • name-desc (パッケージ名と説明の両方で検索)
  • maintainer (パッケージメンテナで検索)

by パラメータは省略することができ、その場合は name-desc がデフォルトです。

返り値タイプは search または error になります。

検索単語を空にしてメンテナ検索した場合、メンテナが存在しないパッケージのリストが返ってきます。

例:

foobar で検索:

https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar

john によってメンテナンスされているパッケージを検索:

https://aur.archlinux.org/rpc/?v=5&type=search&by=maintainer&arg=john

コールバックを指定して検索:

https://aur.archlinux.org/rpc/?v=5&type=search&arg=foobar&callback=jsonp1192244621103

info

以下の形式のリクエストを実行することでパッケージの情報を取得できます:

/rpc/?v=5&type=info&arg[]=pkg1&arg[]=pkg2&…

pkg1pkg2 は情報を取得したいパッケージの名前に置き換えてください (完全一致です)。

返り値タイプは multiinfo または error になります。

例:

foobar パッケージの情報を取得:

https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foobar

foobarbar パッケージの情報を取得:

https://aur.archlinux.org/rpc/?v=5&type=info&arg[]=foo&arg[]=bar

返り値タイプ

返り値は3つあるタイプのどれかになります。かならずタイプを返すので、操作の結果がエラーだったかどうか判断することができます。

返り値のペイロードは以下の形式になっています:

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

ReturnType は文字列で、以下のうちのどれかになります:

  • search
  • multiinfo
  • error

ReturnTypesearchmultiinfo の場合は ReturnData はオブジェクト配列となり、ReturnTypeerror の場合は空の配列になります。

return data

The type of ReturnData is an array of dictionary objects for the search and multiinfo ReturnType, and an empty array for error ReturnType.

For the ReturnType search, ReturnData may contain the following fields:

  • ID
  • Name
  • PackageBaseID
  • PackageBase
  • Version
  • Description
  • URL
  • NumVotes
  • Popularity
  • OutOfDate
  • Maintainer
  • FirstSubmitted
  • LastModified
  • URLPath

For the ReturnType info and multiinfo, ReturnData may additionally contain the following fields:

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

Fields that a package does not contain will be omitted from the output.

error

error タイプはエラーのレスポンス文字列を返り値に含みます。エラーレスポンスは searchinfo クエリタイプで返ってくることがあります。

ReturnType error の例:

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

search

search タイプは search リクエストから返される結果です。検索の結果は、info リクエストと同じです。info セクションを見てください。

ReturnType search の例:

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

info

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 のコールバックメカニズムが必要な場合、callback 変数を追加で指定することで可能です。コールバックは基本的に JavaScript のライブラリで処理しますが、以下が例です。

クエリの例:

https://aur.archlinux.org/rpc/?v=5&type=search&arg=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"}]})

引数に RPC コールの結果が設定されて JavaScript 関数 jsonp1192244621103 が自動的に呼び出されます。

Limitations

  • HTTP GET requests are limited to URI of 8190 bytes maximum length. However, the official AUR instance running on a nginx server with HTTP/2 uses the default URI maximum length limit of 4443 bytes. Info requests with more than about 200 packages as an argument will need to be split.
  • Search queries must be at least two characters long.
  • Searches will fail if they contain 5000 or more results.
  • The API rate is limited to a maximum of 4000 requests per day per IP.

リファレンスクライアント

時と場合によっては例があったほうが物事を理解しやすいものです。リファレンス実装 (jQuery, python, ruby) が次の url にあります: https://github.com/cactus/random/tree/2b72a1723bfc8ae64eed6a3c40cb154accae3974/aurjson_examples

関連するコード

  • python3-aurAUR パッケージには AUR のリモート JSON インターフェイスなど AUR のサービスを使用するための Python 3 モジュールが入っています。詳しくは python3-aur を参照。
  • jshon はコマンドラインから JSON をパース・読み込み・作成します。詳しくは jshon を参照。