2.5. S3 オブジェクト操作

開発者は、Ceph Object Gateway 経由で Amazon S3 アプリケーションプログラミングインターフェイス (API) を使用してオブジェクト操作を行うことができます。

以下の表は、関数のサポートステータスとともに、オブジェクトの Amazon S3 の機能操作を示しています。

表2.20 オブジェクト操作
Get Object	サポート対象
Get Object Information	サポート対象
Put Object	サポート対象
Delete Object	サポート対象
Delete Multiple Objects	サポート対象
Get Object ACLs	サポート対象
Put Object ACLs	サポート対象
Copy Object	サポート対象
Post Object	サポート対象
Options Object	サポート対象
Initiate Multipart Upload	サポート対象
Add a Part to a Multipart Upload	サポート対象
List Parts of a Multipart Upload	サポート対象
Assemble Multipart Upload	サポート対象
Copy Multipart Upload	サポート対象
Abort Multipart Upload	サポート対象
マルチテナンシー	サポート対象

2.5.1. 前提条件

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

2.5.2. S3 get an object from a bucket

バケットからオブジェクトを取得します。

構文

GET /BUCKET/OBJECT HTTP/1.1

versionId サブリソースを追加して、オブジェクトの特定のバージョンを取得します。

構文

GET /BUCKET/OBJECT?versionId=VERSION_ID HTTP/1.1

表2.21 リクエストヘッダー
Name	説明	有効な値	必須
範囲	取得するオブジェクトの範囲。	範囲: bytes=beginbyte-endbyte	No
if-modified-since	タイムスタンプ以降に変更した場合にのみ取得します。	タイムスタンプ	No
if-unmodified-since	タイムスタンプ以降変更されていない場合にのみ取得します。	タイムスタンプ	No
if-match	オブジェクトの ETag が ETag と一致する場合にのみ取得します。	エンティティータグ	No
if-none-match	オブジェクトの ETag が ETag と一致する場合にのみ取得します。	エンティティータグ	No

表2.22 レスポンスヘッダー
Name	説明
Content-Range	データ範囲 (範囲ヘッダーフィールドがリクエストに指定された場合のみを返します)。
x-amz-version-id	バージョン ID または Null を返します。

2.5.3. S3 get information on an object

オブジェクトに関する情報を返します。この要求は Get Object 要求と同じヘッダー情報を返しますが、オブジェクトデータペイロードではなくメタデータのみが含まれます。

オブジェクトの現行バージョンを取得します。

構文

HEAD /BUCKET/OBJECT HTTP/1.1

versionId サブリソースを追加して、特定バージョンの情報を取得します。

構文

HEAD /BUCKET/OBJECT?versionId=VERSION_ID HTTP/1.1

表2.23 リクエストヘッダー
Name	説明	有効な値	必須
範囲	取得するオブジェクトの範囲。	範囲: bytes=beginbyte-endbyte	No
if-modified-since	タイムスタンプ以降に変更した場合にのみ取得します。	タイムスタンプ	No
if-unmodified-since	タイムスタンプ以降変更されていない場合にのみ取得します。	タイムスタンプ	No
if-match	オブジェクトの ETag が ETag と一致する場合にのみ取得します。	エンティティータグ	No
if-none-match	オブジェクトの ETag が ETag と一致する場合にのみ取得します。	エンティティータグ	No

表2.24 レスポンスヘッダー
Name	説明
x-amz-version-id	バージョン ID または Null を返します。

2.5.4. S3 によりオブジェクトをバケットに追加

オブジェクトをバケットに追加します。この操作を実行するには、バケットに書き込みパーミッションが必要です。

構文

PUT /BUCKET/OBJECT HTTP/1.1

表2.25 リクエストヘッダー
Name	説明	有効な値	必須
content-md5	メッセージの base64 でエンコードされた MD-5 ハッシュ	文字列。デフォルトや制約はありません。	No
content-type	標準の MIME タイプ。	MIME タイプ。デフォルト: `binary/octet-stream`	いいえ
x-amz-meta-<…>	ユーザーのメタデータ。オブジェクトとともに保存されます。	8kb までの文字列。デフォルトはありません。	No
x-amz-acl	固定 ACL。	`private`、`public-read`、`public-read-write`、`authenticated-read`	いいえ

