跳到主要内容

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。