YandexDisk::Client
A client for the Yandex.Disk REST API.
Covers the whole documented surface: disk info, metadata and listings, directories, copy/move/delete, upload and download, publishing, custom properties, the Trash, and the background operations the API starts for anything it cannot finish inline.
client = YandexDisk::Client.new(ENV["YANDEX_DISK_TOKEN"])
client.mkdir_p("disk:/reports/2026")
client.upload("chart.png", "disk:/reports/2026/chart.png")
puts client.publish("disk:/reports/2026/chart.png").public_urlInstances are safe to share between fibers: every request checks a connection out of a pool for its duration.
Constants
The API caps a listing page at 1000 items; 200 keeps responses small enough to stay responsive on a slow link.
Constructors
Instance methods
Copies from to to.
Returns nil when the API finished inline, or an OperationHandle when
it moved the work to the background — which it does for non-empty
folders. Pass the handle to #wait to block until it settles.
Deletes a resource. Directories are removed recursively.
With permanently false the resource lands in the Trash, where
#trash_restore can still bring it back.
Downloads a published resource without saving it to the Disk first.
Downloads path to the local file destination, returning its size.
The file is reopened and truncated on every attempt, so a retry after a half-finished transfer starts clean rather than appending to a stump.
A flat list of every file on the Disk, newest path order, ignoring the directory tree. Useful for "find that file" without walking folders.
Metadata for a single resource, or nil when it does not exist.
The most recently uploaded files, newest first.
Every entry directly inside path, following pagination.
Returns an empty array when the directory does not exist, so callers writing into a fresh remote root do not have to special-case it. Pass fields to trim the response down to the keys you actually read.
Metadata for a single resource. Raises NotFoundError when absent.
For a directory the first page of its contents comes back in
Resource#items; use #list to page through all of it.
Creates a single directory. Returns false when it already existed.
Moves or renames from to to. See #copy for the return value.
Metadata for someone else's published resource.
public_key is either the key or the https://yadi.sk/... URL. For a
published folder, path addresses an entry inside it.
Publishes a resource and returns it with public_url filled in.
The publish call itself only answers with a metadata link, so this makes a second request to read back the key and URL that were just minted.
Everything the account currently has published.
Sends one PUT to a pre-authorised upload href.
The upload host is not the API host and takes no OAuth header. Retrying is left to the caller: the body has to be rewound between attempts, and only the caller knows how.
Issues an arbitrary API call with retries and error mapping applied.
Copies a published resource into the account's Downloads folder.
Attaches arbitrary key/value metadata to a resource.
Values merge with whatever is already there; pass nil to drop a key.
The API caps the whole object at 1 KB including keys and punctuation.
client.set_custom_properties("disk:/dump.sql", {
"source" => JSON::Any.new("db-01"),
"stale" => nil,
})Permanently removes one entry from the Trash.
Everything inside a Trash directory, following pagination.
Metadata for an entry in the Trash. Paths here live in the trash:/
namespace: a deleted disk:/a/b.txt becomes trash:/b.txt.
Restores a trashed resource to where it came from, recreating the original folder if it is gone. name renames it on the way back.
Revokes public access, deactivating any link already handed out.
Uploads a local file, chunking and retrying as needed.
This is the everyday entry point; construct an Uploader directly only
when you want to reuse one across many files with a fixed chunk size.
client.upload("dump.sql.gz", "disk:/backups/dump.sql.gz") do |sent, total|
print "\r#{sent * 100 // total}%"
endUploads a local file, chunking and retrying as needed.
This is the everyday entry point; construct an Uploader directly only
when you want to reuse one across many files with a fixed chunk size.
client.upload("dump.sql.gz", "disk:/backups/dump.sql.gz") do |sent, total|
print "\r#{sent * 100 // total}%"
endAsks Yandex to fetch url itself and store it at path.
Always asynchronous — the returned handle is the only way to learn whether the download succeeded.
Requests a pre-authorised upload URL, valid for 30 minutes.
Most callers want #upload, which handles chunking and retries; reach
for this only when driving the transfer yourself.
Polls handle until it settles, and returns the final state.
Raises OperationFailedError if the API reports failure and
OperationTimeoutError if it is still running when timeout elapses —
a still-running operation is not the same as a finished one, and
silently returning "in-progress" would invite exactly that confusion.