跳到主要内容

PutRelativeFile

POST /wopi/files/(file_id)

基于当前文件在主机上创建一个新文件。

此操作的工作原理如下:

  1. WOPI 主机检查文件当前是否被锁定。

  2. 如果文件当前被锁定并且 X-WOPI-Lock 值与文件上当前的锁不匹配,则主机必须返回 409 Conflict ("lock mismatch") 并包含 X-WOPI-Lock 响应标头,标头中包含文件当前锁的值。在文件未被锁定的情况下,主机必须将 X-WOPI-Lock 设置为空字符串。

  3. 如果文件已解锁,主机会从 X-WOPI-SuggestedTarget 标头中获取文件名并修改它以使请求成功:

    • 如果标头仅包含文件扩展名(以句点开头),则生成的文件名将包含此扩展名和不带扩展名的初始文件名。
    • 如果标头包含完整的文件名,那么它将是结果文件的名称。
  4. 最后,主机创建一个具有合法名称且不覆盖任何现有文件的新文件,同时保留文件扩展名。

参数

名称类型描述
file_idstringfile ID 必须是 URL 安全的文件 ID。

查询参数

名称类型描述
access_tokenstring访问令牌主机将用它确定请求是否被授权。

请求标头

名称类型是否必填描述
X-WOPI-Overridestring必填来自 WOPI 服务器的请求操作 (PUT_RELATIVE)。
X-WOPI-SuggestedTargetstring必填文件扩展名或完整文件名,包括 UTF-7 编码字符串格式的文件扩展名。
X-WOPI-Sizeinteger非必填的文件的大小(以字节为单位)。
X-WOPI-FileConversionboolean非必填的表明请求是在二进制文档转换的上下文中进行的。

请求正文

请求正文必须包含二进制格式的完整文件内容。

响应标头

名称类型是否必填描述
X-WOPI-Lockstring非必填的锁ID——标识文件上的当前锁。当使用 409 Conflict 响应请求时,必须始终包含此标头。用 200 OK响应请求时不应包含它。
X-WOPI-LockFailureReasonstring非必填的锁定失败的原因。当使用 409 Conflict响应请求时,可能会包含此标头。它只能用于记录目的。

响应体

名称类型是否必填描述
Namestring必填文件名,包括扩展名,没有路径。
Urlstring必填URI,其形式为 http://server/<...>/wopi/files/(file_id)?access_token=(access token), 在主机上新创建的文件。
HostViewUrlstring非必填的主机页面的 URI,该页面为新创建文件加载查看 WOPI 操作。
HostEditUrlstring非必填的主机页面的 URI,该页面为新创建的文件加载编辑操作。

另存为

从 8.1 版开始,通过 PutRelativeFile 操作将 另存为 功能添加到 WOPI 协议中。在 ONLYOFFICE Docs API 中,此操作作为 onRequestSaveAs 事件实现。

执行 PutRelativeFile 操作保存当前文件的副本时,请求中不会发送 X-WOPI-FileConversion 标头。

要限制另存为功能,请将 CheckFileInfo 中的 UserCanNotWriteRelative 属性设置为 true