3.5. Swift コンテナー操作

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

3.5.1. 前提条件

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

3.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 を使用しないと、マニフェストファイルが上書きされます。したがって、既存のオブジェクトは上書きされ、データが失われることになります。

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

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

構文

POST /AP_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

表3.2 リクエストヘッダー

Name説明必須

X-Container-Read

コンテナーの読み取りパーミッションを持つユーザー ID。

ユーザー ID のコンマ区切りの文字列値。

いいえ

X-Container-Write

コンテナーの書き込みパーミッションを持つユーザー ID。

ユーザー ID のコンマ区切りの文字列値。

No

3.5.4. Swift 一覧コンテナー

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

構文

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

表3.3 リクエストパラメーター

Name説明必須有効な値

limit

結果の数を指定の値に制限します。

整数

No

該当なし

format

結果の形式を定義します。

文字列

いいえ

json または xml

marker

マーカー値よりも大きな結果の一覧を返します。

文字列

No

該当なし

レスポンスにはコンテナーの一覧が含まれるか、HTTP 204 レスポンスコードで返されます。

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

Name説明

account

アカウント情報の一覧。

コンテナー

container

コンテナーの一覧。

コンテナー

name

コンテナーの名前。

文字列

bytes

コンテナーのサイズ。

整数

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

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

構文

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

表3.5 パラメーター

名前説明タイプ有効な値必須

format

結果の形式を定義します。

文字列

json または xml

いいえ

prefix

結果を、指定した接頭辞で始まるオブジェクトに制限します。

文字列

該当なし

いいえ

marker

マーカー値よりも大きな結果の一覧を返します。

文字列

該当なし

いいえ

limit

結果の数を指定の値に制限します。

整数

0 - 10,000

いいえ

delimiter

接頭辞と他のオブジェクト名の間に挿入される区切り文字。

文字列

該当なし

いいえ

path

オブジェクトの擬似階層パス。

文字列

該当なし

No

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

Name説明

container

コンテナー

コンテナー

object

コンテナー内のオブジェクト。

コンテナー

name

コンテナー内のオブジェクトの名前。

文字列

hash

オブジェクトのコンテンツのハッシュコード。

文字列

last_modified

オブジェクトの内容を最後に変更した時間。

Date

content_type

オブジェクト内のコンテンツのタイプ。

文字列

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

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

構文

PUT /AP_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

表3.7 ヘッダー

Name説明必須

X-Container-Read

コンテナーの読み取りパーミッションを持つユーザー ID。

ユーザー ID のコンマ区切りの文字列値。

いいえ

X-Container-Write

コンテナーの書き込みパーミッションを持つユーザー ID。

ユーザー ID のコンマ区切りの文字列値。

いいえ

X-Container-Meta-KEY

任意の文字列の値を取得するユーザー定義のメタデータキー。

文字列

いいえ

X-Storage-Policy

Ceph Object Gateway の placement_pools 下にあるストレージポリシーを識別するキー。radosgw-admin zone get を実行し、利用可能なキーを取得します。

文字列

No

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

表3.8 HTTP レスポンス

Name説明ステータスコード

409

コンテナーは、別のユーザーの所有権にすでに存在します。

BucketAlreadyExists

3.5.7. Swift コンテナーの削除

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

構文

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

表3.9 HTTP レスポンス

Name説明ステータスコード

204

コンテナーが削除されました。

NoContent

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

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

構文

POST /AP_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

表3.10 リクエストヘッダー

Name説明必須

X-Container-Meta-KEY

任意の文字列の値を取得するユーザー定義のメタデータキー。

文字列

No