Aria2中文说明文档

术语

GID

The GID (or gid) is a key to manage each download. Each download will be assigned a unique GID. The GID is stored as 64-bit binary value in aria2. For RPC access, it is represented as a hex string of 16 characters (e.g., 2089b05ecca3d829). Normally, aria2 generates this GID for each download, but the user can specify GIDs manually using the --gid option. When querying downloads by GID, you can specify only the prefix of a GID as long as it is unique among others.

RPC授权密钥

As of 1.18.4, in addition to HTTP basic authorization, aria2 provides RPC method-level authorization. In a future release, HTTP basic authorization will be removed and RPC method-level authorization will become mandatory.

To use RPC method-level authorization, the user has to specify an RPC secret authorization token using the --rpc-secret option. For each RPC method call, the caller has to include the token prefixed with token:. Even when the --rpc-secret option is not used, if the first parameter in the RPC method is a string and starts with token:, it will removed from the parameter list before the request is being processed.

For example, if the RPC secret authorization token is $$secret$$, calling aria2.addUri RPC method would have to look like this:

aria2.addUri("token:$$secret$$", ["http://example.org/file"])
                    

The system.multicall RPC method is treated specially. Since the XML-RPC specification only allows a single array as a parameter for this method, we don't specify the token in the call. Instead, each nested method call has to provide the token as the first parameter as described above.

函数

All code examples are compatible with the Python 2.7 interpreter. For information on the secret parameter, see RPC authorization secret token.

aria2.addUri([secret, ]uris[, options[, position]])

This method adds a new download. uris is an array of HTTP/FTP/SFTP/BitTorrent URIs (strings) pointing to the same resource. If you mix URIs pointing to different resources, then the download may fail or be corrupted without aria2 complaining. When adding BitTorrent Magnet URIs, uris must have only one element and it should be BitTorrent Magnet URI. options is a struct and its members are pairs of option name and value. See Options below for more details. If position is given, it must be an integer starting from 0. The new download will be inserted at position in the waiting queue. If position is omitted or position is larger than the current size of the queue, the new download is appended to the end of the queue. This method returns the GID of the newly registered download.

JSON-RPC Example

The following example adds http://example.org/file:

>>> import urllib2, json
                    >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'qwer',
                    ...                       'method':'aria2.addUri',
                    ...                       'params':[['http://example.org/file']]})
                    >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
                    >>> c.read()
                    '{"id":"qwer","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
                    

XML-RPC Example

The following example adds http://example.org/file:

>>> import xmlrpclib
                    >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
                    >>> s.aria2.addUri(['http://example.org/file'])
                    '2089b05ecca3d829'
                    

The following example adds a new download with two sources and some options:

>>> s.aria2.addUri(['http://example.org/file', 'http://mirror/file'],
                                          dict(dir="/tmp"))
                      'd2703803b52216d1'
                      

The following example adds a download and inserts it to the front of the queue:

>>> s.aria2.addUri(['http://example.org/file'], {}, 0)
                    'ca3d829cee549a4d'
                    

[, uris[, options[, position]]])

This method adds a BitTorrent download by uploading a ".torrent" file. If you want to add a BitTorrent Magnet URI, use the aria2.addUri() method instead. torrent must be a base64-encoded string containing the contents of the ".torrent" file. uris is an array of URIs (string). uris is used for Web-seeding. For single file torrents, the URI can be a complete URI pointing to the resource; if URI ends with /, name in torrent file is added. For multi-file torrents, name and path in torrent are added to form a URI for each file. options is a struct and its members are pairs of option name and value. See Options below for more details. If position is given, it must be an integer starting from 0. The new download will be inserted at position in the waiting queue. If position is omitted or position is larger than the current size of the queue, the new download is appended to the end of the queue. This method returns the GID of the newly registered download. If --rpc-save-upload-metadata is true, the uploaded data is saved as a file named as the hex string of SHA-1 hash of data plus ".torrent" in the directory specified by --dir option. E.g. a file name might be 0a3893293e27ac0490424c06de4d09242215f0a6.torrent. If a file with the same name already exists, it is overwritten! If the file cannot be saved successfully or --rpc-save-upload-metadata is false, the downloads added by this method are not saved by --save-session.

The following examples add local file file.torrent.

JSON-RPC Example

>>> import urllib2, json, base64
                      >>> torrent = base64.b64encode(open('file.torrent').read())
                      >>> jsonreq = json.dumps({'jsonrpc':'2.0', 'id':'asdf',
                      ...                       'method':'aria2.addTorrent', 'params':[torrent]})
                      >>> c = urllib2.urlopen('http://localhost:6800/jsonrpc', jsonreq)
                      >>> c.read()
                      '{"id":"asdf","jsonrpc":"2.0","result":"2089b05ecca3d829"}'
                      

XML-RPC Example

>>> import xmlrpclib
                      >>> s = xmlrpclib.ServerProxy('http://localhost:6800/rpc')
                      >>> s.aria2.addTorrent(xmlrpclib.Binary(open('file.torrent', mode='rb').read()))
                      '2089b05ecca3d829'