Browse Source

Add API document for share group [3/3]

This patch adds a new API document for share group snapshot.

Partial-Bug: 1724716
Change-Id: I832d264eb220027aad32937dc64a6ca428ee55a4
zhongjun 1 year ago
parent
commit
cd77c128b0

+ 1
- 0
api-ref/source/index.rst View File

@@ -39,3 +39,4 @@ Shared File Systems API (EXPERIMENTAL)
39 39
 .. include:: share-replicas.inc
40 40
 .. include:: share-groups.inc
41 41
 .. include:: share-group-types.inc
42
+.. include:: share-group-snapshots.inc

+ 5
- 0
api-ref/source/samples/share-group-snapshot-actions-reset-state-request.json View File

@@ -0,0 +1,5 @@
1
+{
2
+    "reset_status": {
3
+        "status": "error"
4
+    }
5
+}

+ 7
- 0
api-ref/source/samples/share-group-snapshot-create-request.json View File

@@ -0,0 +1,7 @@
1
+{
2
+    "share_group_snapshot": {
3
+        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
4
+        "name": "test"
5
+        "description": "test description"
6
+    }
7
+}

+ 22
- 0
api-ref/source/samples/share-group-snapshot-create-response.json View File

@@ -0,0 +1,22 @@
1
+{
2
+    "share_group_snapshot": {
3
+        "status": "creating",
4
+        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
5
+        "links": [
6
+            {
7
+                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
8
+                "rel": "self"
9
+            },
10
+            {
11
+                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
12
+                "rel": "bookmark"
13
+            }
14
+        ],
15
+        "name": null,
16
+        "members": [],
17
+        "created_at": "2017-08-10T03:01:39.442509",
18
+        "project_id": "e23850eeb91d4fa3866af634223e454c",
19
+        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
20
+        "description": null
21
+    }
22
+}

+ 22
- 0
api-ref/source/samples/share-group-snapshot-show-response.json View File

@@ -0,0 +1,22 @@
1
+{
2
+    "share_group_snapshot": {
3
+        "status": "creating",
4
+        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
5
+        "links": [
6
+            {
7
+                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
8
+                "rel": "self"
9
+            },
10
+            {
11
+                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
12
+                "rel": "bookmark"
13
+            }
14
+        ],
15
+        "name": null,
16
+        "members": [],
17
+        "created_at": "2017-08-10T03:01:39.442509",
18
+        "project_id": "e23850eeb91d4fa3866af634223e454c",
19
+        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
20
+        "description": null
21
+    }
22
+}

+ 6
- 0
api-ref/source/samples/share-group-snapshot-update-request.json View File

@@ -0,0 +1,6 @@
1
+{
2
+    "share_group_snapshot": {
3
+        "name": "update name",
4
+        "description": "update description"
5
+    }
6
+}

+ 22
- 0
api-ref/source/samples/share-group-snapshot-update-response.json View File

@@ -0,0 +1,22 @@
1
+{
2
+    "share_group_snapshot": {
3
+        "status": "creating",
4
+        "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
5
+        "links": [
6
+            {
7
+                "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
8
+                "rel": "self"
9
+            },
10
+            {
11
+                "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
12
+                "rel": "bookmark"
13
+            }
14
+        ],
15
+        "name": null,
16
+        "members": [],
17
+        "created_at": "2017-08-10T03:01:39.442509",
18
+        "project_id": "e23850eeb91d4fa3866af634223e454c",
19
+        "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
20
+        "description": null
21
+    }
22
+}

+ 44
- 0
api-ref/source/samples/share-group-snapshots-list-detailed-response.json View File

