注意

本文档适用于 Ceph 的开发版本。

Admin Operations

An admin API request will be done on a URI that starts with the configurable ‘admin’ resource entry point. Authorization for the admin API duplicates the S3 authorization mechanism. Some operations require that the user holds special administrative capabilities. The response entity type (XML or JSON) may be specified as the ‘format’ option in the request and defaults to JSON if not specified.

Info

Get RGW cluster/endpoint information.

caps:: info=read

语法

GET /{admin}/info?format=json HTTP/1.1
Host: {fqdn}

请求参数

None.

Response Entities

If successful, the response contains an info section.

info

描述:: A container for all returned information.
类型:: Container

cluster_id

描述:: The (typically unique) identifier for the controlling backing store for the RGW cluster. In the typical case, this is value returned from librados::rados::cluster_fsid().
类型:: String
Parent:: info

Special Error Responses

None.

Get Usage

Request bandwidth usage information.

Note: this feature is disabled by default, can be enabled by setting rgw enable usage log = true in the appropriate section of ceph.conf. For changes in ceph.conf to take effect, radosgw process restart is needed.

caps:: usage=read

Syntax

GET /{admin}/usage?format=json HTTP/1.1
Host: {fqdn}

请求参数

uid

描述:: The user for which the information is requested. If not specified will apply to all users.
类型:: String
示例:: foo_user
必需:: 否

start

描述:: Date and (optional) time that specifies the start time of the requested data.
类型:: String
示例:: 2012-09-25 16:00:00
必需:: 否

end

描述:: Date and (optional) time that specifies the end time of the requested data (non-inclusive).
类型:: String
示例:: 2012-09-25 16:00:00
必需:: 否

show-entries

描述:: Specifies whether data entries should be returned.
类型:: Boolean
示例:: True [True]
必需:: 否

show-summary

描述:: Specifies whether data summary should be returned.
类型:: Boolean
示例:: True [True]
必需:: 否

Response Entities

If successful, the response contains the requested information.

usage

描述:: A container for the usage information.
类型:: Container

entries

描述:: A container for the usage entries information.
类型:: Container

user

描述:: A container for the user data information.
类型:: Container

owner

描述:: The name of the user that owns the buckets.
类型:: String

bucket

描述:: The bucket name.
类型:: String

time

描述:: Time lower bound for which data is being specified (rounded to the beginning of the first relevant hour).
类型:: String

epoch

描述:: The time specified in seconds since 1/1/1970.
类型:: String

categories

描述:: A container for stats categories.
类型:: Container

entry

描述:: A container for stats entry.
类型:: Container

category

描述:: Name of request category for which the stats are provided.
类型:: String

bytes_sent

描述:: Number of bytes sent by the RADOS Gateway.
类型:: 整数

bytes_received

描述:: Number of bytes received by the RADOS Gateway.
类型:: 整数

ops（操作）

描述:: Number of operations.
类型:: 整数

successful_ops

描述:: Number of successful operations.
类型:: 整数

summary

描述:: A container for stats summary.
类型:: Container

total

描述:: A container for stats summary aggregated total.
类型:: Container

Special Error Responses

TBD.

Trim Usage

Remove usage information. With no dates specified, removes all usage information.

Note: this feature is disabled by default, can be enabled by setting rgw enable usage log = true in the appropriate section of ceph.conf. For changes in ceph.conf to take effect, radosgw process restart is needed.

caps:: usage=write

Syntax

DELETE /{admin}/usage?format=json HTTP/1.1
Host: {fqdn}

请求参数

uid

描述:: The user for which the information is requested. If not specified will apply to all users.
类型:: String
示例:: foo_user
必需:: 否

start

描述:: Date and (optional) time that specifies the start time of the requested data.
类型:: String
示例:: 2012-09-25 16:00:00
必需:: 否

end

描述:: Date and (optional) time that specifies the end time of the requested data (none inclusive).
类型:: String
示例:: 2012-09-25 16:00:00
必需:: 否

remove-all

描述:: Required when uid is not specified, in order to acknowledge multi user data removal.
类型:: Boolean
示例:: True [False]
必需:: 否

Special Error Responses

TBD.

Get User Info

Get user information. Cap users or user-info-without-keys must be set to read to run this operation. If cap user-info-without-keys is set to read or *, S3 keys and Swift keys will not be included in the response unless the user running this operation is the system user, an admin user, or the cap users is set to read.

Either a uid or access-key must be supplied as a request parameter. We recommend supplying uid. If both are provided but correspond to different users, the info for the user specified with uid will be returned.

Syntax

GET /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

access-key

Response Entities

If successful, the response contains the user information.

user

user_id

display_name

suspended

max_buckets

subusers

keys

swift_keys

caps

Special Error Responses

None.

Create Account

Squid 版本新增。

Create a new account.

caps:: accounts=write

Syntax

POST /{admin}/account?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

id

描述:: The ID of the account to be created.
类型:: String
示例:: RGW00000000000000001
必需:: 是

An account ID must be 20 characters long, and in the format of the string “RGW” followed by 17 numeric characters.

