IRPCThumbnails.GetDocumentFileThumbnail

Vault API / standard read session idempotent returns metadata structure version

Gets a classic thumbnail or a first-page preview of one file of an object version, as PNG.

Service	Thumbnails `MFiles.IRPCThumbnails`
gRPC method	`/MFiles.IRPCThumbnails/GetDocumentFileThumbnail`
HTTP (mf-http-grpc)	`POST /grpc/v1/get-document-file-thumbnail`
Request	`GetDocumentFileThumbnailRequest`
Response	`GetDocumentFileThumbnailResponse`
Book and level	Vault API, standard
Kind	read
Session	Required: the session ID from LogIn in the mfiles-session-id-bin metadata.
Idempotent	yes
Returns metadata structure version	yes (in the mfiles-metadata-version-bin trailer)
Streaming	none (unary)

Remarks

Requires a vault session.
Classic (THUMBNAIL_TYPE_CLASSIC or THUMBNAIL_TYPE_CLASSIC_NO_ICON; the server treats them the same): identify the file with a specific file version (FILE_VER_TYPE_SPECIFIC). The server generates the thumbnail on first request and caches it. Check thumbnail_status:
- THUMBNAIL_STATUS_GENERATED: thumbnail holds the PNG.
- THUMBNAIL_STATUS_CANNOT_GENERATE: the server has no thumbnail handler for the file type.
- THUMBNAIL_STATUS_FAILED_TO_GENERATE, THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE: generation failed, or the file's data is missing.
- THUMBNAIL_STATUS_DO_NOT_GENERATE: thumbnails are turned off, or the file type is excluded (see GetThumbnailOptions).
- THUMBNAIL_STATUS_NOT_GENERATED: no thumbnail yet.
In every case other than THUMBNAIL_STATUS_GENERATED, thumbnail is empty: show an icon or ask for a preview instead.
Preview (THUMBNAIL_TYPE_PREVIEW): obj_ver must name a specific version (OBJ_VER_VERSION_TYPE_SPECIFIC); a latest-version reference fails. The file must belong to that version. The server renders the first page and scales it to fit within max_width x max_height, keeping the aspect ratio; images are at most 999 pixels on the longer side. The response has thumbnail_type THUMBNAIL_TYPE_PREVIEW. If no preview can be made, the response holds the file type's icon instead, with thumbnail_type THUMBNAIL_TYPE_CLASSIC; thumbnail_status is THUMBNAIL_STATUS_GENERATED in both cases.
The first preview of a file can take a while, because the server first makes a PDF version of the file. Later calls reuse it.
Previews work only for files stored in the vault; for files of external repositories the call fails with "Not implemented.".

Request: GetDocumentFileThumbnailRequest

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