@@ -0,0 +1,44 @@
1
+{
2
+    "share_group_snapshots": [
3
+        {
4
+            "status": "available",
5
+            "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
6
+            "links": [
7
+                {
8
+                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
9
+                    "rel": "self"
10
+                },
11
+                {
12
+                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
13
+                    "rel": "bookmark"
14
+                }
15
+            ],
16
+            "name": null,
17
+            "members": [],
18
+            "created_at": "2017-08-10T03:01:39.000000",
19
+            "project_id": "e23850eeb91d4fa3866af634223e454c",
20
+            "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
21
+            "description": null
22
+        },
23
+        {
24
+            "status": "available",
25
+            "share_group_id": "cd7a3d06-23b3-4d05-b4ca-7c9a20faa95f",
26
+            "links": [
27
+                {
28
+                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
29
+                    "rel": "self"
30
+                },
31
+                {
32
+                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/9d8ed9be-4454-4df0-b0ae-8360b623d93d",
33
+                    "rel": "bookmark"
34
+                }
35
+            ],
36
+            "name": null,
37
+            "members": [],
38
+            "created_at": "2017-08-10T03:01:28.000000",
39
+            "project_id": "e23850eeb91d4fa3866af634223e454c",
40
+            "id": "9d8ed9be-4454-4df0-b0ae-8360b623d93d",
41
+            "description": null
42
+        }
43
+    ]
44
+}

+ 22
- 0
api-ref/source/samples/share-group-snapshots-list-members-response.json View File

@@ -0,0 +1,22 @@
1
+{
2
+    "share_group_snapshot_members": [
3
+        {
4
+            "status": "available",
5
+            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
6
+            "created_at": "2017-09-07T11:50:39.000000",
7
+            "share_proto": "NFS",
8
+            "share_size": 1,
9
+            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
10
+            "size": 1
11
+        },
12
+        {
13
+            "status": "available",
14
+            "share_id": "406ea93b-32e9-4907-a117-148b3945749f",
15
+            "created_at": "2015-09-07T11:50:39.000000",
16
+            "share_proto": "NFS",
17
+            "share_size": 1,
18
+            "id": "6d221c1d-0200-461e-8d20-24b4776b9ddb",
19
+            "size": 1
20
+        }
21
+    ]
22
+}

+ 18
- 0
api-ref/source/samples/share-group-snapshots-list-response.json View File

@@ -0,0 +1,18 @@
1
+{
2
+    "share_group_snapshot": [
3
+        {
4
+            "links": [
5
+                {
6
+                    "href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
7
+                    "rel": "self"
8
+                },
9
+                {
10
+                    "href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_group_snapshot/46bf5875-58d6-4816-948f-8828423b0b9f",
11
+                    "rel": "bookmark"
12
+                }
13
+            ],
14
+            "name": null,
15
+            "id": "46bf5875-58d6-4816-948f-8828423b0b9f",
16
+        }
17
+    ]
18
+}

+ 343
- 0
api-ref/source/share-group-snapshots.inc View File

