Object Storage Service：Python查詢檔案

注意事項

• 本文以華東1（杭州）外網Endpoint為例。如果您希望通過與OSS同地區的其他阿里雲產品訪問OSS，請使用內網Endpoint。關於OSS支援的Region與Endpoint的對應關係，請參見OSS訪問網域名稱、資料中心、開放連接埠。

• 本文以OSS網域名稱建立OSSClient為例。如果您希望通過自訂網域名、STS等方式建立OSSClient，請參見初始化。

• 要查詢檔案，您必須具有oss:GetObject許可權。具體操作，請參見為RAM使用者授權自訂的權限原則。

• OSS僅支援查詢CSV檔案和JSON檔案，不支援查詢其他格式的檔案。

Python SDK樣本

以下代碼用於查詢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())

# 填寫Bucket所在地區對應的Endpoint。以華東1（杭州）為例，Endpoint填寫為https://oss-cn-hangzhou.aliyuncs.com。
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# 填寫Endpoint對應的Region資訊，例如cn-hangzhou。注意，v4簽名下，必須填寫該參數
region = "cn-hangzhou"

# yourBucketName填寫儲存空間名稱。
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)
# Select API的參數。
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 LINE。
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 Select API中的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
                       ):

    以上樣本用於對指定Key的檔案運行SQL，並返回查詢結果。

    • sql是原始的SQL字串，無需做base64編碼。

    • Progress_callback是可選的用來彙報進度的回呼函數。

    • select_params用於指定select執行的各種參數以及行為。

    • headers用於指定請求中附帶的header資訊，其行為和get-object一致。比如，對於CSV檔案，在某些情況下可以用bytes來指定SQL查詢在檔案中的範圍。

  • select_params支援的參數

    參數名稱	描述
    Json_Type	當Json_Type沒有指定時，預設為CSV檔案。 當Json_Type指定為DOCUMENT時，該檔案為JSON DOCUMENT檔案。 當Json_Type指定為LINES時，該檔案為JSON LINE檔案。
    CsvHeaderInfo	CSV的header資訊。 合法值為None、Ignore以及Use。 None：該檔案沒有header資訊。 Ignore：該檔案有header資訊但未在SQL中使用。 Use：該檔案有Header資訊且在sql語句中使用了Header中的列名。
    CommentCharacter	CSV中的注釋字元。僅支援一個字元，預設為None表示沒有注釋字元。
    RecordDelimiter	CSV中的行分隔字元，僅支援一個或兩個字元。預設為\n。
    OutputRecordDelimiter	Select輸出結果中的行分隔字元。預設為\n。
    FieldDelimiter	CSV的資料行分隔符號，僅支援一個字元，預設為逗號（,）。
    OutputFieldDelimiter	Select輸出結果中的資料行分隔符號，預設為逗號（,）。
    QuoteCharacter	CSV列的引號字元，只支援一個字元，預設為雙引號。引號內的行資料行分隔符號被當做一般字元處理。
    SplitRange	使用Split做分區查詢。格式為(start, end)，此處為閉區間，表示查詢範圍從Split start#到end#。
    LineRange	使用行做分區查詢。格式為(start, end)，此處為閉區間，表示查詢範圍從行號start#到end#。
    CompressionType	壓縮類型，可以為GZIP。預設為None。
    KeepAllColumns	該參數設定為true時表示原CSV檔案中未在select列中出現的列將以空值輸出（但保留列的位置）。預設為False。 如果CSV檔案中的列為 firstname, lastname, age，SQL為select firstname, age from ossobject。 如果KeepAllColumns為true，則輸出為firstname,,age（中間多一個逗號）。 如果KeepAllColumns為false，則輸出為firstname,age。 說明 引入該選項的原因是讓原本處理GetObject返回資料的代碼可以在不用修改的情況下平移切換到SelectObject。
    OutputRawData	該參數為True時表示輸出為Select資料，沒有Frame的封裝，表明很長時間不返回資料時會引起逾時。 該參數為False時表示輸出為Frame封裝的資料。預設是False。
    EnablePayloadCrc	為每個Frame計算CRC校正值，預設為False。
    OutputHeader	僅用於CSV檔案，表示輸出結果中第一行是Header資訊。
    SkipPartialDataRecord	該參數為True時，如果CSV中某一列值不存在或者JSON中某一個Key不存在，則直接跳過整個記錄。該參數為False時，則把該列當做null來處理。 假如某一行的列為firstname,lastname,age。SQL為select _1, _4 from ossobject。 如果為True，則直接跳過此行。 如果為False，則返回firstname,\n。
    MaxSkippedRecordsAllowed	允許跳過的行的最大值。預設為0，表示一旦有一行跳過就返回錯誤。
    ParseJsonNumberAsString	當該參數為True時：表示JSON檔案中的數字都解析為字串。 當參數為False時：按照整數或者浮點數進行解析，False為預設值。 當JSON檔案中含有高精度的浮點數時，直接解析為浮點數會丟失精度。如果想保留原始的精度，則可以設定該參數為True，並且在SQL語句中將該列Cast為decimal類型即可。

  • select_object傳回值：返回SelectObjectResult對象，該對象支援read()函數以獲得所有select結果。同時也支援__iter__方法。

    說明

    如果Select結果偏大，調用read()函數會阻塞直到select結果完全返回，同時佔用過多的記憶體。建議使用__iter__方法（foreach chunk in result），然後對每個chunk進行處理。__iter__方法不僅可以降低記憶體使用量，且OSS伺服器端每處理一個請求chunk用戶端都能及時處理，不必等到全部結果返回後才處理。

• select_object_to_file

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

  以上樣本用於對指定Key的檔案運行SQL，將查詢結果寫入指定的檔案。

  涉及的參數描述與select_object相同。

• create_select_object_meta

  • create_select_object_meta的文法結構

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

    以上樣本用於對指定Key的檔案進行建立或者擷取select meta。select meta是指該檔案的總行數、總列數（CSV檔案）、總的Split數。

    如果該檔案已經建立過meta，則調用該函數不會重新建立，除非在參數中指定OverwriteIfExists為true。

    建立select meta需要掃描整個檔案。

  • select_meta_params中支援的參數

    參數名稱	描述
    Json_Type	當Json_Type沒有指定時，預設為CSV檔案。 若指定，必須為LINES，表示檔案是JSON LINES。 說明 JSON DOCUMENT不支援該操作。
    RecordDelimiter	CSV檔案分行符號。
    FieldDelimiter	CSV檔案資料行分隔符號。
    QuoteCharacter	CSV檔案列引號符。引號符內的行資料行分隔符號按一般字元處理。
    CompressionType	壓縮類型。目前不支援任何壓縮類型，故只能為None。
    OverwriteIfExists	覆蓋原有的Select Meta。正常情況無需使用該選項。

  • create_select_object_meta傳回值：GetSelectObjectMetaResult對象，包括rows、splits兩個屬性。對於CSV檔案，其內部的select_resp對象還包括columns值，表示CSV檔案的列數。

相關文檔

• 關於查詢檔案的完整範例程式碼，請參見GitHub樣本。

• 關於查詢檔案的API介面說明，請參見SelectObject。