表2.26 レスポンスヘッダー
Name	説明
x-amz-version-id	バージョン ID または Null を返します。

2.5.5. S3 delete an object

オブジェクトを削除します。含まれるバケットに WRITE パーミッションを設定する必要があります。

オブジェクトを削除します。オブジェクトのバージョン管理が有効なの場合、マーカーが作成されます。

構文

DELETE /BUCKET/OBJECT HTTP/1.1

バージョン管理が有効な場合にオブジェクトを削除するには、versionId サブリソースおよび削除するオブジェクトのバージョンを指定する必要があります。

DELETE /BUCKET/OBJECT?versionId=VERSION_ID HTTP/1.1

2.5.6. S3 delete multiple objects

この API 呼び出しは、バケットから複数のオブジェクトを削除します。

構文

POST /BUCKET/OBJECT?delete HTTP/1.1

2.5.7. S3 get an object's Access Control List (ACL)

オブジェクトの現行バージョンの ACL を返します。

構文

GET /BUCKET/OBJECT?acl HTTP/1.1

versionId サブリソースを追加して、特定バージョンの ACL を取得します。

構文

GET /BUCKET/OBJECT?versionId=VERSION_ID&acl HTTP/1.1

表2.27 レスポンスヘッダー
Name	説明
x-amz-version-id	バージョン ID または Null を返します。

表2.28 レスポンスエンティティー
Name	型	詳細
`AccessControlPolicy`	コンテナー	レスポンスのコンテナー。
`AccessControlList`	コンテナー	ACL 情報用のコンテナー
`Owner`	コンテナー	オブジェクトの所有者の `ID` および `DisplayName` のコンテナー。
`ID`	文字列	オブジェクトの所有者の ID。
`DisplayName`	文字列	オブジェクトの所有者の表示名。
`Grant`	コンテナー	`Grantee` および `Permission` のコンテナー。
`Grantee`	コンテナー	パーミッションを付与されるユーザーの `DisplayName` および `ID` のコンテナー。
`Permission`	文字列	`Grantee` オブジェクトに指定されたパーミッション。

2.5.8. S3 によりオブジェクトのアクセス制御リスト (ACL) の設定

オブジェクトの現行バージョンのオブジェクト ACL を設定します。

構文

PUT /BUCKET/OBJECT?acl

表2.29 リクエストエンティティー
Name	型	詳細
`AccessControlPolicy`	コンテナー	レスポンスのコンテナー。
`AccessControlList`	コンテナー	ACL 情報用のコンテナー
`Owner`	コンテナー	オブジェクトの所有者の `ID` および `DisplayName` のコンテナー。
`ID`	文字列	オブジェクトの所有者の ID。
`DisplayName`	文字列	オブジェクトの所有者の表示名。
`Grant`	コンテナー	`Grantee` および `Permission` のコンテナー。
`Grantee`	コンテナー	パーミッションを付与されるユーザーの `DisplayName` および `ID` のコンテナー。
`Permission`	文字列	`Grantee` オブジェクトに指定されたパーミッション。

2.5.9. S3 によるオブジェクトのコピー

オブジェクトをコピーするには、PUT を使用して宛先バケットとオブジェクト名を指定します。

構文

PUT /DEST_BUCKET/DEST_OBJECT HTTP/1.1
x-amz-copy-source: SOURCE_BUCKET/SOURCE_OBJECT

表2.30 リクエストヘッダー
Name	説明	有効な値	必須
x-amz-copy-source	ソースバケット名 + オブジェクト名。	BUCKET/OBJECT	はい
x-amz-acl	固定 ACL。	`private`、`public-read`、`public-read-write`、`authenticated-read`	いいえ
x-amz-copy-if-modified-since	タイムスタンプ以降に変更された場合のみコピーします。	タイムスタンプ	No
x-amz-copy-if-unmodified-since	タイムスタンプ以降変更されていない場合にのみコピーします。	タイムスタンプ	No
x-amz-copy-if-match	オブジェクトの ETag が ETag と一致する場合に限りコピーします。	エンティティータグ	No
x-amz-copy-if-none-match	オブジェクトの ETag が一致しない場合にのみコピーします。	エンティティータグ	No

