3.5. S3 オブジェクト操作

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

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

表3.3 オブジェクト操作

機能状態

Get Object

サポート対象

Get Object Information

サポート対象

Put Object Lock

サポート対象

Get Object Lock

サポート対象

Put Object Legal Hold

サポート対象

Get Object Legal Hold

サポート対象

Put Object Retention

サポート対象

Get Object Retention

サポート対象

Put Object Tagging

サポート対象

Get Object Tagging

サポート対象

Delete Object Tagging

サポート対象

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

サポート対象

マルチテナンシー

サポート対象

3.5.1. 前提条件

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

3.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

リクエストヘッダー

range
詳細
取得するオブジェクトの範囲。
有効な値
範囲: bytes=beginbyte-endbyte
必須
いいえ
if-modified-since
詳細
タイムスタンプ以降に変更した場合にのみ取得します。
有効な値
Timestamp
必須
いいえ
if-match
詳細
オブジェクトの ETag が ETag と一致する場合にのみ取得します。
有効な値
エンティティータグ
必須
いいえ
if-none-match
詳細
オブジェクトの ETag が ETag と一致する場合にのみ取得します。
有効な値
エンティティータグ
必須
いいえ

レスポンスヘッダー

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

3.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

リクエストヘッダー

range
詳細
取得するオブジェクトの範囲。
有効な値
範囲: bytes=beginbyte-endbyte
必須
いいえ
if-modified-since
詳細
タイムスタンプ以降に変更した場合にのみ取得します。
有効な値
Timestamp
必須
いいえ
if-match
詳細
オブジェクトの ETag が ETag と一致する場合にのみ取得します。
有効な値
エンティティータグ
必須
いいえ
if-none-match
詳細
オブジェクトの ETag が ETag と一致する場合にのみ取得します。
有効な値
エンティティータグ
必須
いいえ

レスポンスヘッダー

x-amz-version-id
詳細
バージョン ID または Null を返します。

3.5.4. S3 put object lock

put object lock API は、選択したバケットにロック設定を配置します。オブジェクトロックを使用すると、write-once-read-many(WORM) モデルを使用してオブジェクトを格納できます。オブジェクトロックは、オブジェクトが一定期間または無期限に削除または上書きされないようにします。Object Lock 設定に指定されるルールは、デフォルトで選択されるバケットにあるすべての新規オブジェクトに適用されます。

重要

バケットを作成するときにオブジェクトロックを有効にします。有効にしないと、操作が失敗します。

構文

PUT /BUCKET?object-lock HTTP/1.1

PUT /testbucket?object-lock HTTP/1.1

リクエストエンティティー

ObjectLockConfiguration
詳細
要求のコンテナー。
Container
必須
はい
ObjectLockEnabled
詳細
このバケットにオブジェクトロック設定が有効になっているかどうかを示します。
String
必須
はい
**ルール**
詳細
指定されたバケットの位置にあるオブジェクトロックルール。
Container
必須
いいえ
DefaultRetention
詳細
指定されたバケットに設定される新規オブジェクトに適用されるデフォルトの保持期間。
Container
必須
いいえ
Mode
詳細
デフォルトのオブジェクトのロック保持モード。有効な値は GOVERNANCE/COMPLIANCE です。
Container
必須
はい
Days
詳細
デフォルトの保持期間に指定される日数。
整数
必須
いいえ
Years
詳細
デフォルトの保持期間に指定されるの年数。
整数
必須
いいえ

HTTP レスポンス

400
ステータスコード
MalformedXML
詳細
XML は適していません。
409
ステータスコード
InvalidBucketState
詳細
バケットオブジェクトのロックが有効になっていません。

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.5. S3 get object lock

get object lock API は、バケットのロック設定を取得します。

構文

GET /BUCKET?object-lock HTTP/1.1

GET /testbucket?object-lock HTTP/1.1

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

