RenameFile¶
-
POST/wopi/files/(file_id)¶ The RenameFile operation renames a file.
If the host cannot rename the file because the name requested is invalid or conflicts with an existing file, the host should try to generate a different name based on the requested name that meets the file name requirements.
If the host cannot generate a different name, it should return an HTTP status code 400 Bad Request. The response must include an X-WOPI-InvalidFileNameError header that describes why the file name was invalid.
If the file is currently unlocked, the host should respond with a 200 OK and proceed with the rename.
If the file is currently locked and the X-WOPI-Lock value does not match the lock currently on the file the host must return a “lock mismatch” response (409 Conflict) and include an X-WOPI-Lock response header containing the value of the current lock on the file.
Office for the web Tip
Office for the web includes contains UI that users can use to rename files. In order to activate this UI in Office for the web, you must implement the RenameFile operation, and also do the following:
Set SupportsRename and UserCanRename to true in your CheckFileInfo response.
Set a FileNameMaxLength value if the default value is not correct for your WOPI host.
- Parameters
file_id (string) – A string that specifies a file ID of a file managed by host. This string must be URL safe.
- Query Parameters
access_token (string) – An access token that the host will use to determine whether the request is authorized.
- Request Headers
X-WOPI-Override – The string
RENAME_FILE. Required.X-WOPI-Lock – A string provided by the WOPI client that the host must use to identify the lock on the file.
X-WOPI-RequestedName – A UTF-7 encoded string that is a file name, not including the file extension.
- Response Headers
X-WOPI-InvalidFileNameError – A string describing the reason the rename operation could not be completed. This header should only be included when the response code is 400 Bad Request. This value must only be used for logging purposes.
X-WOPI-Lock – A string value identifying the current lock on the file. This header must always be included when responding to the request with 409 Conflict. It should not be included when responding to the request with 200 OK.
X-WOPI-LockFailureReason – An optional string value indicating the cause of a lock failure. This header may be included when responding to the request with 409 Conflict. There is no standard for how this string is formatted, and it must only be used for logging purposes.
X-WOPI-LockedByOtherInterface –
Deprecated since version 2015-12-15: This header is deprecated and should be ignored by WOPI clients.
- Status Codes
200 OK – Success
400 Bad Request – Specified name is illegal
401 Unauthorized – Invalid access token
404 Not Found – Resource not found/user unauthorized
409 Conflict – Lock mismatch/locked by another interface; an X-WOPI-Lock response header containing the value of the current lock on the file must always be included when using this response code
500 Internal Server Error – Server error
501 Not Implemented – Operation not supported
See also
- Standard WOPI request and response headers
In addition to the request/response headers listed here, this operation may also use the Standard WOPI request and response headers.
Response¶
The response to a RenameFile call is JSON (as specified in RFC 4627) containing a single required property:
- Name
The string name of the renamed file without a path or file extension.
Important
The Name property returned must not include the file extension. This is different than other similar WOPI operations such as PutRelativeFile and CreateChildFile.