4.5. Swift コンテナー操作

開発者は、Ceph Object Gateway 経由で Swift アプリケーションのプログラミングインターフェイス (API) を使用してコンテナーの操作を行うことができます。コンテナーを一覧表示、作成、更新、および削除できます。コンテナーのメタデータを追加または更新できます。

4.5.1. 前提条件

  • 稼働中の Red Hat Ceph Storage クラスターがある。
  • RESTful クライアント。

4.5.2. Swift コンテナー操作

コンテナーは、データオブジェクトを格納するメカニズムです。アカウントには多くのコンテナーを持たせることができますが、コンテナー名は一意でなければなりません。この API により、クライアントはコンテナーの作成、アクセス制御およびメタデータの設定、コンテナーのコンテンツの取得、およびコンテナーの削除を行うことができます。この API は特定のユーザーのアカウントの情報に関連するリクエストを行うため、コンテナーのアクセス制御が意図的に公開されていない限り、つまり匿名のリクエストを許可しない限り、この API のすべてのリクエストを認証する必要があります。

注記

Amazon S3 API はバケットという用語を使用してデータコンテナーを記述します。Swift API 内のバケットを参照すると、バケットという用語はコンテナーという用語と同じものになります。

オブジェクトストレージの 1 つは、階層パスやディレクトリーをサポートしないことです。代わりに、各コンテナーにオブジェクトがある 1 つ以上のコンテナーで設定される 1 つのレベルをサポートします。RADOS Gateway の Swift 互換 API は、疑似階層コンテナーの概念をサポートします。これは、オブジェクトの命名を使用してコンテナーをエミュレートする手段で、ストレージシステムで実際には実装されません。たとえば、photos/buildings/empire-state.jpg のように、疑似階層名でオブジェクトに名前を付けることができますが、コンテナー名にスラッシュ (/) 文字を含めることはできません。

重要

バージョン付けされた Swift コンテナーに大規模なオブジェクトをアップロードする場合は、python-swiftclient ユーティリティーで --leave-segments オプションを使用します。--leave-segments を使用しないと、マニフェストファイルが上書きされます。したがって、既存のオブジェクトは上書きされ、データが失われることになります。

4.5.3. Swift でコンテナーのアクセス制御リスト (ACL) の更新

ユーザーがコンテナーを作成すると、ユーザーはデフォルトでコンテナーへの読み取り/書き込みアクセスを持ちます。その他のユーザーがコンテナーのコンテンツを読み取りしたり、コンテナーに書き込むことを許可するには、ユーザーを明示的に有効にする必要があります。X-Container-Read または X-Container-Write* を指定することもできます。これにより、すべてのユーザーがコンテナーから読み取るか、またはコンテナーへの書き込みが可能になります。* を設定すると、コンテナーが公開されます。これにより、匿名ユーザーがコンテナーから読み込むか、またはコンテナーに書き込むことができます。

構文

POST /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN
X-Container-Read: *
X-Container-Write: UID1, UID2, UID3

リクエストヘッダー

X-Container-Read
詳細
コンテナーの読み取りパーミッションを持つユーザー ID。
ユーザー ID のコンマ区切りの文字列値。
必須
いいえ
X-Container-Write
詳細
コンテナーの書き込みパーミッションを持つユーザー ID。
ユーザー ID のコンマ区切りの文字列値。
必須
いいえ

4.5.4. Swift 一覧コンテナー

API バージョンを指定し、アカウントは特定のユーザーアカウントのコンテナーの一覧を返す GET リクエスト。リクエストは特定のユーザーのコンテナーを返すため、リクエストには認証トークンが必要です。リクエストは匿名で行われません。

構文

GET /API_VERSION/ACCOUNT HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN

リクエストパラメーター

limit
詳細
結果の数を指定の値に制限します。
Integer
有効な値
該当なし
必須
はい
format
詳細
結果の数を指定の値に制限します。
Integer
有効な値
json または xml
必須
いいえ
marker
詳細
マーカー値よりも大きな結果の一覧を返します。
String
有効な値
該当なし
必須
いいえ

応答にはコンテナーの一覧が含まれるか、または 204 応答コードで返されます。

レスポンスエンティティー

アカウント
詳細
アカウント情報の一覧。
Container
コンテナー
詳細
コンテナーの一覧。
Container
name
詳細
コンテナーの名前。
String
bytes
詳細
コンテナーのサイズ。
Integer

4.5.5. Swift でコンテナーオブジェクトの一覧表示

コンテナー内のオブジェクトを一覧表示するには、API バージョン、アカウント、およびコンテナーの名前を使用して GET リクエストを行います。クエリーパラメーターを指定して完全なリストをフィルターリングしたり、パラメーターを除外してコンテナーに保存されている最初の 10,000 オブジェクト名の一覧を返すこともできます。

