Object Storage Service:Consultar objetos com o OSS SDK for Python 1.0

Observações

• Este tópico usa o endpoint público da região china (Hangzhou). Para acessar o OSS a partir de outros serviços da alibaba cloud na mesma região, use um endpoint interno. Para obter mais informações sobre regiões e endpoints do OSS, consulte Regions and endpoints.

• Este tópico demonstra como criar uma instância OSSClient com um endpoint do OSS. Para configurações alternativas, como o uso de um domínio personalizado ou a autenticação com credenciais do Security Token service (STS), consulte Initialization.

• Para consultar objetos, você deve ter a permissão oss:GetObject. Para mais informações, consulte Grant a custom policy.

• O SelectObject permite consultar apenas objetos nos formatos CSV e JSON.

Exemplos

O código a seguir mostra como consultar objetos CSV e 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

Esta seção descreve os elementos usados na operação SelectObject em Python, incluindo select_object, select_object_to_file e create_select_object_meta.

• select_object

  • O código a seguir mostra como especifique e selecione os parâmetros para select_object:

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

    O exemplo de código anterior execute uma instrução SQL no objeto com a chave especificada e retorna os resultados da consulta.

    • sql: a instrução SQL, sem necessidade de codificação em Base64.

    • Progress_callback: opcional. Este parâmetro define uma função de callback para relatar o progresso da consulta.

    • select_params: os parâmetros e as ações da operação SelectObject.

    • headers: as informações de cabeçalho da requisição. O cabeçalho funciona da mesma forma que na operação GetObject. Por exemplo, configure o campo bytes no cabeçalho da requisição para especificar o intervalo do objeto CSV a ser consultado.

  • A tabela a seguir descreve os parâmetros suportados por select_params.

    Parâmetro	Descrição
    Json_Type	Por padrão, o objeto é tratado como CSV se este parâmetro não for especificado. O objeto é tratado como um JSON Document se este parâmetro for defina como DOCUMENT. O objeto é tratado como um JSON LINES se este parâmetro for definido como LINES.
    CsvHeaderInfo	As informações de cabeçalho do objeto CSV. Valores válidos: None, Ignore e Use. None: o objeto não possui informações de cabeçalho configuradas. Ignore: o objeto possui informações de cabeçalho configuradas, mas não são usadas durante a execução da instrução SQL. Use: o objeto possui informações de cabeçalho configuradas e os nomes das colunas no cabeçalho são usados durante a execução da instrução SQL.
    CommentCharacter	O caractere de comentário no objeto CSV. O valor deste parâmetro deve conter apenas um caractere. O valor padrão é None, que não permite caracteres de comentário.
    RecordDelimiter	O delimitador de linha no objeto CSV. O valor deste parâmetro deve conter um ou dois caracteres. Valor padrão: \n.
    OutputRecordDelimiter	O delimitador de linha no resultado de saída da instrução SELECT. Valor padrão: \n.
    FieldDelimiter	O delimitador de coluna no objeto CSV. O valor deste parâmetro deve conter apenas um caractere. O valor padrão é a vírgula (,).
    OutputFieldDelimiter	O delimitador de coluna no resultado de saída da instrução SELECT. O valor padrão é a vírgula (,).
    QuoteCharacter	O caractere de aspas para as colunas no objeto CSV. O valor deste parâmetro deve conter apenas um caractere. O valor padrão é a aspa dupla ("). Os delimitadores de linha e coluna entre aspas são processados como caracteres normais.
    SplitRange	O intervalo de divisão na consulta multipart. O valor deste parâmetro é um intervalo fechado no formato (start, end), que indica o intervalo de divisões a serem consultadas.
    LineRange	O intervalo de linhas na consulta multipart. O valor deste parâmetro é um intervalo fechado no formato (start, end), que indica o intervalo de linhas a serem consultadas.
    CompressionType	O formato de compactação do objeto. Valores válidos: GZIP e None. Valor padrão: None.
    KeepAllColumns	Se este parâmetro for defina como true, as colunas que a instrução SELECT exclui no objeto CSV ficarão vazias no resultado de saída, mas as posições das colunas serão mantidas. Valor padrão: False. Por exemplo, suponha que as colunas no objeto CSV sejam firstname, lastname e age, e a instrução SQL seja select firstname, age from ossobject. Se KeepAllColumns for definido como true, o resultado de saída será firstname,,age, com uma vírgula extra (,) para indicar a posição da coluna excluída lastname. Se KeepAllColumns for definido como false, o resultado de saída será firstname,age. Nota Este parâmetro permite que o código usado para processar o GetObject também processe o SelectObject sem a necessidade de modificações.
    OutputRawData	Se este parâmetro for definido como True, o SelectObject retorna diretamente os dados brutos. Se os dados demorarem muito para retornar, poderá ocorrer um erro de tempo limite. Se este parâmetro for definido como False, o sistema encapsula os dados de saída em frames. Valor padrão: False.
    EnablePayloadCrc	Define se o sistema calcula um valor de verificação de redundância cíclica (CRC) para cada frame. Valor padrão: False.
    OutputHeader	As informações de cabeçalho na primeira linha do resultado de saída. Este parâmetro se aplica apenas a objetos CSV.
    SkipPartialDataRecord	Se este parâmetro for definido como True para um objeto CSV, o sistema ignora o registro atual quando uma coluna desse registro não tiver dados. Para um objeto JSON, o sistema ignora o registro atual se uma chave não existir. Se definido como False, uma coluna sem dados fica vazia no resultado de saída. Por exemplo, suponha que uma linha inclua as colunas firstname, lastname e age, e a instrução SQL seja select _1, _4 from ossobject. Se este parâmetro for definido como True, o sistema ignora essa linha. Se este parâmetro for definido como False, o retorno será firstname,\n.
    MaxSkippedRecordsAllowed	O número máximo de linhas ignoradas. O valor padrão é 0, o que indica que o sistema retorna um erro se uma linha for ignorada.
    ParseJsonNumberAsString	Se este parâmetro for definido como True, o sistema analisa todos os números no objeto JSON como strings. Se este parâmetro for definido como False, o sistema analisa todos os números no objeto JSON como inteiros ou números de ponto flutuante. Valor padrão: False. Números de ponto flutuante de alta precisão em um objeto JSON sofrem perda de precisão quando analisados como números de ponto flutuante. Para manter a precisão, defina este parâmetro como True e use a função CAST para converter os dados analisados no tipo decimal.

  • Resultados retornados por select_object: A operação retorna um objeto SelectObjectResult. Use a função read() ou o método _iter_ para obter todos os resultados.

    Nota

    Se você chamar a função read() para ler todos os resultados quando a operação retornar múltiplos resultados, o consumo de recursos de memória será excessivo e o tempo de espera será longo. Recomendamos usar o método _iter_ (foreach chunk in result) para obter e processar cada parte dos resultados. O método _iter_ reduz o uso de memória e permite que o cliente processe cada parte processada pelo servidor OSS de forma oportuna, sem precisar aguardar o retorno de todos os resultados.

• select_object_to_file

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

  O exemplo de código anterior execute uma instrução SQL no objeto com a chave especificada e grava os resultados da consulta em outro objeto especificado.

  Os demais parâmetros são os mesmos descritos em select_object.

• create_select_object_meta

  • Sintaxe de create_select_object_meta

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

    O exemplo de código anterior crie o Select Meta para o objeto com a chave especificada ou obtém o Select Meta desse objeto. O Select Meta inclui o número total de linhas, o número total de colunas (para objetos CSV) e o número total de divisões em um objeto.

    Se o Select Meta já tiver sido criado para um objeto, esta função não o recriará, a menos que o parâmetro OverwriteIfExists seja definido como true.

    Para criar o Select Meta de um objeto, é necessário verificar o objeto totalmente.

  • A tabela a seguir descreve os parâmetros suportados por select_meta_params.

    Parâmetro	Descrição
    Json_Type	Por padrão, o objeto é tratado como CSV se este parâmetro não for especificado. Se este parâmetro for especificado, seu valor deve ser LINES, o que indica que o objeto é um JSON LINES. Nota Esta operação não se aplica a objetos JSON Document.
    RecordDelimiter	O delimitador de linha no objeto CSV.
    FieldDelimiter	O delimitador de coluna no objeto CSV.
    QuoteCharacter	O caractere de aspas no objeto CSV. Os delimitadores de linha e coluna entre aspas são processados como caracteres normais.
    CompressionType	O formato de compactação do objeto. O sistema não suporta formatos de compactação. O valor padrão é None.
    OverwriteIfExists	Define se o Select Meta criado sobrescreve o Select Meta original. Na maioria dos casos, não é necessário configurar este parâmetro.

  • Resultados retornados por create_select_object_meta: A operação retorna um objeto GetSelectObjectMetaResult, incluindo os atributos rows e splits. Para um objeto CSV, o objeto select_resp no resultado inclui o atributo columns, que indica o número de colunas no objeto CSV.

Referências

• Para acessar o código de exemplo completo para consultar objetos, visite o GitHub.

• Para obter mais informações sobre a operação de API para consultar objetos, consulte SelectObject.