/v1/files
本页说明 node 数据面的 /v1/files。参数名与限制由 Kibotos 实现它所用的常量生成，说明保持英文。
Reads and writes the content of one file in the guest. Directories and metadata go through FilesystemService, and paths follow its rules: absolute, or relative to the home directory of the identity user selects.
凭证
Authorization: Bearer <credential>, with the credential of a data-plane session that has the scope the method needs.
方法
| 方法 | 权限范围 | 说明 |
|---|---|---|
GET | DATA_PLANE_SCOPE_FILE_READ | Reads the file. A single Range: bytes=… range, including one that counts from the end such as bytes=-500, answers 206 with Content-Range; several ranges answer 400 and a range beyond the file answers 416. If-Range is forwarded to the guest unchanged. The response carries Content-Type, Content-Length, Content-Range, Accept-Ranges, ETag and Last-Modified; ETag is an opaque string. |
PUT | DATA_PLANE_SCOPE_FILE_WRITE | Writes the file from the request body. 200 means the file is on storage; the body reports what was written. A read-only directory answers 403 and an exhausted file system or quota answers 413, also for root; neither is retryable, and a file already at the path stays unchanged. |
查询参数
| 参数 | 方法 | 必填 | 说明 |
|---|---|---|---|
path | GET, PUT | 是 | The file: an absolute path in the guest, or a path relative to the home directory of user. |
user | GET, PUT | The guest identity the request runs as: empty for the account the Template declares, that account's name, or root. | |
mode | PUT | The permissions of a new file, in octal with permission bits only, such as 0644. Defaults to 0600. | |
create_only | PUT | true or 1 fails the request when the file exists; false, 0 or no value overwrites it. |
Any other parameter, a parameter given twice, an invalid value, and mode or create_only on GET answer 400 (invalid_argument) before the request reaches the guest.
消息体
PUT result
The body of a successful PUT. Compare the size and digest with what you sent.
| 字段 | 类型 | 说明 |
|---|---|---|
path | string | The cleaned absolute path written. |
size_bytes | number | The number of bytes written. |
sha256 | string | The SHA-256 digest of the bytes written, in lowercase hexadecimal. |
Error body
The body of every error response, with Content-Type: application/json.
| 字段 | 类型 | 说明 |
|---|---|---|
code | string | The name of the Connect error code, such as not_found. |
detail | object | The ErrorDetail of the error in protobuf JSON, with the field names of the proto file. |
状态码
| HTTP 状态码 | Connect 错误码 |
|---|---|
| 400 | invalid_argument |
| 401 | unauthenticated |
| 403 | permission_denied |
| 404 | not_found |
| 405 | unimplemented |
| 409 | already_exists, failed_precondition, aborted |
| 413 | resource_exhausted |
| 499 | canceled |
| 500 | unknown, out_of_range, internal, data_loss |
| 503 | unavailable |
| 504 | deadline_exceeded |
An unsatisfiable range answers 416 with Content-Range: bytes */<size>.
A request whose body stalls for longer than the progress timeout answers 408.
Methods other than GET and PUT answer 405.
限制
| 限制 | 值 | 说明 |
|---|---|---|
| Bytes per request | 1 GiB | The bytes of one GET response or PUT body. Read a larger file with several Range requests. |
| Rate | 64 MiB/s | The transfer rate of one request. |
| Burst | 1 MiB | The bytes one request may transfer above the rate at once. |
| Progress timeout | 5 s | How long the caller may send no request body, or read no response, before the node ends the request. Time the node spends waiting for the guest does not count. |