ObjectLockConfiguration
詳細
要求のコンテナー。
Container
必須
はい
ObjectLockEnabled
詳細
このバケットにオブジェクトロック設定が有効になっているかどうかを示します。
String
必須
はい
**ルール**
説明
指定されたバケットの位置に、オブジェクトロックルールがあります。
Container
必須
いいえ
DefaultRetention
詳細
指定されたバケットに設定される新規オブジェクトに適用されるデフォルトの保持期間。
Container
必須
いいえ
Mode
詳細
デフォルトのオブジェクトのロック保持モード。有効な値は GOVERNANCE/COMPLIANCE です。
Container
必須
はい
Days
詳細
デフォルトの保持期間に指定される日数。
整数
必須
いいえ
Years
詳細
デフォルトの保持期間に指定されるの年数。
整数
必須
いいえ

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.8. S3 put object retention

put object retention API は、オブジェクトの保持設定をオブジェクトに配置します。保持期間は、オブジェクトのバージョンを一定時間保護します。ガバナンスモードとコンプライアンスモードの 2 つのモードがあります。これら 2 つの保持モードは、オブジェクトに対して異なる保護レベルを適用します。

注記

この期間中、オブジェクトは write-once-read-many(WORM 保護) で、上書きまたは削除することはできません。

構文

PUT /BUCKET/OBJECT?retention&versionId= HTTP/1.1

PUT /testbucket/testobject?retention&versionId= HTTP/1.1

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

リクエストエンティティー

Retention
詳細
要求のコンテナー。
Container
必須
はい
Mode
詳細
指定されたオブジェクトの保持モード。有効な値: GOVERNANCE/COMPLIANCE
String
必須
はい
RetainUntilDate
詳細
保持日。形式: 2020-01-05T00:00:00.000Z
Timestamp
必須
はい

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.9. S3 get object retention

get object retention API は、オブジェクト上でオブジェクトの保持設定を取得します。

構文

GET /BUCKET/OBJECT?retention&versionId= HTTP/1.1

GET /testbucket/testobject?retention&versionId= HTTP/1.1

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

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

Retention
詳細
要求のコンテナー。
Container
必須
はい
Mode
詳細
指定されたオブジェクトの保持モード。有効な値: GOVERNANCE/COMPLIANCE
String
必須
はい
RetainUntilDate
詳細
保持日。形式: 2020-01-05T00:00:00.000Z
Timestamp
必須
はい

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.10. S3 put object tagging

put object tagging API は、タグをオブジェクトに関連付けます。タグはキーと値のペアです。他のバージョンのタグを配置するには、versionId クエリーパラメーターを使用します。s3:PutObjectTagging アクションを実行するパーミッションが必要です。デフォルトでは、バケットの所有者はこのパーミッションを持ち、このパーミッションを他のユーザーに付与できます。

構文

PUT /BUCKET/OBJECT?tagging&versionId= HTTP/1.1

PUT /testbucket/testobject?tagging&versionId= HTTP/1.1

リクエストエンティティー

タグ付け
詳細
要求のコンテナー。
Container
必須
はい
TagSet
詳細
タグのセットのコレクションです。
String
必須
はい

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.11. S3 get object tagging

get object tagging API は、オブジェクトのタグを返します。デフォルトでは、GET 操作はオブジェクトの現行バージョンについての情報を返します。

注記

バージョン付けされたバケットの場合は、バケットに複数のバージョンのオブジェクトを使用できます。他のバージョンのタグを取得するには、要求に versionId クエリーパラメーターを追加します。

構文

GET /BUCKET/OBJECT?tagging&versionId= HTTP/1.1

GET /testbucket/testobject?tagging&versionId= HTTP/1.1

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.12. S3 delete object tagging

delete object tagging API は、指定されたオブジェクトから設定されたタグ全体を削除します。この操作を使用するには、s3:DeleteObjectTagging アクションを実行するパーミッションが必要です。

注記

特定のオブジェクトバージョンのタグを削除するには、リクエストに versionId クエリーパラメーターを追加します。

構文

DELETE /BUCKET/OBJECT?tagging&versionId= HTTP/1.1

DELETE /testbucket/testobject?tagging&versionId= HTTP/1.1

