Object Storage Service:OSS SDK for Python 1.0 を使用してオブジェクトをクエリする

使用上の注意

• このトピックでは、中国 (杭州) リージョンのパブリックエンドポイントを使用しています。 OSS と同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用します。 OSS のリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。

• このトピックでは、OSS エンドポイントを使用して OSSClient インスタンスを作成します。 カスタムドメイン名または Security Token Service (STS) を使用して OSSClient インスタンスを作成する場合は、「初期化 (Python SDK V1)」をご参照ください。

• オブジェクトをクエリするには、oss:GetObject 権限が必要です。 詳細については、「RAM ユーザーにカスタムポリシーをアタッチする」をご参照ください。

• SelectObject を使用してクエリできるのは、CSV 形式と JSON 形式のオブジェクトのみです。

例

次のコードは、CSV オブジェクトと JSON オブジェクトをクエリする方法の例を示しています。

import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def select_call_back(consumed_bytes, total_bytes =  None):
        print('Consumed Bytes:' + str(consumed_bytes) + '\n')

# 環境変数からアクセス認証情報を取得します。サンプルコードを実行する前に、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)

key ='python_select.csv'
content ='Tom Hanks,USA,45\r\n'*1024
filename ='python_select.csv'

# CSV ファイルをアップロードします。
bucket.put_object(key, content)
# SelectObject 操作のパラメーターを設定します。
csv_meta_params = {'RecordDelimiter': '\r\n'}
select_csv_params = {'CsvHeaderInfo': 'None',
                    'RecordDelimiter': '\r\n',
                    'LineRange': (500, 1000)}

csv_header = bucket.create_select_object_meta(key, csv_meta_params)
print(csv_header.rows)
print(csv_header.splits)
result = bucket.select_object(key, "select * from ossobject where _3 > 44", select_call_back, select_csv_params)
select_content = result.read()
print(select_content)

result = bucket.select_object_to_file(key, filename,
      "select * from ossobject where _3 > 44", select_call_back, select_csv_params)
bucket.delete_object(key)

###JSON DOCUMENT
key =  'python_select.json'
content =  "{\"contacts\":[{\"key1\":1,\"key2\":\"hello world1\"},{\"key1\":2,\"key2\":\"hello world2\"}]}"
filename =  'python_select.json'
# JSON DOCUMENT オブジェクトをアップロードします。
bucket.put_object(key, content)
select_json_params = {'Json_Type': 'DOCUMENT'}
result = bucket.select_object(key, "select s.key2 from ossobject.contacts[*] s where s.key1 = 1", None, select_json_params)
select_content = result.read()
print(select_content)

result = bucket.select_object_to_file(key, filename,
      "select s.key2 from ossobject.contacts[*] s where s.key1 = 1", None, select_json_params)
bucket.delete_object(key)

###JSON LINES
key =  'python_select_lines.json'
content =  "{\"key1\":1,\"key2\":\"hello world1\"}\n{\"key1\":2,\"key2\":\"hello world2\"}"
filename =  'python_select.json'
# JSON LINES オブジェクトをアップロードします。
bucket.put_object(key, content)
select_json_params = {'Json_Type': 'LINES'}
json_header = bucket.create_select_object_meta(key,select_json_params)
print(json_header.rows)
print(json_header.splits)

result = bucket.select_object(key, "select s.key2 from ossobject s where s.key1 = 1", None, select_json_params)
select_content =  result.read()
print(select_content)
result = bucket.select_object_to_file(key, filename,
           "select s.key2 from ossobject s where s.key1 = 1", None, select_json_params)
bucket.delete_object(key)

Python SelectObject

このセクションでは、Python の SelectObject 操作で使用される要素について説明します。これらの要素には、select_object、select_object_to_file、および create_select_object_meta が含まれます。

