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

Observações

• Os exemplos deste tópico utilizam 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, utilize um endpoint interno. Para mais informações sobre regiões e endpoints do OSS, consulte Regiões e endpoints.

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

• A consulta de objetos exige a permissão oss:GetObject. Para mais detalhes, consulte Conceder uma política personalizada.

• A operação SelectObject aceita consultas apenas em objetos nos formatos CSV e JSON.

Exemplos

O código a seguir exemplifica a consulta de 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)

SelectObject em Python

Esta seção detalha os elementos da operação SelectObject em Python: select_object, select_object_to_file e create_select_object_meta.

• select_object

  • O exemplo a seguir mostra como especificar parâmetros para select_object:

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

    Esse trecho de código executa uma instrução SQL no objeto identificado pela chave especificada e retorna os resultados da consulta.

    • sql: instrução SQL sem codificação Base64.

    • Progress_callback: opcional. Define uma função de callback para reportar o progresso da consulta.

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

    • headers: informações de cabeçalho incluídas na requisição. Funcionam da mesma forma que na operação GetObject. Por exemplo, configure o campo bytes no cabeçalho para definir o intervalo de consulta em um objeto CSV.

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

    Parâmetro	Descrição
    Json_Type	Se omitido, o objeto é tratado como CSV por padrão. Defina como DOCUMENT para objetos JSON Document. Defina como LINES para objetos JSON LINES.
    CsvHeaderInfo	Informações de cabeçalho do objeto CSV. Valores válidos: None, Ignore e Use. None: O objeto não possui cabeçalho configurado. Ignore: O objeto tem cabeçalho, mas ele é ignorado durante a execução da instrução SQL. Use: O objeto tem cabeçalho e os nomes das colunas são utilizados na execução da instrução SQL.
    CommentCharacter	Caractere de comentário no objeto CSV. Aceita apenas um caractere. O valor padrão é None, indicando que comentários não são permitidos.
    RecordDelimiter	Delimitador de linha do objeto CSV. Aceita um ou dois caracteres. Valor padrão: \n.
    OutputRecordDelimiter	Delimitador de linha no resultado da instrução SELECT. Valor padrão: \n.
    FieldDelimiter	Delimitador de coluna do objeto CSV. Aceita apenas um caractere. O valor padrão é vírgula (,).
    OutputFieldDelimiter	Delimitador de coluna no resultado da instrução SELECT. O valor padrão é vírgula (,).
    QuoteCharacter	Caractere de aspas para as colunas do objeto CSV. Aceita apenas um caractere. O valor padrão é aspas duplas ("). Delimitadores de linha e coluna entre aspas são tratados como caracteres normais.
    SplitRange	Intervalo de splits para consulta multipart. O valor é um intervalo fechado no formato (início, fim), indicando quais splits consultar.
    LineRange	Intervalo de linhas para consulta multipart. O valor é um intervalo fechado no formato (início, fim), indicando quais linhas consultar.
    CompressionType	Formato de compressão do objeto. Valores válidos: GZIP e None. Valor padrão: None.
    KeepAllColumns	Quando definido como true, as colunas excluídas pela instrução SELECT no objeto CSV aparecem vazias no resultado, mantendo suas posições originais. Valor padrão: False. Por exemplo, considere um objeto CSV com as colunas firstname, lastname e age, e a instrução SQL select firstname, age from ossobject. Com KeepAllColumns definido como true, o resultado será firstname,,age, onde a vírgula extra indica a posição da coluna lastname excluída. Com KeepAllColumns definido como false, o resultado será firstname,age. Nota Este parâmetro permite que códigos escritos para processar GetObject funcionem com SelectObject sem modificações.
    OutputRawData	Se definido como True, o SelectObject retorna os dados brutos diretamente. A ausência de retorno de dados por muito tempo pode causar erro de timeout. Se definido como False, os dados de saída são encapsulados em frames. Valor padrão: False.
    EnablePayloadCrc	Define se o valor de verificação de redundância cíclica (CRC) é calculado para cada frame. Valor padrão: False.
    OutputHeader	Informações de cabeçalho na primeira linha do resultado. Aplicável apenas a objetos CSV.
    SkipPartialDataRecord	Para objetos CSV com este parâmetro como True, o registro atual é ignorado se alguma coluna estiver vazia. Em objetos JSON, o registro é ignorado se uma chave não existir. Se definido como False, colunas sem dados aparecem vazias no resultado. Por exemplo, numa linha com as colunas firstname, lastname e age, usando a instrução SQL select _1, _4 from ossobject: Com o parâmetro como True, essa linha é ignorada. Com o parâmetro como False, o retorno é firstname,\n.
    MaxSkippedRecordsAllowed	Número máximo de linhas que podem ser ignoradas. O valor padrão é 0, o que gera um erro caso alguma linha seja ignorada.
    ParseJsonNumberAsString	Quando True, todos os números do objeto JSON são interpretados como strings. Quando False, os números são interpretados como inteiros ou ponto flutuante. Valor padrão: False. Números de ponto flutuante de alta precisão em objetos JSON podem perder precisão ao serem interpretados como tal. Para preservar a exatidão, defina este parâmetro como True e utilize a função CAST para converter os dados para o tipo decimal.

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

    Nota

    Ao chamar a função read() para ler múltiplos resultados de uma vez, há consumo excessivo de memória e longa espera. Recomendamos o uso do método _iter_ (foreach chunk in result) para obter e processar cada bloco individualmente. Essa abordagem reduz o uso de memória e permite que o cliente processe cada bloco à medida que o servidor OSS os disponibiliza, eliminando a necessidade de aguardar o retorno completo dos dados.

• select_object_to_file

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

  O código acima executa uma instrução SQL no objeto com a chave especificada e grava os resultados em outro objeto definido.

  Os demais parâmetros seguem a mesma definição de 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):

    Este trecho cria ou obtém o Select Meta do objeto identificado pela chave. O Select Meta contém o total de linhas, total de colunas (para CSV) e total de splits do objeto.

    Caso o Select Meta já exista, a função não o recria, a menos que o parâmetro OverwriteIfExists esteja definido como true.

    A criação do Select Meta exige a varredura completa do objeto.

  • A tabela a seguir lista os parâmetros aceitos por select_meta_params.

    Parâmetro	Descrição
    Json_Type	Sem essa especificação, o objeto é considerado CSV por padrão. Se especificado, deve ser LINES, indicando um objeto JSON LINES. Nota Esta operação não se aplica a objetos JSON Document.
    RecordDelimiter	Delimitador de linha do objeto CSV.
    FieldDelimiter	Delimitador de coluna do objeto CSV.
    QuoteCharacter	Caractere de aspas do objeto CSV. Delimitadores de linha e coluna entre aspas são tratados como caracteres comuns.
    CompressionType	Formato de compressão do objeto. Nenhum formato de compressão é suportado nesta operação. Valor padrão: None.
    OverwriteIfExists	Indica se o novo Select Meta deve sobrescrever o anterior. Geralmente não é necessário configurar este parâmetro.

  • Resultados retornados por create_select_object_meta: Retorna um objeto GetSelectObjectMetaResult contendo os atributos rows e splits. Para objetos CSV, o objeto select_resp no resultado também inclui o atributo columns, indicando o número de colunas.

Referências

• Para acessar o código de exemplo completo sobre consulta de objetos, visite o GitHub.

• Para mais detalhes sobre a operação de API utilizada na consulta de objetos, consulte SelectObject.