関連情報

  • この API 呼び出しの詳細は、S3 API を参照してください。

3.5.13. S3 add an object to a bucket

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

構文

PUT /BUCKET/OBJECT HTTP/1.1

リクエストヘッダー

content-md5
詳細
メッセージの base64 でエンコードされた MD-5 ハッシュ
有効な値
文字列。デフォルトや制約はありません。
必須
いいえ
content-type
詳細
標準の MIME タイプ。
有効な値
MIME タイプ。デフォルト: binary/octet-stream
必須
いいえ
x-amz-meta-<…​>*
詳細
ユーザーのメタデータ。オブジェクトとともに保存されます。
有効な値
8kb までの文字列。デフォルトはありません。
必須
いいえ
x-amz-acl
詳細
固定 ACL。
有効な値
privatepublic-readpublic-read-writeauthenticated-read
必須
いいえ

レスポンスヘッダー

x-amz-version-id
詳細
バージョン ID または Null を返します。

3.5.14. S3 delete an object

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

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

構文

DELETE /BUCKET/OBJECT HTTP/1.1

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

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

3.5.15. S3 delete multiple objects

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

構文

POST /BUCKET/OBJECT?delete HTTP/1.1

3.5.16. 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

レスポンスヘッダー

x-amz-version-id
詳細
バージョン ID または Null を返します。

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

AccessControlPolicy
詳細
応答のコンテナー。
Container
AccessControlList
詳細
ACL 情報用のコンテナー
Container
Owner
詳細
バケット所有者の ID および DisplayName のコンテナー。
Container
ID
詳細
バケット所有者の ID。
String
DisplayName
詳細
バケットの所有者の表示名。
String
Grant
詳細
Grantee および Permission のコンテナー。
Container
Grantee
詳細
パーミッションを付与されるユーザーの DisplayName および ID のコンテナー。
Container
パーミッション
詳細
Grantee バケットに指定されるパーミッション。
String

3.5.17. S3 set an object's Access Control List (ACL)

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

構文

PUT /BUCKET/OBJECT?acl

リクエストエンティティー

AccessControlPolicy
詳細
応答のコンテナー。
Container
AccessControlList
詳細
ACL 情報用のコンテナー
Container
Owner
詳細
バケット所有者の ID および DisplayName のコンテナー。
Container
ID
詳細
バケット所有者の ID。
String
DisplayName
詳細
バケットの所有者の表示名。
String
Grant
詳細
Grantee および Permission のコンテナー。
Container
Grantee
詳細
パーミッションを付与されるユーザーの DisplayName および ID のコンテナー。
Container
パーミッション
詳細
Grantee バケットに指定されるパーミッション。
String

3.5.18. S3 copy an object

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

構文

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

リクエストヘッダー

x-amz-copy-source
詳細
ソースバケット名 + オブジェクト名。
有効な値
BUCKET/OBJECT
必須
はい
x-amz-acl
詳細
固定 ACL。
有効な値
privatepublic-readpublic-read-writeauthenticated-read
必須
いいえ
x-amz-copy-if-modified-since
詳細
タイムスタンプ以降に変更された場合のみコピーします。
有効な値
Timestamp
必須
いいえ
x-amz-copy-if-unmodified-since
詳細
タイムスタンプ以降変更されていない場合にのみコピーします。
有効な値
Timestamp
必須
いいえ
x-amz-copy-if-match
詳細
オブジェクトの ETag が ETag と一致する場合に限りコピーします。
有効な値
エンティティータグ
必須
いいえ
x-amz-copy-if-none-match
詳細
オブジェクトの ETag が ETag と一致する場合に限りコピーします。
有効な値
エンティティータグ
必須
いいえ

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

CopyObjectResult
詳細
レスポンス要素のコンテナー。
Container
LastModified
詳細
ソースオブジェクトを最後に変更した日付。
Date
Etag
詳細
新規オブジェクトの ETag。
String

3.5.19. S3 add an object to a bucket using HTML forms

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

構文

POST /BUCKET/OBJECT HTTP/1.1