name

描述:: The name of the account to be created.
类型:: String
示例:: account_name
必需:: 是

email

描述:: The email address associated with the account.
类型:: String
示例:: foo@bar.com
必需:: 否

tenant

描述:: The Tenant under which the account exists.
类型:: string
示例:: tenant1
必需:: 否

max-users

描述:: Specifies the maximum number of users the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

max-roles

描述:: Specifies the maximum number of roles the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

max-groups

描述:: Specifies the maximum number of groups the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

max-access-keys

描述:: Specifies the maximum number of access keys the account can own. The default is 4.
类型:: 整数
示例:: 1 [4]
必需:: 否

max-buckets

描述:: Specifies the maximum number of buckets the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

Response Entities

If successful, the response contains the following account information.

account

描述:: A container for the account information.
类型:: Container

id

描述:: The ID of the account created.
类型:: String
Parent:: account

tenant

描述:: The Tenant under which the account exists.
类型:: String
Parent:: account

name

描述:: The name of the account created.
类型:: String
Parent:: account

email

描述:: The email address associated with the account.
类型:: String
Parent:: account

max_users

描述:: The maximum number of users the account can own.
类型:: 整数
Parent:: account

max_roles

描述:: The maximum number of roles the account can own.
类型:: 整数
Parent:: account

max_groups

描述:: The maximum number of groups the account can own.
类型:: 整数
Parent:: account

max_buckets

描述:: The maximum number of buckets the account can own.
类型:: 整数
Parent:: account

max_access_keys

描述:: The maximum number of access keys the account can own.
类型:: 整数
Parent:: account

quota

描述:: A container for the account quota information.
类型:: Container
Parent:: account

enabled

描述:: Whether quota is enabled at the account level.
类型:: Bool
Parent:: quota

check_on_raw

描述:: Whether quota should be checked on raw usage instead of the 4 KiB rounded one.
类型:: Bool
Parent:: quota

max_size

描述:: The max quota size in bytes.
类型:: 整数
Parent:: quota

max_size_kb

描述:: The max quota size in kilobytes.
类型:: 整数
Parent:: quota

max_objects

描述:: The max number of objects that an account can own.
类型:: 整数
Parent:: quota

bucket_quota

描述:: A container for the account bucket-level quota information.
类型:: Container
Parent:: account

enabled

描述:: Whether quota is enabled at the bucket level for the account.
类型:: Bool
Parent:: bucket_quota

check_on_raw

描述:: Whether bucket quota for the account should be checked on raw usage instead of the 4 KiB rounded one.
类型:: Bool
Parent:: bucket_quota

max_size

描述:: The max quota size in bytes for buckets under the account.
类型:: 整数
Parent:: bucket_quota

max_size_kb

描述:: The max quota size in kilobytes for buckets under the account.
类型:: 整数
Parent:: bucket_quota

max_objects

描述:: The max number of objects that a bucket under the account can have.
类型:: 整数
Parent:: bucket_quota

Special Error Responses

AccountAlreadyExists

描述:: Attempt to create existing account. This can happen if the account ID or the email is already in use.
Code:: 409 Conflict

Modify Account

Squid 版本新增。

Modify an account. Either id, name, or email must be provided.

caps:: accounts=write

Syntax

PUT /{admin}/account?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

id

描述:: The ID of the account to be modified.
类型:: String
示例:: RGW00000000000000001
必需:: 否

name

描述:: The name of the account to be modified.
类型:: String
示例:: account_name
必需:: 否

email

描述:: The email address of the account to be modified.
类型:: String
示例:: foo@bar.com
必需:: 否

max-users

描述:: Specifies the maximum number of users the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

max-roles

描述:: Specifies the maximum number of roles the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

max-groups

描述:: Specifies the maximum number of groups the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

max-access-keys

描述:: Specifies the maximum number of access keys the account can own. The default is 4.
类型:: 整数
示例:: 1 [4]
必需:: 否

max-buckets

描述:: Specifies the maximum number of buckets the account can own. The default is 1000.
类型:: 整数
示例:: 500 [1000]
必需:: 否

Response Entities

If successful, the response contains the following account information.

account

描述:: A container for the account information.
类型:: Container

id

描述:: The account ID.
类型:: String
Parent:: account

tenant

描述:: The Tenant under which the account exists.
类型:: String
Parent:: account

name

描述:: The name of the account created.
类型:: String
Parent:: account

email

描述:: The email address associated with the account.
类型:: String
Parent:: account

max_users

描述:: The maximum number of users the account can own.
类型:: 整数
Parent:: account

max_roles

描述:: The maximum number of roles the account can own.
类型:: 整数
Parent:: account

max_groups

描述:: The maximum number of groups the account can own.
类型:: 整数
Parent:: account

max_buckets

描述:: The maximum number of buckets the account can own.
类型:: 整数
Parent:: account

max_access_keys

描述:: The maximum number of access keys the account can own.
类型:: 整数
Parent:: account

quota

描述:: A container for the account quota information.
类型:: Container
Parent:: account

enabled

