APIs in Category: dataprotection |
API version 6.1 |
dp-relationship-iter |
Data protection means backing up data and being able to recover it. Data is protected by making copies of it so that it is available for restoration even if the original data is no longer available. Data protection involves two key aspects: one is the ability to replicate the data, and the other is restoring it to the original location or new location for use as if it was the original. The ability to restore data that has been protected is core functionality of data protection solution. |
dp-relationship-iter | [top] |
Lists data protection relationships. For example, SnapVault or SnapMirror relationships. List relationships for a single storage service connection or for a particular source or destination name or id.
Input Name Range Type Description is-managed boolean
optional
If true, only list relationships which are managed by a storage-service. If false, only list relationships which are not in a storage service. If unspecified, list all relationships. max-records integer
optional
The maximum number of records per return batch the caller wants to receive. The server may return smaller batch sizes based on performance constraints. If this field is not provided, then the server will return default number of records based on server performance. relationship-resource-key resource-key
optional
Resource key of relationship. relationship-resource-key cannot be specified with any other inputs. relationship-states relationship-state[]
optional
If specified, only the relationships in any of these states are returned. If not present, do not filter by state. relationship-statuses relationship-status[]
optional
If specified, only the relationships in any of these statuses are returned. If not present, do not filter by status. relationship-type relationship-type
optional
If present, list only relationships of specified type. If not present, do not filter by type. source-or-destination-resource-key resource-key
optional
Resource key of either a source or a destination object. If empty, all relationships are listed. The source or destination object must be either a Volume or Vserver. If Vserver is specified, relationships for all volumes in that Vserver are listed. storage-service-connection-resource-key resource-key
optional
Resource key of the storage service connection. If present, only relationships on the specified connection will be listed. storage-service-connection-resource-key cannot be specified with storage-service-resource-key and is-managed inputs. storage-service-resource-key resource-key
optional
Resource key of storage service. Lists relationships managed by the storage service. storage-service-resource-key cannot be specified with is-managed, and storage-service-connection-resource-key input. tag string
optional
Specify the tag from the last call. It is not specified for the first call. For subsequent calls, copy values from the 'next-tag' obtained from the previous call. Any resource-filters specified in the first call must be included in subsequent calls. Output Name Range Type Description next-tag string
optional
Tag for the next call. Not present when there are no more objects to return. num-records integer
The number of records returned in this call. records dp-relationship-info[]
optional
The list of records.
Errno Description EINVALIDINPUT EOBJECTNOTFOUND
dp-restore-start | [top] |
Starts a restore/retrieval operation on part of a storage object. This API copies storage objects (files, LUNS, directories, qtrees, and volumes) from a given Snapshot copy to a specified location. Users can run one of the following APIs to obtain the source snapshot resource key.
- resource-lookup
- snapshot-get-location
This API returns the job-id of the job created for the restore operation. The job ID can be used to lookup detailed information on the progress of the restore operation.
Input Name Range Type Description restore-requests dp-restore-request-info[]
List of the objects to be restored. Output Name Range Type Description job-id job-id
The identification of the job created by this API request. The job is a manifest that expresses the set of different tasks and the sequence in which they are executed in order to accomplish a high level work-flow.
Errno Description EOBJECTNOTFOUND EINVALIDINPUT E_INPUT_NOT_IMPLEMENTED
Element definition: dp-relationship-info | [top] |
Information about relationship.
Name Range Type Description current-transfer-error string
optional
A message describing the last retryable error encountered by the current transfer. Applicable to Data ONTAP 8.2 and higher. destination-name obj-full-name
Full name of storage object where this relationship ends. destination-resource-key resource-key
Storage resource key of storage object where this relationship ends. is-healthy boolean
True if the most recent update succeeded and if it was a scheduled update occurred as scheduled. Otherwise false. lag-duration integer
optional
The amount of time in seconds by which the data on the mirror lags behind the source. Applicable to Data ONTAP 8.2 and higher. last-transfer-duration integer
optional
The amount of time in seconds it took for the last transfer to complete. Applicable to Data ONTAP 8.2 and higher. last-transfer-error string
optional
A message describing the cause of the last transfer failure. Present only if the last transfer was unsuccessful. Applicable to Data ONTAP 8.2 and higher. max-transfer-rate [0..2^31 - 1]. integer
Specifies the upper bound at which data is transferred between clusters, in kilobytes per second. 0 is unlimited which permits the relationship to fully utilize the available network bandwidth. The max-transfer-rate option does not affect relationships confined to a single cluster. relationship-name obj-name
Name of the relationship. relationship-progress [0..2^63 - 1]. integer
optional
The total number of bytes that have been processed so far for the current activity of the relationship as returned in the relationship-status. This is set only when the relationship-status indicates activity is in progress. relationship-resource-key resource-key
Resource key of the relationship. relationship-state relationship-state
State of the relationship. relationship-status relationship-status
Status of the relationship. relationship-type relationship-type
Type of the relationship. schedule-name obj-full-name
Full name of the schedule associated with this relationship. schedule-resource-key resource-key
Resource key of the schedule associated with this relationship. source-name obj-full-name
Full name of storage object where this relationship originates. source-resource-key resource-key
Resource key of storage object where this relationship originates. storage-service-connection-resource-key resource-key
optional
Resource key of the storage service connection. storage-service-destination-node-resource-key resource-key
optional
Resource key of the storage service node for the destination of this relationship. storage-service-name obj-name
optional
Name of the storage-service owning this relationship. Not present if this relationship is not owned by any storage service. storage-service-resource-key resource-key
optional
Resource key of the storage-service owning this relationship. Not present if this relationship is not owned by any storage-service. storage-service-source-node-resource-key resource-key
optional
Storage object resource key of the storage service node for the source of this relationship.
Element definition: dp-restore-request-info | [top] |
Restore request information pertaining to a single restore request.
Name Range Type Description destination-path string
optional
Path to the destination directory where the data is restored. Path is relative to the root of the destination volume and should not contain name of the file. If omitted, data is restored to the root of the volume. For in-place volume restore, a destination-path must not be specified. If both destination-path and use-snapshot-restore-volume inputs are specified and use-snapshot-restore-volume is set to true, then EINVALIDINPUT is returned. Leading '/' is optional in the destination-path. Examples of the destination-path are "dir1/dir2", "/dir1/dir2" or "/". If the destination-path is "/dir1/dir2", it is interpreted as "<destination-volume>/dir1/dir2". '/' must be used in place of '\' when restoring to or from a Windows path. destination-volume-resource-key resource-key
Resource key of the target volume to restore the data to. preserve-directory-hierarchy boolean
optional
Flag to preserve the directory hierarchy in the restore path. When true the directory hierarchy is recreated during restore. For example, if the path of the storage object 'c' to be restored is originally located on /a/b/c within the given Snapshot copy and the destination path to where it needs to be stored is /dest, then after restore, 'c' is stored at /dest/a/b/c. When false, 'c' is stored at /dest/c. Default is false. source-path string
optional
Path within the Snapshot copy of the storage object that is being restored. If use-snapshot-restore-volume flag is specified, then the source-path element must not be specified. Source path is relative to the Snapshot copy location and it can be a directory or a file. If a directory is specified, the files and subdirectories of that directory are restored. Leading '/' is optional in the source-path. Examples of the source-path are "dir1/dir2" or "/dir1/dir2" or "/dir1/dir2/file1". If the source-path is "/dir1/dir2", it is interpreted as "<source-volume>/.snapshot/<snapshot>/dir1/dir2". '/' must be used in place of '\' when restoring to or from a Windows path. source-snapshot-resource-key resource-key
Resource key of the snapshot copy. This is the immutable natural key to uniquely identify a snapshot on clustered Data ONTAP. use-snapshot-restore-volume boolean
optional
The flag to use the snapshot-restore-volume API. This flag is applicable only for in-place restoration of a volume from a local Snapshot copy. When true, this flag indicates that Data ONTAP's snapshot-restore-volume API is used for volume restoration. As a side-effect, any Snapshot copies created after this Snapshot copy creation no longer remain on the source volume after the restore. In effect, after the reversion, the volume is in the same state as it was when the Snapshot copy was created. If the volume is in a SnapMirror relationship, then only Snapshot copies that were created after the last SnapMirror update could be used. Otherwise, the job will fail indicating that the volume has a locked Snapshot copy. If this flag is set true, then both source-path and destination-path must not be specified. Otherwise, EINVALIDINPUT is returned.
WARNING: The storage system will reboot after the restore if the specified snapshot-identifier belongs to the root volume of a node Vserver. See Data ONTAP's guide for the "snapshot-restore-volume" API for more information.
When this flag is not specified or false, the snapshot-restore-volume API is not used. Default is false.
Element definition: job-id | [top] |
Opaque identifier for a job.
[none]
Element definition: relationship-state | [top] |
State of the relationship. Possible values are:
- uninitialized
- snapmirrored
- broken-off
[none]
Element definition: relationship-status | [top] |
Status of the relationship. Possible values are:
- idle
- transferring
- checking
- quiescing
- quiesced
- queued (Data ONTAP 8.2 and higher)
- preparing (Data ONTAP 8.2 and higher)
- waiting (Data ONTAP 8.2 and higher)
- finalizing (Data ONTAP 8.2 and higher)
- aborting (Data ONTAP 8.2 and higher)
[none]
Element definition: relationship-type | [top] |
Type of a relationship. Possible values are:
- data_protection (aka "mirror")
- load_sharing
- vault (Data ONTAP 8.2 and higher)
- restore (Data ONTAP 8.2 and higher)
- transition_data_protection (Data ONTAP 8.2 and higher)
[none]
Element definition: resource-key | [top] |
A self-describing string identifier for a managed resource.
[none]
Element definition: obj-full-name | [top] |
Full name of an object. This typedef is an alias for the builtin ZAPI type string. An object full name conforms to all the rules of an obj-name, except that the full name may be up to 255 characters long. Full names are created by concatenating an object name with any parent object names, so as to create a unique name for an object. The format of full names is as follows:
For any object not listed above, the obj-name and obj-full-name are identical.
- cluster full names are the either the fully-qualified domain name or the IP address of the cluster.
- cluster-node full names are the either the fully-qualified domain name or the IP address of the cluster.
- aggregate full names are the cluster-node name and the aggregate name, separated by a colon, e.g. cluster-node:aggr0.
- volume full names are the vserver name and the volume name, separated by ":/", e.g. vserver:/volume. Note this does not include the "/vol" prefix. Volume and aggregate full names are distinguished by the presence of a forward slash after the colon.
- qtree full names are the containing volume full name and the qtree name, separated by a slash, e.g. vserver:/volume/qtree. The data not contained by any qtree may be represented by "-", e.g. vserver:/volume/-.
- lun full names are either a volume or qtree full name and the LUN path, separated by a slash, e.g. vserver:/volume/LUN or vserver:/volume/qtree/LUN.
- initiator-group full names are vserver name and the initiator group name, separated by a colon, e.g. vserver:igroup.
- export-policy full names are vserver name and the policy name, separated by a colon, e.g. vserver:policy-name.
- lif full names are a cluster, cluster-node, or vserver name and the interface name, separated by a colon, e.g. cluster-name|cluster-node-name|vserver-name:lif.
- port-set full names are the vserver name and the portset name, separated by a colon, e.g. vserver:portset.
- fcp-target full names are the cluster-node name and the target name, separated by a colon, e.g. cluster-node:target.
[none]
Element definition: obj-name | [top] |
Name of an object. This typedef is an alias for the built in ZAPI type string. An object name must conform to the following format: The behavior of a ZAPI when it encounters an error involving an obj-name input element depends on how the ZAPI uses the input element. Here are the general rules:
- It must contain between 1 and 64 characters.
- It may start with any character and may contain any combination of characters, except that it may not consist solely of decimal digits ('0' through '9').
- In some contexts, a name may be the empty string (""), which is interpreted as a null value, e.g., a reference to no object at all.
A ZAPI may deviate from these general rules, for example, it may return more specific error codes. In such cases, the ZAPI specification must document its behavior.
- If the input name element is used to create a new object with the given name, or rename an existing object to that name, and the name does not conform to the above format, then the ZAPI fails with error code EINVALIDINPUT. Note that because EINVALIDINPUT is such a common error code, ZAPI specifications are not required to document cases when they may return it.
- If the input name element is used to refer to an existing object with that name, and there is no object with that name, then the ZAPI fails with error code EOBJECTNOTFOUND. Generally the ZAPI specification documents cases when it may return this error code.
If an input name element is used to refer to an existing object, then the ZAPI specification must specify which object type (e.g. cluster, vserver, volume etc.) is allowed. Some ZAPIs allow the object to be one of several different types. See the description of obj-full-name for examples of valid input formats.
Note that there is no requirement that all object names must be unique. However, the names for some specific types of objects are constrained such that no two objects of that type may have the same name.
[none]