3.5.20. S3 determine options for a request

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

構文

OPTIONS /OBJECT HTTP/1.1

3.5.21. S3 initiate a multipart upload

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

構文

POST /BUCKET/OBJECT?uploads

リクエストヘッダー

content-md5
詳細
メッセージの base64 でエンコードされた MD-5 ハッシュ
有効な値
文字列。デフォルトや制約はありません。
必須
いいえ
content-type
詳細
標準の MIME タイプ。
有効な値
MIME タイプ。デフォルト: binary/octet-stream
必須
いいえ
x-amz-meta-<…​>
詳細
ユーザーのメタデータ。オブジェクトとともに保存されます。
有効な値
8kb までの文字列。デフォルトはありません。
必須
いいえ
x-amz-acl
詳細
固定 ACL。
有効な値
privatepublic-readpublic-read-writeauthenticated-read
必須
いいえ

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

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

3.5.22. S3 add a part to a multipart upload

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

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

構文

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

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

HTTP レスポンス

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

3.5.23. S3 list the parts of a multipart upload

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

構文

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

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

InitiatedMultipartUploadsResult
詳細
結果のコンテナー
Container
Bucket
詳細
オブジェクトの内容を受け取るバケット。
String
キー
詳細
key リクエストパラメーターで指定されるキー (存在する場合)。
String
UploadId
詳細
upload-id 要求パラメーターで指定される ID で、マルチパートアップロードを特定します (存在する場合)。
String
イニシエーター
詳細
アップロードを開始したユーザーの IDDisplayName が含まれます。
Container
ID
詳細
イニシエーターの ID。
String
DisplayName
詳細
イニシエーターの表示名。
String
Owner
詳細
アップロードしたオブジェクトを所有するユーザーの ID および DisplayName のコンテナー。
Container
StorageClass
詳細
作成されるオブジェクトを保存するために使用されるメソッド。STANDARD または REDUCED_REDUNDANCY
String
PartNumberMarker
詳細
IsTruncatedtrue の場合に後続のリクエストで使用する部分マーカー。一覧の先頭に指定します。
String
NextPartNumberMarker
詳細
IsTruncatedtrue の場合は、後続のリクエストで使用する次の部分マーカー。リストの末尾。
String
IsTruncated
詳細
true の場合は、オブジェクトのアップロードコンテンツのサブセットのみが返されます。
Boolean
部分
詳細
KeyPartInitiatorOwnerStorageClass、および Initiated 要素のコンテナー。
Container
PartNumber
詳細
KeyPartInitiatorOwnerStorageClass、および Initiated 要素のコンテナー。
Integer
ETag
詳細
コンポーネントのエンティティータグです。
String
サイズ
詳細
アップロードした部分のサイズ。
Integer

3.5.24. S3 assemble the uploaded parts

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

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

構文

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

リクエストエンティティー

CompleteMultipartUpload
詳細
1 つ以上の部分で設定されるコンテナー。
Container
必須
はい
部分
詳細
PartNumber および ETag のコンテナー。
Container
必須
はい
PartNumber
詳細
部分の識別子。
整数
必須
はい
ETag
詳細
コンポーネントのエンティティータグです。
String
必須
はい

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

CompleteMultipartUploadResult
詳細
応答のコンテナー。
Container
場所
詳細
新規オブジェクトのリソース識別子 (パス)。
URI
bucket
詳細
新規オブジェクトが含まれるバケットの名前。
String
キー
詳細
オブジェクトのキー。
String
ETag
詳細
新規オブジェクトのエンティティータグ。
String

3.5.25. S3 copy a multipart upload

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

複数パートからなるアップロードコピーを実行するには、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

リクエストヘッダー

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

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

CopyPartResult
詳細
すべてのレスポンス要素のコンテナー。
Container
ETag
詳細
新しい部分の ETag を返します。
String
LastModified
詳細
最後に変更した日付を返します。
String

関連情報

3.5.26. S3 abort a multipart upload

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

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

構文

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

3.5.27. 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 コネクターと完全に互換性があります。

3.5.28. 関連情報