描述:: Whether quota is enabled at the account level.
类型:: Bool
Parent:: quota

check_on_raw

描述:: Whether quota should be checked on raw usage instead of the 4 KiB rounded one.
类型:: Bool
Parent:: quota

max_size

描述:: The max quota size in bytes.
类型:: 整数
Parent:: quota

max_size_kb

描述:: The max quota size in kilobytes.
类型:: 整数
Parent:: quota

max_objects

描述:: The max number of objects that an account can own.
类型:: 整数
Parent:: quota

bucket_quota

描述:: A container for the account bucket-level quota information.
类型:: Container
Parent:: account

enabled

描述:: Whether quota is enabled at the bucket level for the account.
类型:: Bool
Parent:: bucket_quota

check_on_raw

描述:: Whether bucket quota for the account should be checked on raw usage instead of the 4 KiB rounded one.
类型:: Bool
Parent:: bucket_quota

max_size

描述:: The max quota size in bytes for buckets under the account.
类型:: 整数
Parent:: bucket_quota

max_size_kb

描述:: The max quota size in kilobytes for buckets under the account.
类型:: 整数
Parent:: bucket_quota

max_objects

描述:: The max number of objects that a bucket under the account can have.
类型:: 整数
Parent:: bucket_quota

Special Error Responses

None.

Get Account Info

Squid 版本新增。

Get account info. Either an id or a name must be provided.

caps:: accounts=write

Syntax

GET /{admin}/account?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

id

描述:: The ID of the account to get info for.
类型:: String
示例:: RGW00000000000000001
必需:: 否

name

描述:: The name of the account to get info for.
类型:: String
示例:: account_name
必需:: 否

Response Entities

If successful, the response contains the following account information.

account

描述:: A container for the account information.
类型:: Container

id

描述:: The account ID.
类型:: String
Parent:: account

tenant

描述:: The Tenant under which the account exists.
类型:: String
Parent:: account

name

描述:: The name of the account created.
类型:: String
Parent:: account

email

描述:: The email address associated with the account.
类型:: String
Parent:: account

max_users

描述:: The maximum number of users the account can own.
类型:: 整数
Parent:: account

max_roles

描述:: The maximum number of roles the account can own.
类型:: 整数
Parent:: account

max_groups

描述:: The maximum number of groups the account can own.
类型:: 整数
Parent:: account

max_buckets

描述:: The maximum number of buckets the account can own.
类型:: 整数
Parent:: account

max_access_keys

描述:: The maximum number of access keys the account can own.
类型:: 整数
Parent:: account

quota

描述:: A container for the account quota information.
类型:: Container
Parent:: account

enabled

描述:: Whether quota is enabled at the account level.
类型:: Bool
Parent:: quota

check_on_raw

描述:: Whether quota should be checked on raw usage instead of the 4 KiB rounded one.
类型:: Bool
Parent:: quota

max_size

描述:: The max quota size in bytes.
类型:: 整数
Parent:: quota

max_size_kb

描述:: The max quota size in kilobytes.
类型:: 整数
Parent:: quota

max_objects

描述:: The max number of objects that an account can own.
类型:: 整数
Parent:: quota

bucket_quota

描述:: A container for the account bucket-level quota information.
类型:: Container
Parent:: account

enabled

描述:: Whether quota is enabled at the bucket level for the account.
类型:: Bool
Parent:: bucket_quota

check_on_raw

描述:: Whether bucket quota for the account should be checked on raw usage instead of the 4 KiB rounded one.
类型:: Bool
Parent:: bucket_quota

max_size

描述:: The max quota size in bytes for buckets under the account.
类型:: 整数
Parent:: bucket_quota

max_size_kb

描述:: The max quota size in kilobytes for buckets under the account.
类型:: 整数
Parent:: bucket_quota

max_objects

描述:: The max number of objects that a bucket under the account can have.
类型:: 整数
Parent:: bucket_quota

Special Error Responses

None.

Remove Account

Squid 版本新增。

Remove an existing account. Either id, name, or email must be provided.

caps:: accounts=write

Syntax

DELETE /{admin}/account?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

id

描述:: The ID of the account to be removed.
类型:: String
示例:: RGW00000000000000001
必需:: 否

tenant

描述:: The Tenant under which the account exists.
类型:: String
示例:: tenant
必需:: 否

name

描述:: The name of the account to be removed.
类型:: String
示例:: account_name
必需:: 否

email

描述:: The email address associated with the account to be removed.
类型:: String
示例:: foo@bar.com
必需:: 否

Response Entities

None

Special Error Responses

None.

Create User

Create a new user. By default, a S3 key pair will be created automatically and returned in the response. If only one of access-key or secret-key is provided, the omitted key will be automatically generated. By default, a generated key is added to the keyring without replacing an existing key pair. If access-key is specified and refers to an existing key owned by the user then it will be modified.

New in version Luminous.

A tenant may either be specified as a part of uid or as an additional request param.

caps:: users=write

Syntax

PUT /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID to be created.
类型:: String
示例:: foo_user
必需:: 是