@@ -0,0 +1,343 @@
1
+.. -*- rst -*-
2
+
3
+=======================================
4
+Share group snapshots (since API v2.31)
5
+=======================================
6
+
7
+Use the shared file service to make snapshots of share groups. A share
8
+group snapshot is a point-in-time, read-only copy of the data that is
9
+contained in a share group. You can create, update, and delete
10
+share group snapshots. After you create a share group snapshot, you
11
+can create a share group from it.
12
+
13
+You can update a share group snapshot to rename it, change its
14
+description, or update its state.
15
+
16
+As administrator, you can also reset the state of a group snapshot. Use
17
+the ``policy.json`` file to grant permissions for these actions to other
18
+roles.
19
+
20
+.. note::
21
+
22
+    Share Group Snapshot APIs are part of the `experimental APIs
23
+    <http://developer.openstack.org/api-ref/shared-file-systems/#experimental-apis>`_.
24
+
25
+List share group snapshots
26
+==========================
27
+
28
+.. rest_method::  GET /v2/{tenant_id}/share-group-snapshots
29
+
30
+Lists all share group snapshots.
31
+
32
+Normal response codes: 200
33
+Error response codes: badRequest(400), unauthorized(401)
34
+
35
+Request
36
+-------
37
+
38
+.. rest_parameters:: parameters.yaml
39
+
40
+   - tenant_id: tenant_id_path
41
+   - project_id: project_id
42
+   - all_tenants: all_tenants
43
+   - name: group_snapshot_name_query
44
+   - description: group_snapshot_description_query
45
+   - status: group_snapshot_status_query
46
+   - share_group_id: share_group_id_query
47
+   - limit: limit_query
48
+   - offset: offset
49
+   - sort_key: sort_key
50
+   - sort_dir: sort_dir
51
+
52
+Response parameters
53
+-------------------
54
+
55
+.. rest_parameters:: parameters.yaml
56
+
57
+   - id: group_snapshot_id
58
+   - name: snapshot_name
59
+   - links: group_snapshot_links
60
+
61
+Response example
62
+----------------
63
+
64
+.. literalinclude:: samples/share-group-snapshots-list-response.json
65
+   :language: javascript
66
+
67
+
68
+List share group snapshots with details
69
+=======================================
70
+
71
+.. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/detail
72
+
73
+Lists all share group snapshots with details.
74
+
75
+Normal response codes: 200
76
+Error response codes: badRequest(400), unauthorized(401)
77
+
78
+Request
79
+-------
80
+
81
+.. rest_parameters:: parameters.yaml
82
+
83
+   - tenant_id: tenant_id_path
84
+   - project_id: project_id
85
+   - all_tenants: all_tenants
86
+   - name: group_snapshot_name_query
87
+   - description: group_snapshot_description_query
88
+   - status: group_snapshot_status_query
89
+   - share_group_id: share_group_id_query
90
+   - limit: limit_query
91
+   - offset: offset
92
+   - sort_key: sort_key
93
+   - sort_dir: sort_dir
94
+
95
+Response parameters
96
+-------------------
97
+
98
+.. rest_parameters:: parameters.yaml
99
+
100
+   - id: group_snapshot_id
101
+   - project_id: project_id
102
+   - status: group_snapshot_status_required
103
+   - share_group_id: share_group_id
104
+   - name: group_snapshot_name
105
+   - description: group_snapshot_description
106
+   - created_at: group_snapshot_created_at
107
+   - members: group_snapshot_members
108
+   - links: group_snapshot_links
109
+
110
+Response example
111
+----------------
112
+
113
+.. literalinclude:: samples/share-group-snapshots-list-detailed-response.json
114
+   :language: javascript
115
+
116
+
117
+List share group snapshots members
118
+==================================
119
+
120
+.. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/members
121
+
122
+Lists all share group snapshots members.
123
+
124
+Normal response codes: 200
125
+Error response codes: badRequest(400), unauthorized(401)
126
+
127
+Request
128
+-------
129
+
130
+.. rest_parameters:: parameters.yaml
131
+
132
+   - tenant_id: tenant_id_path
133
+   - group_snapshot_id: group_snapshot_id_path
134
+
135
+Response parameters
136
+-------------------
137
+
138
+.. rest_parameters:: parameters.yaml
139
+
140
+   - id: group_snapshot_id
141
+   - created_at: snapshot_created_at
142
+   - project_id: project_id
143
+   - size: snapshot_size
144
+   - share_protocol: snapshot_share_protocol
145
+   - name: snapshot_name
146
+   - share_group_snapshot_id: group_snapshot_id
147
+   - share_id: snapshot_share_id
148
+
149
+
150
+Response example
151
+----------------
152
+
153
+.. literalinclude:: samples/share-group-snapshots-list-members-response.json
154
+   :language: javascript
155
+
156
+
157
+Show share group snapshot details
158
+=================================
159
+
160
+.. rest_method::  GET /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
161
+
162
+Shows details for a share group snapshot.
163
+
164
+Normal response codes: 200
165
+Error response codes: badRequest(400), unauthorized(401), itemNotFound(404)
166
+
167
+Request
168
+-------
169
+
170
+.. rest_parameters:: parameters.yaml
171
+
172
+   - tenant_id: tenant_id_path
173
+   - group_snapshot_id: group_snapshot_id_path
174
+
175
+Response parameters
176
+-------------------
177
+
178
+.. rest_parameters:: parameters.yaml
179
+
180
+   - id: group_snapshot_id
181
+   - project_id: project_id
182
+   - status: group_snapshot_status_required
183
+   - share_group_id: share_group_id
184
+   - name: group_snapshot_name
185
+   - description: group_snapshot_description
186
+   - created_at: group_snapshot_created_at
187
+   - members: group_snapshot_members
188
+   - links: group_snapshot_links
189
+
190
+Response example
191
+----------------
192
+
193
+.. literalinclude:: samples/share-group-snapshot-show-response.json
194
+   :language: javascript
195
+
196
+
197
+Create share group snapshot
198
+===========================
199
+
200
+.. rest_method::  POST /v2/{tenant_id}/share-group-snapshots
201
+
202
+Creates a snapshot from a share.
203
+
204
+
205
+Normal response codes: 200
206
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
207
+itemNotFound(404), unprocessableEntity(422)
208
+
209
+Request
210
+-------
211
+
212
+.. rest_parameters:: parameters.yaml
213
+
214
+   - tenant_id: tenant_id_path
215
+   - name: group_snapshot_name_option
216
+   - description: group_snapshot_description_option
217
+   - share_group_id: share_group_id
218
+
219
+Request example
220
+---------------
221
+
222
+.. literalinclude:: samples/share-group-snapshot-create-request.json
223
+   :language: javascript
224
+
225
+Response parameters
226
+-------------------
227
+
228
+.. rest_parameters:: parameters.yaml
229
+
230
+   - id: group_snapshot_id
231
+   - project_id: project_id
232
+   - status: group_snapshot_status_required
233
+   - share_group_id: share_group_id
234
+   - name: group_snapshot_name
235
+   - description: group_snapshot_description
236
+   - created_at: group_snapshot_created_at
237
+   - members: group_snapshot_members
238
+   - links: group_snapshot_links
239
+
240
+Response example
241
+----------------
242
+
243
+.. literalinclude:: samples/share-group-snapshot-create-response.json
244
+   :language: javascript
245
+
246
+
247
+Reset share group snapshot state
248
+================================
249
+
250
+.. rest_method::  POST /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}/action
251
+
252
+Administrator only. Explicitly updates the state of a share group snapshot.
253
+
254
+Use the ``policy.json`` file to grant permissions for this action
255
+to other roles.
256
+
257
+Normal response codes: 202
258
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
259
+itemNotFound(404)
260
+
261
+Request
262
+-------
263
+
264
+.. rest_parameters:: parameters.yaml
265
+
266
+   - tenant_id: tenant_id_path
267
+   - group_snapshot_id: group_snapshot_id_path
268
+   - status: group_snapshot_status_required
269
+
270
+Request example
271
+---------------
272
+
273
+.. literalinclude:: samples/snapshot-actions-reset-state-request.json
274
+   :language: javascript
275
+
276
+
277
+Update share group snapshot
278
+===========================
279
+
280
+.. rest_method::  PUT /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
281
+
282
+Updates a share group snapshot.
283
+
284
+Normal response codes: 200
285
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
286
+itemNotFound(404), unprocessableEntity(422)
287
+
288
+Request
289
+-------
290
+
291
+.. rest_parameters:: parameters.yaml
292
+
293
+   - tenant_id: tenant_id_path
294
+   - group_snapshot_id: group_snapshot_id_path
295
+   - name: group_snapshot_name_option
296
+   - description: group_snapshot_description_option
297
+
298
+Request example
299
+---------------
300
+
301
+.. literalinclude:: samples/snapshot-update-request.json
302
+   :language: javascript
303
+
304
+Response parameters
305
+-------------------
306
+
307
+.. rest_parameters:: parameters.yaml
308
+
309
+   - id: group_snapshot_id
310
+   - project_id: project_id
311
+   - status: group_snapshot_status_required
312
+   - share_group_id: share_group_id
313
+   - name: group_snapshot_name
314
+   - description: group_snapshot_description
315
+   - created_at: group_snapshot_created_at
316
+   - members: group_snapshot_members
317
+   - links: group_snapshot_links
318
+
319
+Response example
320
+----------------
321
+
322
+.. literalinclude:: samples/share-group-snapshot-update-response.json
323
+   :language: javascript
324
+
325
+
326
+Delete share group snapshot
327
+===========================
328
+
329
+.. rest_method::  DELETE /v2/{tenant_id}/share-group-snapshots/{group_snapshot_id}
330
+
331
+Deletes a share group snapshot.
332
+
333
+Normal response codes: 202
334
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
335
+itemNotFound(404)
336
+
337
+Request
338
+-------
339
+
340
+.. rest_parameters:: parameters.yaml
341
+
342
+   - tenant_id: tenant_id_path
343
+   - group_snapshot_id: group_snapshot_id_path

Loading…
Cancel
Save