• select_object

  • 次のコードは、select_object のパラメーターを指定する方法の例を示しています。

    def select_object(self, key, sql,
                       progress_callback=None,
                       select_params=None
                       byte_range=None
                       headers=None
                       ):

    上記のコード例は、指定されたキーを持つオブジェクトに対して SQL 文を実行し、クエリ結果を返すために使用されます。

    • sql: Base64 エンコードする必要のない SQL 文。

    • Progress_callback: オプション。このパラメーターは、クエリ進捗状況の報告に使用するコールバック関数を指定します。

    • select_params: SelectObject 操作のパラメーターとアクション。

    • headers: リクエストに含まれるヘッダー情報。ヘッダー情報は、GetObject 操作の場合と同じように機能します。たとえば、リクエストヘッダーの bytes フィールドを設定して、クエリする CSV オブジェクトの範囲を指定できます。

  • 次の表に、select_params でサポートされているパラメーターを示します。

    パラメーター	説明
    Json_Type	このパラメーターが指定されていない場合、デフォルトではオブジェクトは CSV オブジェクトです。 このパラメーターが DOCUMENT に設定されている場合、オブジェクトは JSON ドキュメントオブジェクトです。 このパラメーターが LINES に設定されている場合、オブジェクトは JSON LINES オブジェクトです。
    CsvHeaderInfo	CSV オブジェクトのヘッダー情報。 有効な値: なし、無視、使用。 なし: このオブジェクトにはヘッダー情報が設定されていません。 無視: このオブジェクトにはヘッダー情報が設定されていますが、SQL 文の実行時には使用されません。 使用: このオブジェクトにはヘッダー情報が設定されており、SQL 文の実行時にはヘッダー情報の列名が使用されます。
    CommentCharacter	CSV オブジェクトのコメント文字。このパラメーターの値は、長さが 1 文字のみです。デフォルト値は None で、コメント文字が許可されていないことを示します。
    RecordDelimiter	CSV オブジェクトの行区切り文字。このパラメーターの値は、長さが 1 文字または 2 文字のみです。デフォルト値: \n。
    OutputRecordDelimiter	SELECT 文の出力結果の行区切り文字。デフォルト値: \n。
    FieldDelimiter	CSV オブジェクトの列区切り文字。このパラメーターの値は、長さが 1 文字のみです。デフォルト値はカンマ (,) です。
    OutputFieldDelimiter	SELECT 文の出力結果の列区切り文字。デフォルト値はカンマ (,) です。
    QuoteCharacter	CSV オブジェクトの列の引用符。このパラメーターの値は、長さが 1 文字のみです。デフォルト値は二重引用符 (") です。引用符で囲まれた行区切り文字と列区切り文字は、通常の文字として処理されます。
    SplitRange	マルチパートクエリのスプリット範囲。このパラメーターの値は、(開始、終了) 形式の閉区間で、クエリするスプリットの範囲を示します。
    LineRange	マルチパートクエリの行範囲。このパラメーターの値は、(開始、終了) 形式の閉区間で、クエリする行の範囲を示します。
    CompressionType	オブジェクトが圧縮される形式。有効な値: GZIP および None。デフォルト値: None。
    KeepAllColumns	このパラメーターを true に設定すると、CSV オブジェクトの SELECT 文で除外された列は、出力結果では空のままになります。ただし、列の位置は保持されます。デフォルト値: False。 たとえば、CSV オブジェクトの列は、firstname、lastname、および age です。SQL 文は ossobject から firstname、age を選択します です。 KeepAllColumns が true に設定されている場合、出力結果は firstname,,age になり、除外された lastname 列の位置を示すために余分なカンマ (,) が追加されます。 KeepAllColumns が false に設定されている場合、出力結果は firstname,age になります。 説明 このパラメーターは、GetObject の処理に使用するコードを、変更なしで SelectObject の処理に使用できるようにすることを目的としています。
    OutputRawData	このパラメーターを True に設定すると、SelectObject は生データを直接返します。データが長時間返されない場合、タイムアウトエラーが発生する可能性があります。 このパラメーターを False に設定すると、出力データはフレームにカプセル化されます。デフォルト値: False。
    EnablePayloadCrc	各フレームの巡回冗長検査 (CRC) 値を計算するかどうかを指定します。デフォルト値: False。
    OutputHeader	出力結果の最初の行のヘッダー情報。このパラメーターは CSV オブジェクトにのみ適用されます。
    SkipPartialDataRecord	CSV オブジェクトに対してこのパラメーターを True に設定すると、レコードの列にデータがない場合、現在のレコードはスキップされます。JSON オブジェクトに対してこのパラメーターを True に設定すると、レコードのキーが存在しない場合、現在のレコードはスキップされます。このパラメーターを False に設定すると、データのない列は出力結果で空のままになります。 例えば、行には firstname 列、lastname 列、および age 列が含まれています。SQL 文は select _1, _4 from ossobject です。 このパラメーターを True に設定すると、この行はスキップされます。 このパラメーターを False に設定すると、firstname,\n が返されます。
    MaxSkippedRecordsAllowed	スキップされる行の最大数。デフォルト値は 0 で、行がスキップされた場合にエラーが返されることを示します。
    ParseJsonNumberAsString	このパラメーターを True に設定すると、JSON オブジェクトのすべての数値は文字列として解析されます。 このパラメーターを False に設定すると、JSON オブジェクトのすべての数値は整数または浮動小数点数として解析されます。デフォルト値: False。 JSON オブジェクトの高精度浮動小数点数は、浮動小数点数として解析されると精度が低下します。精度を維持するには、このパラメーターを True に設定し、CAST 関数を使用して解析済みデータを10進数型に変換します。

  • select_object の戻り値: SelectObjectResult オブジェクトが返されます。read() 関数または _iter_ メソッドを使用して、すべての結果を取得できます。

    説明

    複数の結果が返されたときに read() 関数を呼び出してすべての結果を読み取ると、過剰なメモリリソースが使用され、長時間待機する必要があります。_iter_ メソッド (foreach chunk in result) を使用して結果を取得し、結果の各チャンクを処理することをお勧めします。_iter_ メソッドはメモリ使用量を削減し、クライアントが OSS サーバーによって処理された各チャンクリクエストをタイムリーに処理できるようにします。これにより、クライアントはすべての結果が返されるまで待つ必要がなくなります。

• select_object_to_file

  def select_object_to_file(self, key, filename, sql,
                     progress_callback=None,
                     select_params=None
                     headers=None
                     ):

  上記のコード例は、指定されたキーを持つオブジェクトに対して SQL 文を実行し、クエリ結果を別の指定されたオブジェクトに書き込むために使用されます。

  その他のパラメーターは select_object と同じです。

• create_select_object_meta

  • create_select_object_meta の構文

    def create_select_object_meta(self, key, select_meta_params=None, header=None):

    上記のコード例は、指定されたキーを持つオブジェクトの Select Meta を作成するか、そのようなオブジェクトから Select Meta を取得するために使用されます。Select Meta には、オブジェクトの行の総数、列の総数 (CSV オブジェクトの場合)、およびスプリットの総数が含まれます。

    オブジェクトに対して Select Meta が既に作成されている場合、OverwriteIfExists パラメーターが true に設定されていない限り、この関数は Select Meta を再作成しません。

    オブジェクトの Select Meta を作成するには、オブジェクトを完全にスキャンする必要があります。

  • 次の表に、select_meta_params でサポートされているパラメーターを示します。

    パラメーター	説明
    Json_Type	このパラメーターが指定されていない場合、デフォルトではオブジェクトは CSV オブジェクトです。 このパラメーターが指定されている場合、このパラメーターの値は LINES である必要があり、オブジェクトが JSON LINES オブジェクトであることを示します。 説明 この操作は JSON ドキュメントオブジェクトには適用されません。
    RecordDelimiter	CSV オブジェクトの行区切り文字。
    FieldDelimiter	CSV オブジェクトの列区切り文字。
    QuoteCharacter	CSV オブジェクトの引用符。引用符で囲まれた行区切り文字と列区切り文字は、通常の文字として処理されます。
    CompressionType	オブジェクトが圧縮される形式。圧縮形式はサポートされていません。デフォルト値は None です。
    OverwriteIfExists	作成された Select Meta が元の Select Meta を上書きするかどうかを指定します。ほとんどの場合、このパラメーターを設定する必要はありません。

  • create_select_object_meta の戻り値: GetSelectObjectMetaResult オブジェクトが返されます。これには、rows 属性と splits 属性が含まれます。CSV オブジェクトの場合、結果の select_resp オブジェクトには columns 属性が含まれ、CSV オブジェクトの列の数を示します。

関連情報

• オブジェクトのクエリに使用する完全なサンプルコードについては、GitHub をご覧ください。

• オブジェクトのクエリに呼び出すことができる API 操作の詳細については、「SelectObject」をご参照ください。