範囲ダウンロードを使用して、オブジェクトから指定された範囲のデータをダウンロードできます。
使用上の注意
このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用しています。 OSS と同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用します。 OSS のリージョンとエンドポイントの詳細については、「OSS のリージョンとエンドポイント」をご参照ください。
このトピックでは、アクセス認証情報は環境変数から取得されます。 アクセス認証情報を設定する方法の詳細については、「OSS SDK for Python 1.0 を使用してアクセス認証情報を設定する」をご参照ください。
このトピックでは、OSS エンドポイントを使用して OSSClient インスタンスを作成します。 カスタムドメイン名または Security Token Service (STS) を使用して OSSClient インスタンスを作成する場合は、「初期化」をご参照ください。
範囲ダウンロードを実行するには、
oss:GetObject権限が必要です。 詳細については、「RAM ユーザーにカスタムポリシーをアタッチする」をご参照ください。
有効なダウンロード範囲を指定する
次のサンプルコードは、ファイルをダウンロードするための有効な範囲を指定する方法の例を示しています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# エンドポイントにマップするリージョンの ID を指定します。例: cn-hangzhou。署名アルゴリズム V4 を使用する場合は、このパラメーターが必要です。
region = "cn-hangzhou"
# バケットの名前を指定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# オブジェクトのサイズが 1,000 バイトの場合、有効な範囲はバイト 0 からバイト 999 です。
# バイト 0 からバイト 999 までの範囲内のデータ (合計 1,000 バイト) をクエリします。指定された値の範囲が無効な場合、オブジェクト全体がダウンロードされます。たとえば、指定された範囲の開始または終了が負の数である場合、または指定された値がオブジェクトサイズより大きい場合、オブジェクトのすべてのコンテンツがダウンロードされます。
object_stream = bucket.get_object('<yourObjectName>', byte_range=(0, 999))無効なダウンロード範囲を指定する
サイズが 1,000 バイトのオブジェクトがあるとします。有効なダウンロード範囲は 0 から 999 です。指定された範囲が無効な場合、Range ヘッダーは有効になりません。レスポンスは、HTTP ステータスコード 200 とオブジェクト全体のコンテンツを返します。次の表に、無効なリクエストとそのレスポンスを示します。
Range: bytes を 500 ～ 2000 に設定すると、範囲の終わりの値が無効になります。ファイル全体のコンテンツが返され、HTTP ステータスコードは 200 になります。
Range: bytes を 1000 ～ 2000 に設定すると、範囲の始まりの値が無効になります。ファイル全体のコンテンツが返され、HTTP ステータスコードは 200 になります。
標準の動作を指定して範囲ごとにデータをダウンロードする
指定された範囲が無効な場合に OSS のダウンロード動作を変更するには、x-oss-range-behavior:standard リクエストヘッダーを追加します。サイズが 1,000 バイトのオブジェクトがあるとします。
Range: bytes を 500 ～ 2000 に設定すると、範囲の終わりの値が無効になります。 500 ～ 999 バイトの範囲内のコンテンツが返され、HTTP ステータスコードは 206 になります。
Range: bytes を 1000 ～ 2000 に設定すると、範囲の始まりの値が無効になります。 HTTP ステータスコード 416 と InvalidRange エラーコードが返されます。
次のコードは、標準の動作に基づいて範囲ダウンロードを実行する方法の例を示しています。
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、OSS_ACCESS_KEY_ID および OSS_ACCESS_KEY_SECRET 環境変数が設定されていることを確認してください。
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())
# バケットが配置されているリージョンのエンドポイントを指定します。たとえば、バケットが中国 (杭州) リージョンにある場合は、エンドポイントを https://oss-cn-hangzhou.aliyuncs.com に設定します。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
# エンドポイントにマップするリージョンの ID を指定します。例: cn-hangzhou。署名アルゴリズム V4 を使用する場合は、このパラメーターが必要です。
region = "cn-hangzhou"
# バケットの名前を指定します。
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)
# サイズが 1,000 バイトのオブジェクトを作成します。
object_name = 'rangeTest.txt'
content = 'a' * 1000
bucket.put_object(object_name, content)
headers = {'x-oss-range-behavior': 'standard'}
# 範囲の終わりの値が無効な場合、OSS は 500 バイトから 999 バイトまでの範囲内のデータと HTTP ステータスコード 206 を返します。
object_stream = bucket.get_object(object_name, byte_range=(500, 2000), headers=headers)
print('standard get 500~2000 http status code:', object_stream.status)
print('standard get 500~2000 contnet_length:', object_stream.content_length)
try:
# 範囲の始まりの値が無効な場合、例外がスローされます。次に、OSS は HTTP ステータスコード 416 とエラーコード InvalidRange を返します。
object_stream = bucket.get_object(object_name, byte_range=(1000, 2000), headers=headers)
except oss2.exceptions.ServerError as e:
print('standard get 1000~2000 http status code:', e.status)
print('standard get 1000~2000 error code:', e.code)