Object Storage Service:オブジェクトの照会

使用上の注意

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

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

• オブジェクトをクエリするには、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')

# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Specify the ID of the region that maps to the endpoint. Example: cn-hangzhou. This parameter is required if you use the signature algorithm V4.
region = "cn-hangzhou"

# Specify the name of your bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

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

# Upload a CSV file. 
bucket.put_object(key, content)
# Configure the parameters for the SelectObject operation. 
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'
# Upload a JSON DOCUMENT object. 
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'
# Upload a JSON LINES object. 
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-encodedする必要のないSQL文。

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

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

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

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

    パラメーター	説明
    Json_タイプ	デフォルトでは、このパラメーターが指定されていない場合、オブジェクトはCSVオブジェクトです。 このパラメーターがDocumentに設定されている場合、オブジェクトはJSON DOCUMENTオブジェクトです。 このパラメーターがLINESに設定されている場合、オブジェクトはJSON LINESオブジェクトです。
    CsvHeaderInfo	CSV オブジェクトのヘッダー情報。 有効な値: None、Ignore、Use。 None: このオブジェクトにはヘッダー情報が設定されていません。 無視: このオブジェクトにはヘッダー情報が設定されていますが、SQL文の実行時に情報は使用されません。 使用: このオブジェクトにはヘッダー情報が設定されており、ヘッダー情報の列名はSQL文の実行時に使用されます。
    CommentCharacter	CSV オブジェクトのコメント文字。 このパラメーターの値は1文字のみです。 デフォルト値はNoneで、コメント文字は使用できません。
    RecordDelimiter	CSV オブジェクトの行区切り文字。 このパラメーターの値の長さは1文字または2文字のみです。 デフォルト値: \n。
    OutputRecordDelimiter	SELECT文の出力結果の行区切り文字。 デフォルト値: \n。
    FieldDelimiter	CSV オブジェクトの列区切り文字。 このパラメーターの値は1文字のみです。 デフォルト値は、コンマ (,) です。
    OutputFieldDelimiter	SELECT文の出力結果の列区切り文字。 デフォルト値は、コンマ (,) です。
    QuoteCharacter	CSV オブジェクトの列の引用文字。 このパラメーターの値は1文字のみです。 デフォルト値は二重引用符 (") です。 引用文字で囲まれた行および列の区切り文字は、通常の文字として処理されます。
    SplitRange	マルチパートクエリの分割範囲。 このパラメーターの値は、(start、end) 形式の閉じた間隔です。これは、クエリする分割の範囲を示します。
    LineRange	マルチパートクエリの行範囲。 このパラメーターの値は、(start、end) 形式の閉じた間隔です。これは、クエリする行の範囲を示します。
    CompressionType	オブジェクトが圧縮される形式。 有効な値: GZIPおよびNone。 デフォルト値 : なし。
    KeepAllColumns	このパラメーターが true に設定されている場合、CSV オブジェクトの SELECT 文で除外された列は、出力結果で空のままになります。 ただし、列の位置は保持されます。 デフォルト値：False。 たとえば、CSVオブジェクトの列は、firstname、lastname、ageです。 SQL 文は select firstname, age from ossobject です。 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_methodを使用できます。

    説明

    複数の結果が返されたときにすべての結果を読み取るためにread() 関数を呼び出すと、過剰なメモリリソースが使用され、長時間待つ必要があります。 結果を取得し、結果の各チャンクを処理するには、_iter_method (foreeach chunk in result) を使用することを推奨します。 _iter_methodは、メモリ使用量を削減し、クライアントが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オブジェクトが返されます。 CSVオブジェクトの場合、結果のselect_respオブジェクトには、CSVオブジェクトの列数を示すcolumns属性が含まれます。

関連ドキュメント

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

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