APIs in Category: dp-restore | API version 4.0

dp-restore-to-new-path dp-restore-to-primary | These operations are used by Freya to restore data from a backed-up dataset.

NetApp Manage ONTAP

dp-restore-to-new-path | [top]

> Start a restore operation on part of a dataset. This operation copies whole members or its sub-paths of the dataset from a specific backup version to a new location. The operation is performed in the background by a job. Error conditions: EOBJECTNOTFOUND - The dataset name or ID or one of the member name or ID was not found. EACCESSDENIED - The dataset exists, but the user invoking the API has no DFM.BackupManager.Restore permission on the dataset. EINTERNALERROR - An error occurred while processing the request. Try again later. EINVALIDINPUT - The number of paths to restore was either 0 or more than 1000 or neither backup-id nor backup-version was specified. EINVALIDHOST - One of the specified destination hosts was not a valid restore destination. EDATABASEERROR - A database error occured.

> Input Name | Range | Type | Description
> backup-id |  | integer optional | Identifier of the backup instance to restore from. If this parameter is specified, then backup-version is ignored. Range: [1..2^31-1]
> backup-version |  | dp-timestamp optional | Timestamp of the backup which should be restored from. If the backup-id is not specified, this parameter is required. A backup location that matches this version will be picked to do the restore from.
> check-overwrite |  | boolean optional | If true, checks if the member to be restored overwrites existing data on the destination. This flag cannot be used if the destination host is an OSSV or an ESX server. If it is used, an error is returned. It can be set to true only if the members to be restored are files. If the restore path has any members other than files, an error is returned. If false, goes ahead with the restore job without checking for overwrites at the destination. By default, it is false.
> check-space-status |  | boolean optional | If true, checks if there is enough space on the destination to restore the member. This flag cannot be used if the destination host is an OSSV or an ESX server. If it is used, an error is returned. It can be set to true only if the members to be restored are files. If the restore path has any members other than files, an error is returned. If the flag is not specified or set to false, goes ahead with the restore job without checking the space status at the destination. By default, it is false.
> dataset-name-or-id |  | obj-name-or-id | Name or identifier of the dataset to restore part of.
> members |  | dp-recover-member-info[] | List of members and their path to recover within the dataset. Each member includes the new location to restore the data. The maximum number of members is 1000.
> migrate-relationship |  | boolean validate optional | Flag indicating whether to migrate the relationships. By default, the value is false.
> Output Name | Range | Type | Description
> job-id |  | integer optional | Id of the job that handles the restore operation. It is returned only if "check-overwrite" and "check-space-status" are false. If either of them is set to true, the API only checks overwrites and/or space status and returns. The restore operation is not performed . Range: [1..2^31-1]
> overwrite-results |  | overwrite-result[] optional | Results of a check-overwrite. Each result will have information about the file that overwrites data on the destination. Returned if check-overwrite is true and if the file being restored might overwrite existing data. This element is not returned if there are no overwrites.
> space-status-results |  | space-status-result[] optional | Results of check-space-status. Each result will have information about the destination volume. Returned if check-space-status is true and if the destination volume does not have enough space for enough space for the restore. Returned if check-space-status is true and if the destination volume does not have enough space for the restore. If the destination volume has enough space, this element is not returned.

> Errno | Description
> EOBJECTNOTFOUND |  |
> EACCESSDENIED |  |
> EINTERNALERROR |  |
> EINVALIDINPUT |  |
> EINVALIDHOST |  |
> EDATABASEERROR |  |
> EBACKUPLOCATIONDOESNOTEXIST |  |
> EOPERATIONNOTSUPPORTED |  |

dp-restore-to-primary | [top]

> Start a restore operation on part of a dataset. This operation copies files and/or directories from a specific backup version back to the primary location. The operation is performed in the background by a job. Error conditions: EOBJECTNOTFOUND - The dataset name or ID or one of the member name or ID was not found. EACCESSDENIED - The dataset exists, but the user invoking the API has no DFM.BackupManager.Restore permission on the dataset or on any of the members. EINTERNALERROR - An error occurred while processing the request. Try again later. EINVALIDINPUT - The number of paths to restore was either 0 or more than 1000 or neither backup-id nor backup-version was specified. EDATABASEERROR - A database error occured. ENDRESTORENOTPOSSIBLE - A partial qtree restore is requested for a dataset which requires a non disruptive restore.