構文

GET /API_VERSION/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN

リクエストパラメーター

format
詳細
結果の数を指定の値に制限します。
Integer
有効な値
json または xml
必須
いいえ
prefix
詳細
結果を、指定した接頭辞で始まるオブジェクトに制限します。
String
有効な値
該当なし
必須
いいえ
marker
詳細
マーカー値よりも大きな結果の一覧を返します。
String
有効な値
該当なし
必須
いいえ
limit
詳細
結果の数を指定の値に制限します。
Integer
有効な値
0 - 10,000
必須
いいえ
delimiter
詳細
接頭辞と他のオブジェクト名の間に挿入される区切り文字。
String
有効な値
該当なし
必須
いいえ
path
詳細
オブジェクトの擬似階層パス。
String
有効な値
該当なし
必須
いいえ

レスポンスエンティティー

コンテナー
詳細
コンテナー
Container
object
詳細
コンテナー内のオブジェクト。
Container
name
詳細
コンテナー内のオブジェクトの名前。
String
ハッシュ
詳細
オブジェクトのコンテンツのハッシュコード。
String
last_modified
詳細
オブジェクトの内容を最後に変更した時間。
Date
content_type
詳細
オブジェクト内のコンテンツのタイプ。
String

4.5.6. Swift でコンテナーの作成

新規コンテナーを作成するには、API バージョン、アカウント、および新規コンテナーの名前で PUT 要求を行います。コンテナー名は一意である必要があります。スラッシュ ( /) を含めることはできず、256 バイト未満でなければなりません。リクエストには、アクセス制御ヘッダーおよびメタデータヘッダーを含めることができます。一連の配置プールのキーを特定するストレージポリシーを含めることもできます。たとえば、radosgw-admin zone get を実行すると、placement_pools で利用可能なキーの一覧を確認します。ストレージポリシーを使用すると、SSD ベースのストレージなど、コンテナーの特別なプールセットを指定できます。操作には、べき等性があります。既存のコンテナーを作成するように要求すると、HTTP 202 戻りコードが返されますが、別のコンテナーは作成されません。

構文

PUT /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN
X-Container-Read: COMMA_SEPARATED_UIDS
X-Container-Write: COMMA_SEPARATED_UIDS
X-Container-Meta-KEY:VALUE
X-Storage-Policy: PLACEMENT_POOLS_KEY

ヘッダー

X-Container-Read
詳細
コンテナーの読み取りパーミッションを持つユーザー ID。
ユーザー ID のコンマ区切りの文字列値。
必須
いいえ
X-Container-Write
詳細
コンテナーの書き込みパーミッションを持つユーザー ID。
ユーザー ID のコンマ区切りの文字列値。
必須
いいえ
X-Container-Meta-KEY
詳細
任意の文字列の値を取得するユーザー定義のメタデータキー。
String
必須
いいえ
X-Storage-Policy
詳細
Ceph Object Gateway の placement_pools 下にあるストレージポリシーを識別するキー。radosgw-admin zone get を実行し、利用可能なキーを取得します。
String
必須
いいえ

同じ名前のコンテナーがすでに存在し、ユーザーがコンテナー所有者である場合、操作は成功します。そうでないと、操作は失敗します。

HTTP レスポンス

409
ステータスコード
BucketAlreadyExists
詳細
コンテナーは、別のユーザーの所有権にすでに存在します。

4.5.7. Swift コンテナーの削除

コンテナーを削除するには、API バージョン、アカウント、およびコンテナーの名前を使用して DELETE 要求を行います。コンテナーは空である必要があります。コンテナーが空であるかを確認する場合は、コンテナーに対して HEAD リクエストを実行します。コンテナーが正常に削除されると、コンテナー名を再利用できます。

構文

DELETE /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN

HTTP レスポンス

204
ステータスコード
NoContent
詳細
コンテナーが削除されました。

4.5.8. Swift がコンテナーのメタデータを追加または更新

コンテナーにメタデータを追加するには、API バージョン、アカウント、およびコンテナー名で POST 要求を行います。メタデータを追加または更新するには、コンテナーに対する書き込み権限が必要です。

構文

POST /API_VERSION/ACCOUNT/TENANT:CONTAINER HTTP/1.1
Host: FULLY_QUALIFIED_DOMAIN_NAME
X-Auth-Token: AUTH_TOKEN
X-Container-Meta-Color: red
X-Container-Meta-Taste: salty

リクエストヘッダー

X-Container-Meta-KEY
詳細
任意の文字列の値を取得するユーザー定義のメタデータキー。
String
必須
いいえ