A tenant name may also specified as a part of uid, by following the syntax tenant$user, refer to Multitenancy for more details.

display-name

描述:: The display name of the user to be created.
类型:: String
示例:: foo user
必需:: 是

email

描述:: The email address associated with the user.
类型:: String
示例:: foo@bar.com
必需:: 否

key-type

描述:: Key type to be generated, options are: swift, s3 (default).
类型:: String
示例:: s3 [s3]
必需:: 否

access-key

描述:: Specify access key.
类型:: String
示例:: ABCD0EF12GHIJ2K34LMN
必需:: 否

secret-key

描述:: Specify secret key.
类型:: String
示例:: 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
必需:: 否

user-caps

描述:: User capabilities.
类型:: String
示例:: usage=read, write; users=read
必需:: 否

generate-key

描述:: Generate a new key pair and add to the existing keyring.
类型:: Boolean
示例:: True [True]
必需:: 否

max-buckets

描述:: Specify the maximum number of buckets the user can own.
类型:: 整数
示例:: 500 [1000]
必需:: 否

suspended

描述:: Specify whether the user should be suspended.
类型:: Boolean
示例:: False [False]
必需:: 否

版本 Jewel 新增。

tenant

描述:: the Tenant under which a user is a part of.
类型:: string
示例:: tenant1
必需:: 否

default-placement

描述:: default placement for the user.
类型:: string
示例:: default-placement
必需:: 否

default-storage-class :Description: default storage class for the user, default-placement must be defined when setting this option. :Type: string :Example: STANDARD-1A :Required: No

Squid 版本新增。

account-id

描述:: the account under which a user should exist.
类型:: string
示例:: RGW00000000000000001
必需:: 否

Response Entities

If successful, the response contains the user information.

user

描述:: A container for the user data information.
类型:: Container

tenant

描述:: The tenant which user is a part of.
类型:: String
Parent:: user

user_id

描述:: The user id.
类型:: String
Parent:: user

display_name

描述:: Display name for the user.
类型:: String
Parent:: user

suspended

描述:: True if the user is suspended.
类型:: Boolean
Parent:: user

max_buckets

描述:: The maximum number of buckets to be owned by the user.
类型:: 整数
Parent:: user

subusers

描述:: Subusers associated with this user account.
类型:: Container
Parent:: user

keys

描述:: S3 keys associated with this user account.
类型:: Container
Parent:: user

swift_keys

描述:: Swift keys associated with this user account.
类型:: Container
Parent:: user

caps

描述:: User capabilities.
类型:: Container
Parent:: user

Special Error Responses

UserExists

描述:: Attempt to create existing user.
Code:: 409 Conflict

InvalidAccessKey

描述:: Invalid access key specified.
Code:: 400 Bad Request

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

InvalidSecretKey

描述:: Invalid secret key specified.
Code:: 400 Bad Request

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

KeyExists

描述:: Provided access key exists and belongs to another user.
Code:: 409 Conflict

EmailExists

描述:: Provided email address exists.
Code:: 409 Conflict

InvalidCapability

描述:: Attempt to grant invalid admin capability.
Code:: 400 Bad Request

Modify User

Modify a user.

caps:: users=write

Syntax

POST /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID to be modified.
类型:: String
示例:: foo_user
必需:: 是

display-name

描述:: The display name of the user to be modified.
类型:: String
示例:: foo user
必需:: 否

email

描述:: The email address to be associated with the user.
类型:: String
示例:: foo@bar.com
必需:: 否

generate-key

描述:: Generate a new key pair and add to the existing keyring.
类型:: Boolean
示例:: True [False]
必需:: 否

access-key

描述:: Specify access key.
类型:: String
示例:: ABCD0EF12GHIJ2K34LMN
必需:: 否

secret-key

描述:: Specify secret key.
类型:: String
示例:: 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
必需:: 否

key-type

描述:: Key type to be generated, options are: swift, s3 (default).
类型:: String
示例:: s3
必需:: 否

max-buckets

描述:: Specify the maximum number of buckets the user can own.
类型:: 整数
示例:: 500 [1000]
必需:: 否

suspended

描述:: Specify whether the user should be suspended.
类型:: Boolean
示例:: False [False]
必需:: 否

op-mask

描述:: The op-mask of the user to be modified.
类型:: String
示例:: read, write, delete, *
必需:: 否

default-placement

描述:: default placement for the user.
类型:: string
示例:: default-placement
必需:: 否

default-storage-class :Description: default storage class for the user, default-placement must be defined when setting this option. :Type: string :Example: STANDARD-1A :Required: No

Response Entities

If successful, the response contains the user information.

user

描述:: A container for the user data information.
类型:: Container

user_id

描述:: The user id.
类型:: String
Parent:: user

display_name

描述:: Display name for the user.
类型:: String
Parent:: user

suspended

描述:: True if the user is suspended.
类型:: Boolean
Parent:: user

max_buckets

描述:: The maximum number of buckets to be owned by the user.
类型:: 整数
Parent:: user

subusers

描述:: Subusers associated with this user account.
类型:: Container
Parent:: user

keys

