FileAPI
TopThe File API exposes basic file management functions.
DownloadFile()
Download from file resource.
GetFile()
Get file resource metadata.
GetFileContent()
Get the content of a file.
Note this rpc will fail if the size of the file content is greater than 64MB, in which case use DownloadFile instead.
GetFileDescendants()
Get the file resource metadata of all descendants of a given file resource.
SetFileContent()
Set the content of a file.
Note this rpc will fail if the size of the file content is greater than 64MB, in which case use UploadFile instead.
UploadFile()
Upload data to a file resource.
DownloadFileRequest
| Field | Type | Description |
| resource_id | string | The id of the resource to download. |
| file_path | string | This is required for linked folders, and represents the relative path to the source file from the base folder. |
DownloadFileResponse
The response stream will contain one or more of the following messages.
Each response message will contain one of the following fields.
| Field | Type | Description |
| block | bytes | A chunk of file data. |
| status | Status | A status will be sent when the file is completely downloaded, or if an error occurs. |
GetFileContentRequest
| Field | Type | Description |
| resource_id | string | The resource id of the base folder. |
| file_path | string | Optional - the path to the file, relative to the base folder. Required for linked folders. |
GetFileContentResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
| content | bytes | The file content. |
GetFileDescendantsRequest
| Field | Type | Description |
| resource_id | string | The resource id of the base folder. |
| file_path | string | For linked files, this is the relative path to the 'parent' file from the base folder. |
| extension | string | Optional - only match descendants of the given kind. |
| descendant_id | string | Optional - can be used to determine if a resource is a descendant. |
GetFileDescendantsResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
| descendant | File repeated | The list of descendants. |
GetFileRequest
| Field | Type | Description |
| resource_id | string | The resource id of the base folder. |
| file_path | string | Optional - the path to the file, relative to the base folder. Required for linked folders. |
GetFileResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
| file | File | The file metadata. |
SetFileContentRequest
| Field | Type | Description |
| resource_id | string | The resource id of the base folder. |
| file_path | string | Optional - the path to the file, relative to the base folder. Required for linked folders. |
| store_name | string | Optional store name to use. If specified, this will be used to extract the extension to set as a resource 'kind', e.g. tdx:ext:json. If not specified, the extension will be taken from the name of the target resource. |
| content | bytes |
SetFileContentResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
UploadFileRequest
One of the following fields must be present.
| Field | Type | Description |
| start | UploadFileStart | Describes the file upload, should only be sent as first message. |
| block | bytes | The next block of data. |
UploadFileResponse
| Field | Type | Description |
| status | Status | Details of any error that occurred on the call. |
| back_off | bool | Reserved for internal use. |
UploadFileStart
| Field | Type | Description |
| resource_id | string | The resource to upload to, required. |
| store_name | string | Optional store name to use. If specified, this will be used to extract the extension to set as a resource 'kind', e.g. tdx:ext:json. If not specified, the extension will be taken from the name of the target resource. |
| streaming_mode | bool | Optionally set streaming mode. When in streaming mode, data is written directly to the resource. Otherwise, data is written to a temporary file and then copied over once the upload completes successfully. |
| truncate | bool | Optional, truncates the file prior to beginning the upload. This is only really relevant if 'streaming_mode' is set. |
| eager_flush | bool | Optional, buffer will flush after each write. |
Status
| Field | Type | Description |
| code | int32 | A simple error code that can be easily handled by the client. Mirrors the grpc StatusCode enum, 0 => OK |
| message | string | A developer-facing human-readable error message in English. It should both explain the error and offer an actionable resolution to it. |
| description | string | Long form error description. |
File
| Field | Type | Description |
| file_path | string | |
| absolute_path | string | |
| file_name | string | |
| extension | string | |
| size | uint64 | |
| media_type | string | |
| is_directory | bool | |
| modified | uint64 | |
| resource_id | string | |
| owner_resource_id | string |
Scalar Value Types
| .proto Type | Notes | C++ | Java | Python | Go | C# | PHP | Ruby |
| double | double | double | float | float64 | double | float | Float | |
| float | float | float | float | float32 | float | float | Float | |
| int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| uint32 | Uses variable-length encoding. | uint32 | int | int/long | uint32 | uint | integer | Bignum or Fixnum (as required) |
| uint64 | Uses variable-length encoding. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum or Fixnum (as required) |
| sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int | uint32 | uint | integer | Bignum or Fixnum (as required) |
| fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long | uint64 | ulong | integer/string | Bignum |
| sfixed32 | Always four bytes. | int32 | int | int | int32 | int | integer | Bignum or Fixnum (as required) |
| sfixed64 | Always eight bytes. | int64 | long | int/long | int64 | long | integer/string | Bignum |
| bool | bool | boolean | boolean | bool | bool | boolean | TrueClass/FalseClass | |
| string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode | string | string | string | String (UTF-8) |
| bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str | []byte | ByteString | string | String (ASCII-8BIT) |