表2.31 レスポンスエンティティー
Name	型	説明
CopyObjectResult	コンテナー	レスポンス要素のコンテナー。
LastModified	Date	ソースオブジェクトを最後に変更した日付。
Etag	文字列	新規オブジェクトの ETag。

関連情報

<additional resource 1>
<additional resource 2>

2.5.10. S3 により HTML フォームを使用してオブジェクトをバケットに追加

HTML フォームを使用してオブジェクトをバケットに追加します。この操作を実行するには、バケットに書き込みパーミッションが必要です。

構文

POST /BUCKET/OBJECT HTTP/1.1

2.5.11. S3 determine options for a request

特定の送信元、HTTP メソッド、およびヘッダーを使用して実際のリクエストを送信できるかどうかを判断するための事前要求です。

構文

OPTIONS /OBJECT HTTP/1.1

2.5.12. S3 initiate a multipart upload

複数パートからなるアップロードプロセスを開始します。追加部分の追加、パーツの一覧表示、および複数パートアップロードの完了または破棄時に指定できる UploadId を返します。

構文

POST /BUCKET/OBJECT?uploads

表2.32 リクエストヘッダー
Name	説明	有効な値	必須
`content-md5`	メッセージの base64 でエンコードされた MD-5 ハッシュ	文字列。デフォルトや制約はありません。	No
`content-type`	標準の MIME タイプ。	MIME タイプ。デフォルト: `binary/octet-stream`	いいえ
`x-amz-meta-<…>`	ユーザーのメタデータ。オブジェクトとともに保存されます。	8kb までの文字列。デフォルトはありません。	No
`x-amz-acl`	固定 ACL。	`private`、`public-read`、`public-read-write`、`authenticated-read`	いいえ

表2.33 レスポンスエンティティー
Name	型	詳細
`InitiatedMultipartUploadsResult`	コンテナー	結果のコンテナー
`Bucket`	文字列	オブジェクトの内容を受け取るバケット。
`Key`	文字列	`key` リクエストパラメーターで指定されるキー (存在する場合)。
`UploadId`	文字列	`upload-id` リクエストパラメーターで指定される ID で、マルチパートアップロードを特定します (存在する場合)。

2.5.13. S3 がマルチパートアップロードに部分を追加

マルチパートアップロードに部分を追加します。

複数パートのアップロードに部分を追加するために uploadId サブリソースとアップロード ID を指定します。

構文

PUT /BUCKET/OBJECT?partNumber=&uploadId=UPLOAD_ID HTTP/1.1

以下の HTTP レスポンスが返されます。

表2.34 HTTP レスポンス
HTTP ステータス	ステータスコード	詳細
`404`	NoSuchUpload	指定した upload-id がこのオブジェクトで開始されたアップロードと一致しません。

2.5.14. S3 でマルチパートアップロードの一部が一覧表示されます。

マルチパートアップロードの一部を一覧表示するために uploadId サブリソースとアップロード ID を指定します。

構文

GET /BUCKET/OBJECT?uploadId=UPLOAD_ID HTTP/1.1

表2.35 レスポンスエンティティー
Name	型	詳細
`InitiatedMultipartUploadsResult`	コンテナー	結果のコンテナー
`Bucket`	文字列	オブジェクトの内容を受け取るバケット。
`Key`	文字列	`key` リクエストパラメーターで指定されるキー (存在する場合)。
`UploadId`	文字列	`upload-id` リクエストパラメーターで指定される ID で、マルチパートアップロードを特定します (存在する場合)。
`Initiator`	コンテナー	アップロードを開始したユーザーの `ID` と `DisplayName` が含まれます。
`ID`	文字列	イニシエーターの ID。
`DisplayName`	文字列	イニシエーターの表示名。
`Owner`	コンテナー	アップロードしたオブジェクトを所有するユーザーの `ID` および `DisplayName` のコンテナー。
`StorageClass`	文字列	作成されるオブジェクトを保存するために使用されるメソッド。`STANDARD` または `REDUCED_REDUNDANCY`
`PartNumberMarker`	文字列	`IsTruncated` が `true` の場合に後続のリクエストで使用する部分マーカー。一覧の先頭に指定します。
`NextPartNumberMarker`	文字列	`IsTruncated` が `true` の場合は、後続のリクエストで使用する次の部分マーカー。リストの末尾。
`MaxParts`	整数	`max-parts` リクエストパラメーターで指定されたレスポンスで許可される最大部分。
`IsTruncated`	ブール値	`true` の場合は、オブジェクトのアップロードコンテンツのサブセットのみが返されます。
`Part`	コンテナー	`Key`、`Part`、`InitiatorOwner`、`StorageClass`、および `Initiated` 要素のコンテナー。
`PartNumber`	整数	部分の識別番号。
`ETag`	文字列	コンポーネントのエンティティータグです。
`サイズ`	整数	アップロードした部分のサイズ。