描述:: S3 keys associated with this user account.
类型:: Container
Parent:: user

swift_keys

描述:: Swift keys associated with this user account.
类型:: Container
Parent:: user

caps

描述:: User capabilities.
类型:: Container
Parent:: user

Special Error Responses

InvalidAccessKey

描述:: Invalid access key specified.
Code:: 400 Bad Request

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

InvalidSecretKey

描述:: Invalid secret key specified.
Code:: 400 Bad Request

KeyExists

描述:: Provided access key exists and belongs to another user.
Code:: 409 Conflict

EmailExists

描述:: Provided email address exists.
Code:: 409 Conflict

InvalidCapability

描述:: Attempt to grant invalid admin capability.
Code:: 400 Bad Request

Remove User

Remove an existing user.

caps:: users=write

Syntax

DELETE /{admin}/user?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID to be removed.
类型:: String
示例:: foo_user
必需:: Yes.

purge-data

描述:: When specified the buckets and objects belonging to the user will also be removed.
类型:: Boolean
示例:: True
必需:: 否

Response Entities

None

Special Error Responses

None.

Create Subuser

Create a new subuser (primarily useful for clients using the Swift API). Note that in general for a subuser to be useful, it must be granted permissions by specifying access. As with user creation if subuser is specified without secret, then a secret key will be automatically generated.

caps:: users=write

Syntax

PUT /{admin}/user?subuser&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID under which a subuser is to be created.
类型:: String
示例:: foo_user
必需:: 是

subuser

描述:: Specify the subuser ID to be created.
类型:: String
示例:: sub_foo
必需:: 是

secret-key

描述:: Specify secret key.
类型:: String
示例:: 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
必需:: 否

key-type

描述:: Key type to be generated, options are: swift (default), s3.
类型:: String
示例:: swift [swift]
必需:: 否

access

描述:: Set access permissions for sub-user, should be one of read, write, readwrite, full.
类型:: String
示例:: read
必需:: 否

generate-secret

描述:: Generate the secret key.
类型:: Boolean
示例:: True [False]
必需:: 否

Response Entities

If successful, the response contains the subuser information.

subusers

描述:: Subusers associated with the user account.
类型:: Container

id

描述:: Subuser id.
类型:: String
Parent:: subusers

permissions

描述:: Subuser access to user account.
类型:: String
Parent:: subusers

Special Error Responses

SubuserExists

描述:: Specified subuser exists.
Code:: 409 Conflict

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

InvalidSecretKey

描述:: Invalid secret key specified.
Code:: 400 Bad Request

InvalidAccess

描述:: Invalid subuser access specified.
Code:: 400 Bad Request

Modify Subuser

Modify an existing subuser

caps:: users=write

Syntax

POST /{admin}/user?subuser&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID under which the subuser is to be modified.
类型:: String
示例:: foo_user
必需:: 是

subuser

描述:: The subuser ID to be modified.
类型:: String
示例:: sub_foo
必需:: 是

generate-secret

描述:: Generate a new secret key for the subuser, replacing the existing key.
类型:: Boolean
示例:: True [False]
必需:: 否

secret

描述:: Specify secret key.
类型:: String
示例:: 0AbCDEFg1h2i34JklM5nop6QrSTUV+WxyzaBC7D8
必需:: 否

key-type

描述:: Key type to be generated, options are: swift (default), s3 .
类型:: String
示例:: swift [swift]
必需:: 否

access

描述:: Set access permissions for sub-user, should be one of read, write, readwrite, full.
类型:: String
示例:: read
必需:: 否

Response Entities

If successful, the response contains the subuser information.

subusers

描述:: Subusers associated with the user account.
类型:: Container

id

描述:: Subuser id.
类型:: String
Parent:: subusers

permissions

描述:: Subuser access to user account.
类型:: String
Parent:: subusers

Special Error Responses

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

InvalidSecretKey

描述:: Invalid secret key specified.
Code:: 400 Bad Request

InvalidAccess

描述:: Invalid subuser access specified.
Code:: 400 Bad Request

Remove Subuser

Remove an existing subuser

caps:: users=write

Syntax

DELETE /{admin}/user?subuser&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID under which the subuser is to be removed.
类型:: String
示例:: foo_user
必需:: 是

subuser

描述:: The subuser ID to be removed.
类型:: String
示例:: sub_foo
必需:: 是

purge-keys

描述:: Remove keys belonging to the subuser.
类型:: Boolean
示例:: True [True]
必需:: 否

Response Entities

None.

Special Error Responses

None.

Create Key

Create a new key. If a subuser is specified then by default created keys will be swift type. If only one of access-key or secret-key is provided the committed key will be automatically generated, that is if only secret-key is specified then access-key will be automatically generated. By default, a generated key is added to the keyring without replacing an existing key pair. If access-key is specified and refers to an existing key owned by the user then it will be modified. The response is a container listing all keys of the same type as the key created. Note that when creating a swift key, specifying the option access-key will have no effect. Additionally, only one swift key may be held by each user or subuser.

caps:: users=write

Syntax

