4.4. Swift コンテナー操作
開発者は、Ceph Object Gateway 経由で Swift アプリケーションのプログラミングインターフェイス (API) を使用してコンテナーの操作を行うことができます。コンテナーをリスト表示、作成、更新、および削除できます。コンテナーのメタデータを追加または更新できます。
前提条件
- 稼働中の Red Hat Ceph Storage クラスターがある。
- RESTful クライアント。
4.4.1. 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.4.2. 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.4.3. 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- 説明
- コンテナーのリスト。
- 型
- コンテナー
name- 説明
- コンテナーの名前。
- 型
- String
bytes- 説明
- コンテナーのサイズ。
- 型
- Integer
4.4.4. 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- 説明
- コンテナー内のオブジェクト。
- 型
- コンテナー
name- 説明
- コンテナー内のオブジェクトの名前。
- 型
- String
ハッシュ- 説明
- オブジェクトのコンテンツのハッシュコード。
- 型
- String
last_modified- 説明
- オブジェクトの内容を最後に変更した時間。
- 型
- 日付
content_type- 説明
- オブジェクト内のコンテンツのタイプ。
- 型
- String
4.4.5. 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.4.6. 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.4.7. 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
- 必須
- いいえ