> Input Name | Range | Type | Description
> backup-id |  | integer optional validate | Identifier of the backup instance to restore from. If this parameter is specified, then backup-version is ignored. Range: [1..2^31-1]
> backup-version |  | dp-timestamp optional | Timestamp of the backup which should be restored from. If the backup-id is not specified, this parameter is required. A backup location that matches this version will be picked to do the restore from.
> check-overwrite |  | boolean optional | If true, checks if the member to be restored overwrites existing data on the destination. This flag cannot be used if the destination host is an OSSV or an ESX server. If it is used, an error is returned. It can be set to true only if the members to be restored are files. If the restore path has any members other than files, an error is returned. If false, goes ahead with the restore job without checking for overwrites at the destination. By default, it is false.
> check-space-status |  | boolean optional | If true, checks if there is enough space on the destination to restore the member. This flag cannot be used if the destination host is an OSSV or an ESX server. If it is used, an error is returned. It can be set to true only if the members to be restored are files. If the restore path has any members other than files, an error is returned. If the flag is not specified or set to false, goes ahead with the restore job without checking the space status at the destination. By default, it is false.
> dataset-name-or-id |  | obj-name-or-id | Name or ID of the dataset to restore part of.
> paths |  | dp-path-info[] | List of paths to restore within the dataset. Each path can be a single file or a directory. The maximum number of paths is 1000.
> Output Name | Range | Type | Description
> job-id |  | integer optional | Id of the job that handles the restore operation. It is returned only if "check-overwrite" and "check-space-status" are false. If either of them is set to true, the API only checks overwrites and/or space status and returns. The restore operation is not performed . Range: [1..2^31-1]
> overwrite-results |  | overwrite-result[] optional | Results of a check-overwrite. Each result will have information about the file that overwrites data on the destination. Returned if check-overwrite is true and if the file being restored might overwrite existing data. This element is not returned if there are no overwrites.
> space-status-results |  | space-status-result[] optional | Results of check-space-status. Each result will have information about the destination volume. Returned if check-space-status is true and if the destination volume does not have enough space for enough space for the restore. Returned if check-space-status is true and if the destination volume does not have enough space for the restore. If the destination volume has enough space, this element is not returned.

> Errno | Description
> EOBJECTNOTFOUND |  |
> EACCESSDENIED |  |
> EINTERNALERROR |  |
> EINVALIDINPUT |  |
> EDATABASEERROR |  |
> ENDRESTORENOTPOSSIBLE |  |
> EBACKUPLOCATIONDOESNOTEXIST |  |
> EOPERATIONNOTSUPPORTED |  |

Element definition: dp-path-info | [top]

> Information about a path inside a dataset.

> Name | Range | Type | Description
> member-name-or-id |  | obj-name-or-id | Name or id of the dataset component that is at the root of the file tree. This may be qtree, ossv directory or volume id that is source of the physical data protection relationship.
> path |  | string | Name of the path. The maximum path length is 32767 characters. This path is relative to "member-name-or-id" path in the storage system or OSSV host. Path cannot be empty.
> primary-snapshot-name |  | string optional | Name of the Snapshot copy on the primary where the data being restored originated. This is ignored if primary-snapshot-unique-id is specified.
> primary-snapshot-unique-id |  | string optional | Unique id of the Snapshot copy on the primary where the data being restored originated. Currently, this is the Snapshot copy's creation time. This is used to differentiate between multiple copies of the root object (specified by member-name-or-id input) in the same backup. If not specified and different versions of the root object exist in two Snapshot copies in the backup, then the restore might be ambiguous.
> restore-configuration |  | boolean optional | Valid only when an OSSV directory being restored is a Virtual Machine. If false the configuration of the Virtual Machine is not changed, only disks are restored. If true, the configuration and data are restored. Default value is true.

Element definition: dp-recover-member-info | [top]

> Information about a member inside a dataset.

