Object Storage Orchestration API Reference

ManualsBrandsAcronis ManualsApplicationsStorage 2.0

Table Of Contents

Acronis Storage 2.0

Object Storage Orchestration API

Reference

October 19, 2016

Summary of content (37 pages)

PAGE 1
Acronis Storage 2.
PAGE 2
Copyright Statement Acronis International GmbH, 2002-2016. All rights reserved. ”Acronis” and ”Acronis Secure Zone” are registered trademarks of Acronis International GmbH. ”Acronis Compute with Conﬁdence”, ”Acronis Startup Recovery Manager”, ”Acronis Active Restore”, ”Acronis Instant Restore” and the Acronis logo are trademarks of Acronis International GmbH. Linux is a registered trademark of Linus Torvalds. VMware and VMware Ready are trademarks and/or registered trademarks of VMware, Inc.
PAGE 3
Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.1 About the Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 1.2 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 2. User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.
PAGE 4
2.2.3 Responses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.3.1 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.3.2 Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.2.4 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.4.1 Sample Request #1 . . . . . . . . . . . . . . . . .
PAGE 5
2.4.4.4 Sample Response #2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.5 PUT Service ostor-limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.5.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 2.5.2.1 Syntax . . . . . . . . . . . . . . . . . . . . .
PAGE 6
3.1 GET Service ostor-usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.1.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.1.2 Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.1.2.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 3.1.2.2 Parameters . . . . . . . . . . . . . . . .
PAGE 7
CHAPTER 1 Introduction 1.1 About the Guide The guide explains how to use the REST API to manage S3 clusters based on Acronis Storage. The system API enables storage administrators to manage users, limits, and billing statistics. The system REST API enables remote execution of operations similar to ostor-s3-admin functionality. 1.2 Authentication Management request must be authenticated with the AWS Access Key ID corresponding to the S3 system user.
PAGE 8
CHAPTER 2 User Management 2.1 GET Service ostor-users 2.1.1 Description Lists information about all users or the user speciﬁed by either email or ID. 2.1.2 Requests 2.1.2.1 Syntax GET /?ostor-users HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: GET /?ostor-users&emailAddress= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: GET /?ostor-users&id= HTTP/1.1 Host: s3.amazonaws.
PAGE 9
2.1. GET Service ostor-users Authorization: 2.1.2.2 Parameters Parameter emailAddress Description Required User email address. No* Type: string. Default value: none. User ID. id No* Type: string. Default value: none. * Only one of the required parameters can be set in a single request. If neither emailAddress nor id are set, the response is information about all users, otherwise the response is information about the user with the speciﬁed email or ID. 2.1.2.
PAGE 10
Chapter 2. User Management ”AWSAccessKeys : [ { ”AWSAccessKeyId” : ””, ”AWSSecretAccessKey” : ”” }] } 2.1.3.3 Errors Returns Error Code 400, if more than one parameter is set. 2.1.4 Examples 2.1.4.1 Sample Request #1 Returns information about all users GET /?ostor-users HTTP/1.1 Host: s3.amazonaws.com Date: Wed, 30 Apr 2016 22:32:00 GMT Authorization: 2.1.4.2 Sample Response #1 HTTP/1.1 200 OK Transfer-encoding : chunked Server : nginx/1.8.
PAGE 11
2.1. GET Service ostor-users { ”UserEmail”: ”user@email.com”, ”UserId”: ”c5bf3c29f0a86585”, ”AWSAccessKeys”: [ { ”AWSAccessKeyId”: ”c5bf3c29f0a865851KPQ”, ”AWSSecretAccessKey”: ”yqt3or2xMFn6mtvPH5Fdrr9nbp2foDCKOCLYjCTb” }] }, { ”UserEmail”: ”root2@email.com”, ”UserId”: ”da2ccd035ce34bc3”, ”AWSAccessKeys”: [ { ”AWSAccessKeyId”: ”da2ccd035ce34bc3XD5P”, ”AWSSecretAccessKey”: ”wHfEBQFO7HN7fhoHx45lHHyBInAOOCZTHtvveYlB” }] }, { ”UserEmail”: ”root0@email.
PAGE 12
Chapter 2. User Management }] 2.1.4.3 Sample Request #2 Returns information about the user with the ID fc06056891f36588. GET /?ostor-users&id=fc06056891f36588 HTTP/1.1 Host: s3.amazonaws.com Date: Wed, 30 Apr 2016 22:32:00 GMT Authorization: 2.1.4.4 Sample Response #2 HTTP/1.1 200 OK Transfer-encoding : chunked Server : nginx/1.8.
PAGE 13
2.2. PUT Service ostor-users 2.2 PUT Service ostor-users 2.2.1 Description Creates a new user or generates/revokes access key pairs of existing users. 2.2.2 Requests 2.2.2.1 Syntax PUT /?ostor-users&emailAddress= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: PUT /?ostor-users&emailAddress=&genKey HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: PUT /?ostor-users&emailAddress=&revokeKey= HTTP/1.1 Host: s3.
PAGE 14
Chapter 2. User Management Parameter genKey Description Required Generates a new access key pair for the user. A user can only have two No key pairs. Type: ﬂag. Default value: none. revokeKey Removes the access key pair that corresponds to the speciﬁed access No key. Type: string. Default value: none. If neither genKey nor revokeKey are set, a new user with the speciﬁed email will be created. 2.2.2.3 Headers This implementation uses only common request headers. 2.2.3 Responses 2.2.3.
PAGE 15
2.2. PUT Service ostor-users } If a key is revoked, the body is empty. 2.2.4 Examples 2.2.4.1 Sample Request #1 Creates a user with the email test@test.test. PUT /?ostor-users&emailAddress=test@test.test HTTP/1.1 Host: s3.amazonaws.com Date: Thu, 07 Apr 2016 16:01:03 GMT +3:00 Authorization: 2.2.4.2 Sample Response #1 HTTP/1.1 200 OK x-amz-req-time-micros : 186132 Transfer-encoding : chunked Server : nginx/1.8.
PAGE 16
Chapter 2. User Management 2.2.4.3 Sample Request #2 Generates a new key pair for the user with the email user1@email.com. PUT /?ostor-users&emailAddress=user1@email.com&genKey HTTP/1.1 Host: s3.amazonaws.com Date: Thu, 07 Apr 2016 15:51:13 GMT +3:00 Authorization: 2.2.4.4 Sample Response #2 HTTP/1.1 200 OK x-amz-req-time-micros : 384103 Transfer-encoding : chunked Server : nginx/1.8.
PAGE 17
2.3. DELETE Service ostor-users 2.3 DELETE Service ostor-users 2.3.1 Description Deletes the user speciﬁed by email or ID. 2.3.2 Requests 2.3.2.1 Syntax DELETE /?ostor-users&emailAddress= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: 2.3.2.2 Parameters Parameter emailAddress Description Required User email address. Yes* Type: string. Default value: none. id User ID. Yes* Type: string. Default value: none.
PAGE 18
Chapter 2. User Management 2.3.3 Responses 2.3.3.1 Headers This implementation uses only common response headers. 2.3.3.2 Body Empty. 2.3.3.3 Errors Returns Error Note: Code 400, if more than one required parameter is set. If a user is successfully deleted, Status204NoContent is returned. 2.3.4 Examples 2.3.4.1 Sample Request Deletes the user with the email test@test.test. DELETE /?ostor-users&emailAddress=test@test.test HTTP/1.1 Host: s3.amazonaws.
PAGE 19
2.4. GET Service ostor-limits x-amz-request-id : 80000000000000030005c8ca5862476a Date : Wed, 30 Apr 2016 22:32:03 GMT Content-type : application/xml 2.4 GET Service ostor-limits 2.4.1 Description Lists information about limits on operations and bandwidth for the speciﬁed user or bucket. 2.4.2 Requests 2.4.2.1 Syntax GET /?ostor-limits&emailAddress= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: GET /?ostor-limits&bucket= HTTP/1.1 Host: s3.amazonaws.
PAGE 20
Chapter 2. User Management Parameter id Description Required User ID. Yes* Type: string. Default value: none. bucket Bucket name. Type: string. Default value: none. * Only one of the required parameters can be set in a single request. 2.4.2.3 Headers This implementation uses only common request headers. 2.4.3 Responses 2.4.3.1 Headers This implementation uses only common response headers. 2.4.3.
PAGE 21
2.4. GET Service ostor-limits Note: 0 means “unlimited”. 2.4.3.3 Errors Returns Error Code 400, if multiple parameters are set at once. Note: The limits are disabled by default. If limits for a user/bucket requested are disabled, an error will be returned. Use PUT ostor-limits to enable limits. 2.4.4 Examples 2.4.4.1 Sample Request #1 Returns information about limits for the user with the email user1@email.com. GET /?ostor-users&emailAddress=user1@email.com HTTP/1.1 Host: s3.amazonaws.
PAGE 22
Chapter 2. User Management ”ops:get” : ”0.50”, ”ops:put” : ”0.50”, ”ops:list” : ”0.50”, ”ops:delete” : ”0.50”, ”bandwidth:out” : ”0” } 2.4.4.3 Sample Request #2 Returns information about limits for the bucket bucket-1. GET /?ostor-limits&bucket=bucket-1 HTTP/1.1 Host: s3.amazonaws.com Date: Wed, 30 Apr 2016 22:32:00 GMT Authorization: 2.4.4.4 Sample Response #2 HTTP/1.1 200 OK Transfer-encoding : chunked Server : nginx/1.8.
PAGE 23
2.5. PUT Service ostor-limits 2.5 PUT Service ostor-limits 2.5.1 Description Sets limit values for the speciﬁed user or bucket. Either operations count or bandwidth limits can be speciﬁed in a single request. 2.5.2 Requests 2.5.2.1 Syntax PUT /?ostor-limits&emailAddress= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: GET /?ostor-limits&bucket= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: 2.5.2.
PAGE 24
Chapter 2. User Management Parameter bandwidth Description Required Enables bandwidth limits. Yes** Bandwidth limits types: { out | kb/s } Type: ﬂag. ops Enables operations limits. If set, all unspeciﬁed bandwidth limits are Yes** set to 0. Operations limits types: { default | ops/min, put | ops/min , get | ops/min, list | ops/min, delete | ops/min } Type: ﬂag. default Sets the default value for operations limits.
PAGE 25
2.5. PUT Service ostor-limits * Only one of the required parameters can be set in a single request. ** Either ops or bandwidth can be set in a single request. Note: Zero limit value means “unlimited”. 2.5.2.3 Headers This implementation uses only common request headers. 2.5.3 Responses 2.5.3.1 Headers This implementation uses only common response headers. 2.5.3.2 Body Empty. 2.5.3.3 Errors Returns Error Code 400, if a wrong set of parameters is speciﬁed. 2.5.4 Examples 2.5.4.
PAGE 26
Chapter 2. User Management 2.5.4.2 Sample Response #1 HTTP/1.1 200 OK Transfer-encoding : chunked Server : nginx/1.8.1 Connection: closed x-amz-request-id : 80000000000000030005c8caec96d65b Date : Thu, 07 Apr 2016 14:08:56 GMT Content-type : application/json 2.5.4.3 Sample Request #2 Sets all operations limits for the user with the email user1@email.com to 1 ops/sec. PUT /?ostor-limits&emailAddress=user1@email.com&ops&default=60 HTTP/1.1 Host: s3.amazonaws.
PAGE 27
2.5. PUT Service ostor-limits Date: Thu, 07 Apr 2016 14:08:55 GMT Authorization: 2.5.4.6 Sample Response #3 HTTP/1.1 200 OK Transfer-encoding : chunked Server : nginx/1.8.1 Connection: closed x-amz-request-id : 80000000000000030005c8caec96d65b Date : Thu, 07 Apr 2016 14:08:56 GMT Content-type : application/json 2.5.4.7 Sample Request #4 Sets operations limits for the bucket testbucket. The new PUT operations limit is 60 ops/s, LIST limit is 0.
PAGE 28
Chapter 2. User Management 2.6 DELETE Service ostor-limits 2.6.1 Description Sets a limit of the selected type to 0.0 (unlimited) for the speciﬁed user or bucket. 2.6.2 Requests 2.6.2.1 Syntax DELETE /?ostor-limits&emailAddress=&ops HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: DELETE /?ostor-limits&id=&ops HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: DELETE /?ostor-limits&bucket=&bandwidth HTTP/1.1 Host: s3.
PAGE 29
2.6. DELETE Service ostor-limits Parameter id Description Required User ID. Yes* Type: string. Default value: none. Bucket name. bucket Yes* Type: string. Default value: none. ops Removes operations limits. No bandwidth Removes bandwidth limits. No * Only one of the required parameters can be set in a single request. 2.6.2.3 Headers This implementation uses only common request headers. 2.6.3 Responses 2.6.3.1 Headers This implementation uses only common response headers. 2.6.3.2 Body Empty.
PAGE 30
Chapter 2. User Management PUT /?ostor-limits&emailAddress=user1@email.com&ops HTTP/1.1 Host: s3.amazonaws.com Date: Thu, 07 Apr 2016 14:08:55 GMT Authorization: 2.6.4.2 Sample Response HTTP/1.1 204 No Content Transfer-encoding : chunked Server : nginx/1.8.1 Connection: closed x-amz-request-id : 80000000000000030005c8caec96d65b Date : Thu, 07 Apr 2016 14:08:56 GMT Content-type : application/json 2.6.4.
PAGE 31
CHAPTER 3 Usage Statistics The S3 gateway can collect usage statistics for S3 users and S3 buckets. The collected data are saved as regular Object Storage objects. One such object contains statistics for the set usage period. To enable statistics collection, set S3_GW_USAGE_BUCKET to True in the gateway conﬁguration ﬁle (/var/lib/ostor/local/gw.conf by default).
PAGE 32
Chapter 3. Usage Statistics GET /?ostor-users&obj=object name HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: 3.1.2.2 Parameters The parameter is speciﬁed by the obj subresource. If the obj subresource is undeﬁned, the response contains information about all existing statistics objects. Otherwise information from the speciﬁed object obj is returned. Parameter obj Description Required Statistics object name. No Type: string. Default value: none. 3.1.2.
PAGE 33
3.1. GET Service ostor-usage ”s3-usage-obj1”, ”s3-usage-obj2”, ”s3-usage-obj3”, ...
PAGE 34
Chapter 3. Usage Statistics Authorization : 3.1.4.2 Sample Response #1 HTTP/1.1 200 OK x-amz-req-time-micros : 404 Transfer-encoding : chunked Server : nginx/1.8.1 Connection : keep-alive x-amz-request-id : 80000000000000030006b6be3b0ae378 Date : Mon, 11 Apr 2016 13:43:16 GMT Content-type : application/json { ”nr_items”: 9, ”truncated”: false, ”items”: [ ”s3-usage-8000000000000003-2016-04-11T13:10:29.000Z-1800”, ”s3-usage-8000000000000003-2016-04-11T13:12:53.
PAGE 35
3.1. GET Service ostor-usage Authorization: 3.1.4.4 Sample Response #2 HTTP/1.1 200 OK X-amz-req-time-micros : 576 Transfer-encoding : chunked Server : nginx/1.8.
PAGE 36
Chapter 3. Usage Statistics 3.2 DELETE Service ostor-usage 3.2.1 Description Deletes the statistics object speciﬁed by name. 3.2.2 Requests 3.2.2.1 Syntax DELETE /?ostor-users&obj= HTTP/1.1 Host: s3.amazonaws.com Date: Authorization: 3.2.2.2 Parameters Parameter obj Description Required Statistics object name. No Type: string. Default value: none. 3.2.2.3 Headers This implementation uses only common request headers. 3.2.3 Responses 3.2.3.
PAGE 37
3.2. DELETE Service ostor-usage 3.2.3.2 Body Empty. Note: If the request is successful, Status204NoContent is returned. 3.2.4 Examples 3.2.4.1 Sample Request The following request deletes statistics object with name s3-usage-8000000000000003-2016-04-11T13:33:55.000Z-30. DELETE /?ostor-usage&obj=s3-usage-8000000000000003-2016-04-11T13:12:53.000Z-30 /HTTP1.1 Date : Mon, 11 Apr 2016 17:52:05 GMT+3:00 Host : ostor-test-1 Authorization : authorization string 3.2.4.2 Sample Response HTTP/1.