PUT /{admin}/user?key&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID to receive the new key.
类型:: String
示例:: foo_user
必需:: 是

subuser

描述:: The subuser ID to receive the new key.
类型:: String
示例:: sub_foo
必需:: 否

key-type

描述:: Key type to be generated, options are: swift, s3 (default).
类型:: String
示例:: s3 [s3]
必需:: 否

access-key

描述:: Specify the access key.
类型:: String
示例:: AB01C2D3EF45G6H7IJ8K
必需:: 否

secret-key

描述:: Specify the secret key.
类型:: String
示例:: 0ab/CdeFGhij1klmnopqRSTUv1WxyZabcDEFgHij
必需:: 否

generate-key

描述:: Generate a new key pair and add to the existing keyring.
类型:: Boolean
示例:: True [True]
必需:: 否

active

描述:: Activate or deactivate a key.
类型:: Boolean
示例:: True [True]
必需:: 否

Response Entities

keys

描述:: Keys of type created associated with this user account.
类型:: Container

user

描述:: The user account associated with the key.
类型:: String
Parent:: keys

access-key

描述:: The access key.
类型:: String
Parent:: keys

secret-key

描述:: The secret key
类型:: String
Parent:: keys

Special Error Responses

InvalidAccessKey

描述:: Invalid access key specified.
Code:: 400 Bad Request

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

InvalidSecretKey

描述:: Invalid secret key specified.
Code:: 400 Bad Request

InvalidKeyType

描述:: Invalid key type specified.
Code:: 400 Bad Request

KeyExists

描述:: Provided access key exists and belongs to another user.
Code:: 409 Conflict

Remove Key

Remove an existing key.

caps:: users=write

Syntax

DELETE /{admin}/user?key&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

access-key

描述:: The S3 access key belonging to the S3 key pair to remove.
类型:: String
示例:: AB01C2D3EF45G6H7IJ8K
必需:: 是

uid

描述:: The user to remove the key from.
类型:: String
示例:: foo_user
必需:: 否

subuser

描述:: The subuser to remove the key from.
类型:: String
示例:: sub_foo
必需:: 否

key-type

描述:: Key type to be removed, options are: swift, s3. NOTE: Required to remove swift key.
类型:: String
示例:: swift
必需:: 否

Special Error Responses

None.

Response Entities

None.

Get Bucket Info

Get information about a subset of the existing buckets. If uid is specified without bucket then all buckets belonging to the user will be returned. If bucket alone is specified, information for that particular bucket will be retrieved.

If max-entries is specified to limit the number of buckets returned, the response body will change and contain the keys buckets, count and truncated. If truncated is true the marker key will also be added.

caps:: buckets=read

Syntax

GET /{admin}/bucket?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket to return info on.
类型:: String
示例:: foo_bucket
必需:: 否

uid

描述:: The user to retrieve bucket information for.
类型:: String
示例:: foo_user
必需:: 否

stats

描述:: Return bucket statistics.
类型:: Boolean
示例:: True [False]
必需:: 否

max-entries

描述:: The number of bucket list entries to return.
类型:: 整数
示例:: 100
必需:: 否

marker

描述:: The marker to use when listing buckets.
类型:: String (bucket name)
示例:: my-bucket
必需:: 否

Response Entities

If successful the request returns a buckets container containing the desired bucket information.

stats

描述:: Per bucket information.
类型:: Container

buckets

描述:: Contains a list of one or more bucket containers.
类型:: Container

bucket

描述:: Container for single bucket information.
类型:: Container
Parent:: buckets

name

描述:: The name of the bucket.
类型:: String
Parent:: bucket

pool

描述:: The pool the bucket is stored in.
类型:: String
Parent:: bucket

id

描述:: The unique bucket id.
类型:: String
Parent:: bucket

marker

描述:: Internal bucket tag.
类型:: String
Parent:: bucket

owner

描述:: The user id of the bucket owner.
类型:: String
Parent:: bucket

usage

描述:: Storage usage information.
类型:: Container
Parent:: bucket

索引

描述:: Status of bucket index.
类型:: String
Parent:: bucket

count

描述:: Number of returned buckets, only if max-entries is specified.
类型:: 整数

truncated

描述:: Reported if the response is truncated when max-entries is specified.
类型:: Boolean

marker

描述:: If truncated is true the marker key is returned with the marker (bucket name) to use to continue pagination.
类型:: String

Special Error Responses

IndexRepairFailed

描述:: Bucket index repair failed.
Code:: 409 Conflict

Check Bucket Index

Check the index of an existing bucket. NOTE: to check multipart object accounting with check-objects, fix must be set to True.

caps:: buckets=write

Syntax

GET /{admin}/bucket?index&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket to return info on.
类型:: String
示例:: foo_bucket
必需:: 是

check-objects

描述:: Check multipart object accounting.
类型:: Boolean
示例:: True [False]
必需:: 否

fix

描述:: Also fix the bucket index when checking.
类型:: Boolean
示例:: False [False]
必需:: 否

Response Entities

索引

描述:: Status of bucket index.
类型:: String