2.5.15. S3 アップロードした部分のアセンブル

アップロードした部分を組み立て、新規オブジェクトを作成します。これにより、複数パートのアップロードが実行されます。

複数パートからなるアップロードを完了するには、uploadId サブリソースとアップロード ID を指定します。

構文

POST /BUCKET/OBJECT?uploadId=UPLOAD_ID HTTP/1.1

表2.36 リクエストエンティティー
Name	型	説明	必須
`CompleteMultipartUpload`	コンテナー	1 つ以上の部分で設定されるコンテナー。	はい
`Part`	コンテナー	`PartNumber` および `ETag` のコンテナー。	はい
`PartNumber`	整数	部分の識別子。	はい
`ETag`	文字列	コンポーネントのエンティティータグです。	Yes

表2.37 レスポンスエンティティー
Name	型	詳細
`CompleteMultipartUploadResult`	コンテナー	レスポンスのコンテナー。
`場所`	URI	新規オブジェクトのリソース識別子 (パス)。
`Bucket`	文字列	新規オブジェクトが含まれるバケットの名前。
`Key`	文字列	オブジェクトのキー。
`ETag`	文字列	新規オブジェクトのエンティティータグ。

2.5.16. S3 によるマルチパートのアップロード

既存のオブジェクトからデータをデータソースとしてコピーして、パーツをアップロードします。

複数パートからなるアップロードコピーを実行するには、uploadId サブリソースとアップロード ID を指定します。

構文

PUT /BUCKET/OBJECT?partNumber=PartNumber&uploadId=UPLOAD_ID HTTP/1.1
Host: cname.domain.com

Authorization: AWS ACCESS_KEY:HASH_OF_HEADER_AND_SECRET

表2.38 リクエストヘッダー
Name	説明	有効な値	必須
`x-amz-copy-source`	ソースバケット名およびオブジェクト名。	BUCKET/OBJECT	はい
`x-amz-copy-source-range`	ソースオブジェクトからコピーするバイトの範囲。	範囲: `bytes=first-last` (ここで、最初のおよび最後は、コピーするゼロベースのバイトオフセットです)たとえば、`bytes=0-9` は、ソースの最初の 10 バイトをコピーすることを示しています。	いいえ

表2.39 レスポンスエンティティー
Name	型	詳細
`CopyPartResult`	コンテナー	すべてのレスポンス要素のコンテナー。
`ETag`	文字列	新しい部分の ETag を返します。
`LastModified`	文字列	最後に変更した日付を返します。

.Additional Resources

この機能の詳細は、Amazon S3 のサイト を参照してください。

2.5.17. S3 abort a multipart upload

複数パートアップロードを中止します。

マルチパートによるアップロードを中止するために uploadId サブリソースとアップロード ID を指定します。

構文

DELETE /BUCKET/OBJECT?uploadId=UPLOAD_ID HTTP/1.1

2.5.18. S3 Hadoop interoperability

HDFS (Hadoop Distributed File System) のアクセスを必要とするデータ解析アプリケーションは、Hadoop 用の Apache S3A コネクターを使用して Ceph Object Gateway にアクセスできます。S3A コネクターは、データが Ceph Object Gateway に保存される一方で、HDFS ファイルシステムがアプリケーションへのセマンティクスを読み取りおよび書き込みする S3 互換のオブジェクトストレージを HDFS ファイルシステムとして表示するオープンソースツールです。

Ceph Object Gateway は、Hadoop 2.7.3 に同梱される S3A コネクターと完全に互換性があります。

2.5.19. 関連情報

マルチテナンシーの詳細は、Red Hat Ceph Storage Object Gateway 設定および管理ガイド を参照してください。