deb-manila/api-ref/source/snapshots.inc
Daniel Gonzalez 3e86e3deac Migrate API reference into tree
The API Documentation team has requires [1] that
projects maintain their api-reference in-tree and
build it to the developer.openstack.org website.

This version of the API reference uses os-api-ref
and compiles API documentation close to that of
the OpenStack compute service (nova).

Co-Authored-By: Goutham Pacha Ravi <gouthamr@netapp.com>

[0] http://lists.openstack.org/pipermail/openstack-dev/2016-May/093765.html

Implements: bp move-manila-api-reference-in-tree
Change-Id: I67bb3354162d6e0e00fa2788edde864cc14920ee
2016-07-25 15:55:00 +00:00

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