> Name | Range | Type | Description
> destination-host |  | obj-name-or-id | Host to restore this dataset member to. The destination host must be compatible with the member type of the member being restored. For example, if the member is a volume, then this destination host must be a storage system.
> destination-path |  | string optional | Path to restore this dataset member to. The path will be interpreted relative to destination-host. If the destination host is a storage system, the path must not already exist. If the destination host is an OSSV, the path will be overwritten. In case of a Virtual Machine restore to the original location: The path must either be an empty string or not be specified. The restore will happen through the destination host. The format of this value depends on the host type of destination-host. If destination-host is a storage system, then it should be of the form "/vol1/[qtree1][/dir1..]". If a full volume restore is being specified, then the destination path must be a volume "/vol". If a full qtree restore is specified, and if the destination is a storage system, destination path can be either "/vol" or "/vol/qtree" and if it is "/vol", the server automatically appends the qtree name to the destination path to turn it into "/vol/qtree" format. If destination-host is an OSSV host, then it should be a pathname appropriate for the OSSV host. A Windows host will accept paths such as "C:\My Documents" and a UNIX host will accepts paths such as "/home/user". If the specified dataset-name-or-id is of an application data set, all the above rules apply. In addition, the files will be restored under a uniquely named directory under the destination path. The directory name is created by adding together three separate pieces of information (listed below) separated by a "_" character: Name of the primary Snapshot where data originated. All characters except [A-Z], [a-z], [0-9], '.', '-', '_', ')' and '(' are stripped from the Snapshot name and the name is trimmed to the first 42 characters before it is used. The 42 character limit ensures that the total length of the uniquely named directory does not exceed 64 characters. The DFM identifier of the primary qtree where the data originated. The DFM identifier of the Snapshot. This is currently the timestamp when the Snapshot was created. The maximum destination length is 32767 characters. In some cases, shorter destination lengths will fail due to limitations of underlying storage systems. Default value is an empty string.
> destination-path-skip-extra-directory |  | boolean optional | If this input is specified and is true, no extra directory will be added to the destination path. See destination-path for more information on how an extra directory is added to the destination path for an application dataset. If the dataset is not an applicatoin dataset, this input has no effect. Default is false.
> member-name-or-id |  | obj-name-or-id | Name or identifier of the dataset component that is at the root of the file tree. This may be qtree, ossv directory or volume id that is source of the physical data protection relationship.
> path |  | string | Name of the path. The maximum path length is 32767 characters. This path is relative to "member-name-or-id" path in the storage system or OSSV host. Path cannot be empty. "/" is considered as full member restore when the member is a volume, qtree or OSSV directory.
> primary-snapshot-name |  | string optional | Name of the Snapshot copy on the primary where the data being restored originated. This is ignored if primary-snapshot-unique-id is specified.
> primary-snapshot-unique-id |  | string optional | Unique id of the Snapshot copy on the primary where the data being restored originated. Currently, this is the Snapshot copy's creation time. This is used to differentiate between multiple copies of the root object (specified by member-name-or-id input) in the same backup. If not specified and different versions of the root object exist in two Snapshot copies in the backup, then the restore might be ambiguous.
> restore-configuration |  | boolean optional | Valid only when an OSSV directory being restored is a Virtual Machine. If false the configuration of the Virtual Machine is not changed, only disks are restored. If true, the configuration and data are restored. Default value is true.

Element definition: dp-timestamp | [top]

> Seconds since 1/1/1970 in UTC. Range: [0..2^31-1]. This runs out in 2036, so update the API some time before then.

> [none]

Element definition: obj-name-or-id | [top]

> Name or internal ID of a DFM object. This typedef is an alias for the builtin ZAPI type string. An obj-name-or-id must contain between 1 and 64 characters, and must conform to one of the following formats: It must have the format of an obj-name, or It must be the decimal numeric string form of a positive integer whose value is in the range [1..2^31 - 1]. Elements of type obj-name-or-id are used only as inputs to ZAPIs. The value must match either the name or internal ID of an existing DFM object. The ZAPI must specify the object's DFM object type (e.g. dataset, host, DP policy, etc.). Some ZAPIs allow the object to be one of several different types. If the format of an obj-name-or-id input element does not conform, or the value does not match the name or ID of an existing object, then generally the ZAPI documents that it fails with error code EOBJECTNOTFOUND. A ZAPI may return more specific error codes. In such cases, the ZAPI specification must document its behavior. If a ZAPI can accept a null value (e.g. reference to no object at all) for such an element, then the element is declared optional, and the absence of the input element represents a null value.

> [none]

Element definition: overwrite-result | [top]

> Information about the member and the destination.

> Name | Range | Type | Description
> dest-host |  | string | Destination host where file will be restored..
> file-path |  | string | destination path where the file was being restored. The path includes the name of the file being restored.
> overwrite-status |  | string | For ONTAP version below 7.3.0, we cannot check for overwrite. In that case, this element will return a predefined string indicating overwrite status could not be checked. For other cases, the overwrite status will be returned. Possible values : "overwrite", "overwrite_check_unsupported"

Element definition: space-status-result | [top]

> Information about the destination volume which does not have enough space for the restore

> Name | Range | Type | Description
> avail-space |  | integer | Free space available in the volume in KB. Range: [0..2^64-1]
> dest-host |  | string | Name of the destination host where the restore would take place.
> dest-vol |  | string | Name of the destination volume where the restore would take place.
> req-space |  | integer | Space required in the volume for restore in KB. Range: [0..2^64-1]