Field	Type	Description
`obj_ver`	`ObjVer`	The object version that has the file. For a preview, a specific version.
`obj_ver.obj_id`	`ObjID`	The object.
`obj_ver.obj_id.type`	`int32`	The object type ID, for example 0 for documents. In a lookup value, the value list ID (for a lookup to objects, the object type ID).
`obj_ver.obj_id.item_id`	`ItemID`	The ID of the object within its type, in `item_id.internal_id`.
`obj_ver.version`	`ObjVerVersion`	The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`.
`obj_ver.version.type`	`ObjVerVersionType`	What `internal_version` means. `OBJ_VER_VERSION_TYPE_SPECIFIC` for a version number.Values: `OBJ_VER_VERSION_TYPE_UNINITIALIZED` (0), `OBJ_VER_VERSION_TYPE_LATEST` (1), `OBJ_VER_VERSION_TYPE_ANY` (2), `OBJ_VER_VERSION_TYPE_ALL` (3), `OBJ_VER_VERSION_TYPE_SPECIFIC` (4), `OBJ_VER_VERSION_TYPE_VALUE_LIST_ITEM` (6), `OBJ_VER_VERSION_TYPE_OBJECT_LEVEL_REFERENCE` (7).
`obj_ver.version.internal_version`	`int32`	The version number, starting from 1, when `type` is `OBJ_VER_VERSION_TYPE_SPECIFIC`. The server returns -1 with `OBJ_VER_VERSION_TYPE_LATEST`.
`obj_ver.version.external_repository_version`	`string`	Used only for objects in external repositories. Leave empty.
`obj_ver.version.external_repository_sort_key`	`int64`	Used only for objects in external repositories. Leave 0.
`file_ver`	`FileVer`	The file and its specific version, as in the File entries of the object version.
`file_ver.file_id`	`FileID`	The file.
`file_ver.file_id.type`	`FileIDType`	`FILE_IDTYPE_SPECIFIC` for one file.Values: `FILE_IDTYPE_UNINITIALIZED` (0), `FILE_IDTYPE_ALL` (1), `FILE_IDTYPE_ANY` (2), `FILE_IDTYPE_SPECIFIC` (3).
`file_ver.file_id.internal_id`	`int32`	The file ID.
`file_ver.file_id.external_repository_id`	`string`	Used only for files in external repositories. Leave empty.
`file_ver.type`	`FileVerType`	`FILE_VER_TYPE_SPECIFIC` for a file version number.Values: `FILE_VER_TYPE_UNINITIALIZED` (0), `FILE_VER_TYPE_LATEST` (1), `FILE_VER_TYPE_ANY` (2), `FILE_VER_TYPE_SPECIFIC` (3).
`file_ver.internal_version`	`int32`	The file version number.
`file_ver.external_repository_version`	`string`	Used only for files in external repositories. Leave empty.
`file_ver.external_repository_sort_key`	`int64`	Used only for files in external repositories. Leave 0.
`type`	`ThumbnailType`	`THUMBNAIL_TYPE_CLASSIC` (default) for the cached square thumbnail, or `THUMBNAIL_TYPE_PREVIEW` for a first-page preview.Values: `THUMBNAIL_TYPE_CLASSIC` (0), `THUMBNAIL_TYPE_CLASSIC_NO_ICON` (1), `THUMBNAIL_TYPE_PREVIEW` (2).
`max_width`	`uint32`	For a preview, the largest width in pixels. Ignored for classic thumbnails.
`max_height`	`uint32`	For a preview, the largest height in pixels. Ignored for classic thumbnails. With both `max_width` and `max_height` 0, the server uses a default size.

Response: GetDocumentFileThumbnailResponse

Nested message fields are expanded to depth 3; follow a type link for deeper levels and for the type's own page.

Field	Type	Description
`thumbnail_status`	`ThumbnailStatus`	Whether a thumbnail was returned: `THUMBNAIL_STATUS_GENERATED` means `thumbnail` has data. See the remarks for the other values.Values: `THUMBNAIL_STATUS_NO_ACTIONS_ALLOWED` (0), `THUMBNAIL_STATUS_NOT_GENERATED` (1), `THUMBNAIL_STATUS_GENERATED` (2), `THUMBNAIL_STATUS_DO_NOT_GENERATE` (3), `THUMBNAIL_STATUS_CANNOT_GENERATE` (4), `THUMBNAIL_STATUS_FAILED_TO_GENERATE` (5), `THUMBNAIL_STATUS_FAILED_MISSING_DATA_FILE` (6).
`thumbnail_type`	`ThumbnailType`	The kind of image returned: `THUMBNAIL_TYPE_PREVIEW` for a page preview, `THUMBNAIL_TYPE_CLASSIC` for a classic thumbnail or a file type icon.Values: `THUMBNAIL_TYPE_CLASSIC` (0), `THUMBNAIL_TYPE_CLASSIC_NO_ICON` (1), `THUMBNAIL_TYPE_PREVIEW` (2).
`thumbnail`	`bytes`	The image as PNG bytes. Empty unless `thumbnail_status` is `THUMBNAIL_STATUS_GENERATED`.

GetThumbnailOptions -- Gets the vault's thumbnail settings.

IRPCThumbnails.GetDocumentFileThumbnail

Remarks

Request: GetDocumentFileThumbnailRequest

Response: GetDocumentFileThumbnailResponse

Related methods