Create a clone of the file
POST /storage/file/clone
Introduced In: 9.6
Creates a clone of the file.
Required Properties
-
source_path
-
destination_path
-
volume.uuid
- Instance UUID of the volume in which to create clone.
Optional Properties
-
range
- Required only in the case of a sub file clone. -
autodelete
- Marks a cloned file for auto deletion. -
is_backup
- Cloned file is used as a backup. -
volume.name
- Name of the volume in which to create the clone. -
token_uuid
- UUID of existing clone token.
Related Ontap commands
-
volume file clone create
Creating file clones
The POST operation is used to create file clones with the specified attributes in the body. Set the volume.uuid
to identify the volume.
Set source_path
and destination_path
to identify the file path of the original and copied file. For a full file clone, the new file is created using destination_path
.
For a sub file clone, set range
in the format source-file-block-number:destination-file-block-number:block-count. The API returns an error for the following overlapping conditions: (a) if the source and destination files are the same and if any of the source ranges overlap with any of the destination ranges. (b) if any of the source ranges overlap amongst themselves. (c) if any of the destination ranges overlap amongst themselves. If not provided, full file cloning is assumed.
If set to autodelete
, the cloned file is deleted when the volumes are full.<br>
# The API: curl -X POST "https://<mgmt_ip>/api/storage/file/clone" -H "accept: application/hal+json" -d '{"volume": {"name": "vol1", "uuid": "40e0fdc5-c28f-11eb-8270-005056bbeb0b"}, "source_path": "f1", "destination_path": "f2_c1"}' # The response: { "job": { "uuid": "0d025fd9-c4dc-11eb-adb5-005056bbeb0b", "_links": { "self": { "href": "/api/cluster/jobs/0d025fd9-c4dc-11eb-adb5-005056bbeb0b" } } } }
Learn More
-
[
DOC /storage/file/clone
]
Parameters
Name | Type | In | Required | Description |
---|---|---|---|---|
return_timeout |
integer |
query |
False |
The number of seconds to allow the call to execute before returning. When doing a POST, PATCH, or DELETE operation on a single record, the default is 0 seconds. This means that if an asynchronous operation is started, the server immediately returns HTTP code 202 (Accepted) along with a link to the job. If a non-zero value is specified for POST, PATCH, or DELETE operations, ONTAP waits that length of time to see if the job completes so it can return something other than 202.
|
return_records |
boolean |
query |
False |
The default is false. If set to true, the records are returned.
|
Request Body
Name | Type | Description |
---|---|---|
autodelete |
boolean |
Mark clone file for auto deletion. |
destination_path |
string |
Relative path of the clone/destination file in the volume. |
is_backup |
boolean |
Mark clone file for backup. |
overwrite_destination |
boolean |
Destination file gets overwritten. |
range |
array[string] |
List of block ranges for sub-file cloning in the format "source-file-block-number:destination-file-block-number:block-count" |
source_path |
string |
Relative path of the source file in the volume. |
token_uuid |
string |
UUID of existing clone token with reserved split load. |
volume |
Example request
Response
Status: 202, Accepted
Name | Type | Description |
---|---|---|
job |
Example response
Headers
Name | Description | Type |
---|---|---|
Location |
Useful for tracking the resource location |
string |
Response
Status: 201, Created
Error
Status: Default
ONTAP Error Response Codes
Error Code | Description |
---|---|
917864 |
Failed to get the file handle. |
917898 |
Invalid |
918236 |
The specified |
13565952 |
Clone start failed. |
13565988 |
The destination file cannot be marked as a backup clone as only a full-file clone can be a backup clone. |
Also see the table of common errors in the Response body overview section of this documentation.
Name | Type | Description |
---|---|---|
error |
Example error
Definitions
See Definitions
href
Name | Type | Description |
---|---|---|
href |
string |
_links
Name | Type | Description |
---|---|---|
self |
volume
Name | Type | Description |
---|---|---|
_links |
||
name |
string |
The name of the volume. This field cannot be specified in a PATCH method. |
uuid |
string |
Unique identifier for the volume. This corresponds to the instance-uuid that is exposed in the CLI and ONTAPI. It does not change due to a volume move.
|
file_clone
File clone
Name | Type | Description |
---|---|---|
autodelete |
boolean |
Mark clone file for auto deletion. |
destination_path |
string |
Relative path of the clone/destination file in the volume. |
is_backup |
boolean |
Mark clone file for backup. |
overwrite_destination |
boolean |
Destination file gets overwritten. |
range |
array[string] |
List of block ranges for sub-file cloning in the format "source-file-block-number:destination-file-block-number:block-count" |
source_path |
string |
Relative path of the source file in the volume. |
token_uuid |
string |
UUID of existing clone token with reserved split load. |
volume |
job_link
Name | Type | Description |
---|---|---|
_links |
||
uuid |
string |
The UUID of the asynchronous job that is triggered by a POST, PATCH, or DELETE operation. |
error_arguments
Name | Type | Description |
---|---|---|
code |
string |
Argument code |
message |
string |
Message argument |
returned_error
Name | Type | Description |
---|---|---|
arguments |
array[error_arguments] |
Message arguments |
code |
string |
Error code |
message |
string |
Error message |
target |
string |
The target parameter that caused the error. |