IRPCSharedLinks.CreateSharedLink

Vault API / standard write session or assertion returns metadata structure version

Creates a shared link to one file of an object and returns it with its new access key.

Service	Shared links `MFiles.IRPCSharedLinks`
gRPC method	`/MFiles.IRPCSharedLinks/CreateSharedLink`
HTTP (mf-http-grpc)	`POST /grpc/v1/create-shared-link`
Request	`CreateSharedLinkRequest`
Response	`CreateSharedLinkResponse`
Book and level	Vault API, standard
Kind	write
Session	Required: a session (mfiles-session-id-bin metadata) or a session assertion (x-mf-session-assertion metadata).
Idempotent	no
Returns metadata structure version	yes (in the mfiles-metadata-version-bin trailer)
Streaming	none (unary)

Remarks

Requires read access to the object version. Read-only, external and visitor links can be created by users whose license does not allow modifications; the other types need license_allows_modifications. When print prevention is enabled in the vault, the user also needs the right to download the file.
Leave access_key, created_at_utc and created_by_user unset (or set created_by_user to the caller's own ID); otherwise the call fails with "The parameter is incorrect.". file_ver must name one file; sharing all files of an object is not supported.
SHARED_LINK_TYPE_READ_ONLY: obj_ver must be a specific, checked-in version and file_ver.type must be FILE_VER_TYPE_ANY (other file version types fail with "The parameter is incorrect. (FileVersion)"). Links to the latest version fail with "Access denied." unless the vault allows them, and links to a checked-out version fail.
SHARED_LINK_TYPE_EXTERNAL and SHARED_LINK_TYPE_VISITOR: obj_ver and file_ver must refer to the latest version; a specific version fails with "Access denied.". Add visitors afterwards with AddSharedLinkRecipients.
The creation is recorded in the vault's event log.

Request: CreateSharedLinkRequest

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
`sl_info`	`SharedLinkInfo`	The link to create: `shared_link_type`, `obj_ver`, `file_ver`, and optionally `description`, `expires_at_utc` (unset for no expiration) and, for external links, `external_shared_link_access_type` and `is_anyone_access_granted`.
`sl_info.access_key`	`string`	The access key of the shared link.
`sl_info.description`	`string`	The description of the shared link.
`sl_info.created_at_utc`	`google.protobuf.Timestamp`	The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link.
`sl_info.expires_at_utc`	`google.protobuf.Timestamp`	The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time.
`sl_info.obj_ver`	`ObjVer`	The object version referenced by the shared link.
`sl_info.obj_ver.obj_id`	`ObjID`	The object.
`sl_info.obj_ver.version`	`ObjVerVersion`	The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`.
`sl_info.created_by_user`	`int32`	The creator of this shared Link.
`sl_info.file_ver`	`FileVer`	The file version referenced by the shared link.
`sl_info.file_ver.file_id`	`FileID`	The file.
`sl_info.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).
`sl_info.file_ver.internal_version`	`int32`	The file version number.
`sl_info.file_ver.external_repository_version`	`string`	Used only for files in external repositories. Leave empty.
`sl_info.file_ver.external_repository_sort_key`	`int64`	Used only for files in external repositories. Leave 0.
`sl_info.shared_link_type`	`SharedLinkType`	Type of the shared link.Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5).
`sl_info.is_anyone_access_granted`	`bool`	True if any user has granted public access to the document.
`sl_info.anyone_access_granted_by_user`	`int32`	The user who has granted public access to the document.
`sl_info.external_shared_link_access_type`	`ExternalSharedLinkAccessType`	Access type of the external shared link.Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3).
`sl_info.created_by_user_name`	`string`	The user who created the shared link.
`sl_info.anyone_access_granted_by_user_name`	`string`	The user who granted public access.

Response: CreateSharedLinkResponse

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
`sl_info_result`	`SharedLinkInfo`	The created link, including its `access_key`.
`sl_info_result.access_key`	`string`	The access key of the shared link.
`sl_info_result.description`	`string`	The description of the shared link.
`sl_info_result.created_at_utc`	`google.protobuf.Timestamp`	The creation time for the shared link. Is set by the server. Should be FILETIME_ZERO, when creating a new link.
`sl_info_result.expires_at_utc`	`google.protobuf.Timestamp`	The expiration time for the shared link. Use FILETIME_ZERO to indicate no expiration time.
`sl_info_result.obj_ver`	`ObjVer`	The object version referenced by the shared link.
`sl_info_result.obj_ver.obj_id`	`ObjID`	The object.
`sl_info_result.obj_ver.version`	`ObjVerVersion`	The version. Usually `OBJ_VER_VERSION_TYPE_SPECIFIC` with `internal_version`.
`sl_info_result.created_by_user`	`int32`	The creator of this shared Link.
`sl_info_result.file_ver`	`FileVer`	The file version referenced by the shared link.
`sl_info_result.file_ver.file_id`	`FileID`	The file.
`sl_info_result.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).
`sl_info_result.file_ver.internal_version`	`int32`	The file version number.
`sl_info_result.file_ver.external_repository_version`	`string`	Used only for files in external repositories. Leave empty.
`sl_info_result.file_ver.external_repository_sort_key`	`int64`	Used only for files in external repositories. Leave 0.
`sl_info_result.shared_link_type`	`SharedLinkType`	Type of the shared link.Values: `SHARED_LINK_TYPE_READ_ONLY` (0), `SHARED_LINK_TYPE_CO_AUTHORING` (1), `SHARED_LINK_TYPE_WOPIREADONLY` (2), `SHARED_LINK_TYPE_WOPIEDIT` (3), `SHARED_LINK_TYPE_VISITOR` (4), `SHARED_LINK_TYPE_EXTERNAL` (5).
`sl_info_result.is_anyone_access_granted`	`bool`	True if any user has granted public access to the document.
`sl_info_result.anyone_access_granted_by_user`	`int32`	The user who has granted public access to the document.
`sl_info_result.external_shared_link_access_type`	`ExternalSharedLinkAccessType`	Access type of the external shared link.Values: `EXTERNAL_SHARED_LINK_ACCESS_TYPE_UNINITIALIZED` (0), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_DOWNLOAD` (1), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_PREVIEW` (2), `EXTERNAL_SHARED_LINK_ACCESS_TYPE_EDIT` (3).
`sl_info_result.created_by_user_name`	`string`	The user who created the shared link.
`sl_info_result.anyone_access_granted_by_user_name`	`string`	The user who granted public access.

AddSharedLinkRecipients -- Adds visitors (email recipients) to an external or visitor link and returns all its recipients.

IRPCSharedLinks.CreateSharedLink

Remarks

Request: CreateSharedLinkRequest

Response: CreateSharedLinkResponse

Related methods