manila/api-ref/source/snapshot-instances.inc
Goutham Pacha Ravi f185ff0f44 [api-ref] De-duplicate date and time parameters
Many APIs present information when the resource
in question was 'created_at' and 'updated_at'.

Having common parameters is easier to maintain in
the documentation since the description is the same
across the board.

Change-Id: Ia5d4ac399fe0d7983c61f5c5e0245d0987e97d6a
Partial-Bug: #1760644
2019-04-04 15:59:32 +00:00

210 lines
4.3 KiB
ReStructuredText

.. -*- rst -*-
==========================================
Share snapshot instances (since API v2.19)
==========================================
A share snapshot instance is an internal representation for a snapshot
of a share. A single snapshot can have multiple snapshot instances if
the parent share has multiple ``instances``. When a share is replicated
or is in the process of being migrated, it can live in multiple places
and each individual location is called an "instance", internally within
the Shared File Systems service.
By default administrators can list, show information for and explicitly
set the state of share snapshot instances. Use the ``policy.json`` file
to grant permissions for these actions to other roles.
List share snapshot instances
=============================
.. rest_method:: GET /v2/{project_id}/snapshot-instances
.. versionadded:: 2.19
Lists all share snapshot instances.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_instance_id_response
- snapshot_id: snapshot_id
- status: snapshot_instance_status
Response example
----------------
.. literalinclude:: samples/snapshot-instances-list-response.json
:language: javascript
List share snapshot instances with details
==========================================
.. rest_method:: GET /v2/{project_id}/snapshot-instances/detail
.. versionadded:: 2.19
Lists all share snapshot instances with details.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_instance_id_response
- snapshot_id: snapshot_id
- created_at: created_at
- updated_at: updated_at
- status: snapshot_instance_status
- share_id: share_id
- share_instance_id: share_instance_id_1
- progress: progress
- provider_location: snapshot_provider_location
Response example
----------------
.. literalinclude:: samples/snapshot-instances-list-with-detail-response.json
:language: javascript
Show share snapshot instance details
====================================
.. rest_method:: GET /v2/{project_id}/snapshot-instances/{snapshot_instance_id}
.. versionadded:: 2.19
Shows details for a share snapshot instance.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_instance_id: snapshot_instance_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_instance_id_response
- snapshot_id: snapshot_id
- created_at: created_at
- updated_at: updated_at
- status: snapshot_instance_status
- share_id: share_id
- share_instance_id: share_instance_id_1
- progress: progress
- provider_location: snapshot_provider_location
Response example
----------------
.. literalinclude:: samples/snapshot-instance-show-response.json
:language: javascript
Reset share snapshot instance state
===================================
.. rest_method:: POST /v2/{project_id}/snapshot-instances/{snapshot_instance_id}/action
.. versionadded:: 2.19
Administrator only. Explicitly updates the state of a share snapshot instance.
Use the ``policy.json`` file to grant permissions for this action
to other roles.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_instance_id: snapshot_instance_id_path
- status: snapshot_instance_status
Request example
---------------
.. literalinclude:: samples/snapshot-instance-actions-reset-state-request.json
:language: javascript