425 lines
8.7 KiB
ReStructuredText
425 lines
8.7 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
===============
|
|
Share snapshots
|
|
===============
|
|
|
|
Use the shared file service to make snapshots of shares. A share
|
|
snapshot is a point-in-time, read-only copy of the data that is
|
|
contained in a share. You can create, manage, update, and delete
|
|
share snapshots. After you create or manage a share snapshot, you
|
|
can create a share from it.
|
|
|
|
You can update a share snapshot to rename it, change its
|
|
description, or update its state to one of these supported states:
|
|
|
|
- ``available``
|
|
|
|
- ``error``
|
|
|
|
- ``creating``
|
|
|
|
- ``deleting``
|
|
|
|
- ``error_deleting``
|
|
|
|
- ``manage_starting``
|
|
|
|
- ``manage_error``
|
|
|
|
- ``unmanage_starting``
|
|
|
|
- ``unmanage_error``
|
|
|
|
As administrator, you can also reset the state of a snapshot and
|
|
force-delete a share snapshot in any state. Use the ``policy.json``
|
|
file to grant permissions for these actions to other roles.
|
|
|
|
|
|
List share snapshots
|
|
====================
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/snapshots
|
|
|
|
Lists all share snapshots.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_16
|
|
- name: name_15
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/snapshots-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
List share snapshots with details
|
|
=================================
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/snapshots/detail
|
|
|
|
Lists all share snapshots with details.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_16
|
|
- status: status_13
|
|
- share_id: share_id_5
|
|
- name: name_15
|
|
- description: description_11
|
|
- created_at: created_at_10
|
|
- share_proto: share_proto_2
|
|
- share_size: share_size
|
|
- size: size_3
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/snapshots-list-detailed-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show share snapshot details
|
|
===========================
|
|
|
|
.. rest_method:: GET /v2/{tenant_id}/snapshots/{snapshot_id}
|
|
|
|
Shows details for a share snapshot.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- snapshot_id: snapshot_id_1
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_16
|
|
- status: status_13
|
|
- share_id: share_id_5
|
|
- name: name_15
|
|
- description: description_11
|
|
- created_at: created_at_10
|
|
- share_proto: share_proto_2
|
|
- share_size: share_size
|
|
- size: size_3
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/snapshot-show-response.json
|
|
:language: javascript
|
|
|
|
|
|
Create share snapshot
|
|
=====================
|
|
|
|
.. rest_method:: POST /v2/{tenant_id}/snapshots
|
|
|
|
Creates a snapshot from a share.
|
|
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), unprocessableEntity(422)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- share_id: share_id_4
|
|
- force: force
|
|
- name: name_14
|
|
- display_name: display_name_1
|
|
- description: description_10
|
|
- display_description: display_description_1
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/snapshot-create-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_16
|
|
- share_id: share_id_5
|
|
- status: status_13
|
|
- name: name_15
|
|
- description: description_11
|
|
- created_at: created_at_10
|
|
- share_proto: share_proto
|
|
- share_size: share_size
|
|
- provider_location: provider_location_1
|
|
- size: size_3
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/snapshot-create-response.json
|
|
:language: javascript
|
|
|
|
|
|
Manage share snapshot
|
|
=====================
|
|
|
|
.. rest_method:: POST /v2/{tenant_id}/snapshots/manage
|
|
|
|
(Since API v2.12) Configures Shared File Systems to manage a share snapshot.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- share_id: share_id_6
|
|
- provider_location: provider_location
|
|
- name: name
|
|
- display_name: display_name_1
|
|
- description: description
|
|
- display_description: display_description_1
|
|
- driver_options: driver_options
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/snapshot-manage-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_16
|
|
- share_id: share_id_5
|
|
- status: status_14
|
|
- name: name_15
|
|
- description: description_11
|
|
- created_at: created_at_10
|
|
- share_proto: share_proto
|
|
- share_size: share_size
|
|
- provider_location: provider_location_1
|
|
- size: size_3
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/snapshot-manage-response.json
|
|
:language: javascript
|
|
|
|
|
|
Unmanage share snapshot
|
|
=======================
|
|
|
|
.. rest_method:: POST /v2/{tenant_id}/snapshots/{snapshot_id}/action
|
|
|
|
(Since API v2.12) Configures Shared File Systems to stop managing a share snapshot.
|
|
|
|
Normal response codes: 202
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), conflict(409)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- snapshot_id: snapshot_id_1
|
|
- unmanage: unmanage
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/snapshot-actions-unmanage-request.json
|
|
:language: javascript
|
|
|
|
|
|
Reset share snapshot state
|
|
==========================
|
|
|
|
.. rest_method:: POST /v2/{tenant_id}/snapshots/{snapshot_id}/action
|
|
|
|
Administrator only. Explicitly updates the state of a share snapshot.
|
|
|
|
Use the ``policy.json`` file to grant permissions for this action
|
|
to other roles.
|
|
|
|
Normal response codes: 202
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- snapshot_id: snapshot_id_1
|
|
- status: status_12
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/snapshot-actions-reset-state-request.json
|
|
:language: javascript
|
|
|
|
|
|
Force-delete share snapshot
|
|
===========================
|
|
|
|
.. rest_method:: POST /v2/{tenant_id}/snapshots/{snapshot_id}/action
|
|
|
|
Administrator only. Force-deletes a share snapshot in any state.
|
|
|
|
Use the ``policy.json`` file to grant permissions for this action
|
|
to other roles.
|
|
|
|
Normal response codes: 202
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- snapshot_id: snapshot_id_1
|
|
- force_delete: force_delete_4
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/snapshot-actions-force-delete-request.json
|
|
:language: javascript
|
|
|
|
|
|
Update share snapshot
|
|
=====================
|
|
|
|
.. rest_method:: PUT /v2/{tenant_id}/snapshots/{snapshot_id}
|
|
|
|
Updates a share snapshot.
|
|
|
|
You can update these attributes:
|
|
|
|
- ``display_name``, which also changes the ``name`` of the share
|
|
snapshot.
|
|
|
|
- ``display_description``, which also changes the ``description`` of
|
|
the share snapshot.
|
|
|
|
- ``is_public``. Changes the level of visibility.
|
|
|
|
If you try to update other attributes, they retain their previous
|
|
values.
|
|
|
|
Normal response codes: 200
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404), unprocessableEntity(422)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- snapshot_id: snapshot_id_1
|
|
- display_name: display_name_3
|
|
- display_description: display_description_2
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/snapshot-update-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: id_16
|
|
- status: status_13
|
|
- share_id: share_id_5
|
|
- name: name_15
|
|
- description: description_11
|
|
- created_at: created_at_10
|
|
- share_proto: share_proto_2
|
|
- share_size: share_size
|
|
- size: size_3
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/snapshot-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Delete share snapshot
|
|
=====================
|
|
|
|
.. rest_method:: DELETE /v2/{tenant_id}/snapshots/{snapshot_id}
|
|
|
|
Deletes a share snapshot.
|
|
|
|
Normal response codes: 202
|
|
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
|
|
itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- tenant_id: tenant_id_1
|
|
- snapshot_id: snapshot_id_1
|