Special Error Responses

IndexRepairFailed

描述:: Bucket index repair failed.
Code:: 409 Conflict

Remove Bucket

Delete an existing bucket.

caps:: buckets=write

Syntax

DELETE /{admin}/bucket?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket to remove.
类型:: String
示例:: foo_bucket
必需:: 是

tenant

描述:: The tenant under which the bucket is to be removed.
类型:: String
示例:: tenant1
必需:: 否

purge-objects

描述:: Remove a buckets objects before deletion.
类型:: Boolean
示例:: True [False]
必需:: 否

bypass-gc

描述:: Bypass garbage collection.
类型:: Boolean
示例:: True [False]
必需:: 否

Response Entities

None.

Special Error Responses

BucketNotEmpty

描述:: Attempted to delete non-empty bucket.
Code:: 409 Conflict

ObjectRemovalFailed

描述:: Unable to remove objects.
Code:: 409 Conflict

Unlink Bucket

Unlink a bucket from a specified user. Primarily useful for changing bucket ownership.

caps:: buckets=write

Syntax

POST /{admin}/bucket?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket to unlink.
类型:: String
示例:: foo_bucket
必需:: 是

uid

描述:: The user ID to unlink the bucket from.
类型:: String
示例:: foo_user
必需:: 是

Response Entities

None.

Special Error Responses

BucketUnlinkFailed

描述:: Unable to unlink bucket from specified user.
Code:: 409 Conflict

Link Bucket

Link a bucket to a specified user, unlinking the bucket from any previous user.

caps:: buckets=write

Syntax

PUT /{admin}/bucket?format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket name to unlink.
类型:: String
示例:: foo_bucket
必需:: 是

bucket-id

描述:: The bucket id to unlink.
类型:: String
示例:: dev.6607669.420
必需:: 否

uid

描述:: The user ID to link the bucket to.
类型:: String
示例:: foo_user
必需:: 是

Response Entities

bucket

描述:: Container for single bucket information.
类型:: Container

name

描述:: The name of the bucket.
类型:: String
Parent:: bucket

pool

描述:: The pool the bucket is stored in.
类型:: String
Parent:: bucket

id

描述:: The unique bucket id.
类型:: String
Parent:: bucket

marker

描述:: Internal bucket tag.
类型:: String
Parent:: bucket

owner

描述:: The user id of the bucket owner.
类型:: String
Parent:: bucket

usage

描述:: Storage usage information.
类型:: Container
Parent:: bucket

索引

描述:: Status of bucket index.
类型:: String
Parent:: bucket

Special Error Responses

BucketUnlinkFailed

描述:: Unable to unlink bucket from specified user.
Code:: 409 Conflict

BucketLinkFailed

描述:: Unable to link bucket to specified user.
Code:: 409 Conflict

Remove Object

Remove an existing object. NOTE: Does not require owner to be non-suspended.

caps:: buckets=write

Syntax

DELETE /{admin}/bucket?object&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket containing the object to be removed.
类型:: String
示例:: foo_bucket
必需:: 是

object

描述:: The object to remove.
类型:: String
示例:: foo.txt
必需:: 是

Response Entities

None.

Special Error Responses

NoSuchObject

描述:: Specified object does not exist.
Code:: 404 Not Found

ObjectRemovalFailed

描述:: Unable to remove objects.
Code:: 409 Conflict

Get Bucket or Object Policy

Read the policy of an object or bucket.

caps:: buckets=read

Syntax

GET /{admin}/bucket?policy&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

bucket

描述:: The bucket to read the policy from.
类型:: String
示例:: foo_bucket
必需:: 是

object

描述:: The object to read the policy from.
类型:: String
示例:: foo.txt
必需:: 否

Response Entities

If successful, returns the object or bucket policy

policy

描述:: Access control policy.
类型:: Container

Special Error Responses

IncompleteBody

描述:: Either bucket was not specified for a bucket policy request or bucket and object were not specified for an object policy request.
Code:: 400 Bad Request

Add A User Capability

Add an administrative capability to a specified user.

caps:: users=write

Syntax

PUT /{admin}/user?caps&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID to add an administrative capability to.
类型:: String
示例:: foo_user
必需:: 是

user-caps

描述:: The administrative capability to add to the user.
类型:: String
示例:: usage=read,write;user=write
必需:: 是

Response Entities

If successful, the response contains the user’s capabilities.

user

描述:: A container for the user data information.
类型:: Container
Parent:: user

user_id

描述:: The user id.
类型:: String
Parent:: user

caps

描述:: User capabilities.
类型:: Container
Parent:: user

Special Error Responses

InvalidCapability

描述:: Attempt to grant invalid admin capability.
Code:: 400 Bad Request

Example Request

PUT /{admin}/user?caps&user-caps=usage=read,write;user=write&format=json HTTP/1.1
Host: {fqdn}
Content-Type: text/plain
Authorization: {your-authorization-token}

Remove A User Capability

Remove an administrative capability from a specified user.

caps:: users=write

Syntax

DELETE /{admin}/user?caps&format=json HTTP/1.1
Host: {fqdn}

Request Parameters

uid

描述:: The user ID to remove an administrative capability from.
类型:: String
示例:: foo_user
必需:: 是

user-caps

描述:: The administrative capabilities to remove from the user.
类型:: String
示例:: usage=read, write
必需:: 是

Response Entities

If successful, the response contains the user’s capabilities.

user

描述:: A container for the user data information.
类型:: Container
Parent:: user

user_id

描述:: The user id.
类型:: String
Parent:: user

caps

描述:: User capabilities.
类型:: Container
Parent:: user

Special Error Responses

InvalidCapability

描述:: Attempt to remove an invalid admin capability.
Code:: 400 Bad Request

NoSuchCap

描述:: User does not possess specified capability.
Code:: 404 Not Found

Quotas

The Admin Operations API enables you to set quotas on users and on buckets owned by users, and on accounts and on buckets owned by accounts. See Quota Management for additional details. Quotas include the maximum number of objects in a bucket and the maximum storage size in megabytes.

To view quotas for users, the user must have a users=read capability. To set, modify or disable a quota, the user must have users=write capability.

To view quotas for accounts, the user must have a accounts=read capability. To set, modify or disable a quota, the user must have accounts=write capability. See the Admin Guide for details.

Valid parameters for quotas include

Bucket: The bucket option allows you to specify a quota for buckets owned by a user.
Maximum Objects: The max-objects setting allows you to specify the maximum number of objects. A negative value disables this setting.
Maximum Size: The max-size option allows you to specify a quota for the maximum number of bytes. The max-size-kb option allows you to specify it in KiB. A negative value disables this setting.
Quota Type: The quota-type option sets the scope for the quota. The options are bucket and user for user-level quota. The options are bucket and account for account-level quota.
Enable/Disable Quota: The enabled option specifies whether the quota should be enabled. The value should be either ‘True’ or ‘False’.

Get User Quota

To get a quota, the user must have users capability set with read permission.

GET /admin/user?quota&uid=<uid>&quota-type=user

Set User Quota

To set a quota, the user must have users capability set with write permission.

PUT /admin/user?quota&uid=<uid>&quota-type=user

The content must include a JSON representation of the quota settings as encoded in the corresponding read operation.

Get Bucket Quota

To get a quota, the user must have users capability set with read permission.

GET /admin/user?quota&uid=<uid>&quota-type=bucket

Set Bucket Quota

To set a quota, the user must have users capability set with write permission.

PUT /admin/user?quota&uid=<uid>&quota-type=bucket

The content must include a JSON representation of the quota settings as encoded in the corresponding read operation.

Set Quota for an Individual Bucket

To set a quota, the user must have buckets capability set with write permission.

PUT /admin/bucket?quota&uid=<uid>&bucket=<bucket-name>

The content must include a JSON representation of the quota settings as mentioned in Set Bucket Quota section above.

Set Account Quota

To set a quota, the user must have accounts capability set with write permission.

PUT /admin/account?quota&id=<account_id>&quota-type=account

Set Bucket Quota under an Account

To set a quota, the user must have accounts capability set with write permission.

PUT /admin/account?quota&id=<account_id>&quota-type=bucket

Rate Limit

The Admin Operations API enables you to set and get ratelimit configurations on users and on bucket and global rate limit configurations. See Rate Limit Management for additional details. Rate Limit includes the maximum number of operations and/or bytes per accumulation interval, separated by read and/or write (Additionally list and get operations), to a bucket and/or by a user and the maximum storage size in megabytes.

To view rate limit, the user must have a ratelimit=read capability. To set, modify or disable a ratelimit, the user must have ratelimit=write capability. See the Admin Guide for details.

Valid parameters for quotas include

Bucket: The bucket option allows you to specify a rate limit for a bucket.
User: The uid option allows you to specify a rate limit for a user.
Maximum Read Bytes: The max-read-bytes setting allows you to specify the maximum number of read bytes per accumulation interval. A 0 value disables this setting.
Maximum Write Bytes: The max-write-bytes setting allows you to specify the maximum number of write bytes per accumulation interval. A 0 value disables this setting.
Maximum Read Ops: The max-read-ops setting allows you to specify the maximum number of read ops per accumulation interval. A 0 value disables this setting.
Maximum Write Ops: The max-write-ops setting allows you to specify the maximum number of write ops per accumulation interval. A 0 value disables this setting.
Maximum List Ops: The max-list-ops setting allows you to specify the maximum number of bucket listing requests per accumulation interval. A 0 value disables this setting.
Maximum Delete Ops: The max-delete-ops setting allows you to specify the maximum number of delete operations per accumulation interval. A 0 value disables throttling.
Global: The global option allows you to specify a global rate limit. The value should be either ‘True’ or ‘False’.
Rate Limit Scope: The ratelimit-scope option sets the scope for the rate limit. The options are bucket , user and anonymous. anonymous is only valid for setting global configuration
Enable/Disable Rate Limit: The enabled option specifies whether the rate limit should be enabled. The value should be either ‘True’ or ‘False’.