Object Storage Service:Consulta de objetos mediante OSS SDK for Python 1.0

Notas

• En este tema se usa el endpoint público de la región China (Hangzhou). Si desea acceder a OSS desde otros servicios de Alibaba Cloud en la misma región, use un endpoint interno. Para obtener más información sobre las regiones y los endpoints de OSS, consulte Regions and endpoints.

• Este tema muestra cómo crear una instancia de OSSClient con un endpoint de OSS. Para configuraciones alternativas, como usar un dominio personalizado o autenticarse con credenciales de Security Token Service (STS), consulte Initialization.

• Para consultar objetos, debe tener el permiso oss:GetObject. Para obtener más información, consulte Grant a custom policy.

• SelectObject solo permite consultar objetos en formatos CSV y JSON.

Ejemplos

A continuación se presenta un ejemplo de código para consultar objetos CSV y 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 sección describe los elementos que se usan en la operación SelectObject en Python: select_object, select_object_to_file y create_select_object_meta.

• select_object

  • El siguiente código muestra cómo especificar parámetros para select_object:

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

    El ejemplo anterior ejecuta una instrucción SQL en el objeto con la clave especificada y devuelve los resultados de la consulta.

    • sql: instrucción SQL, sin codificación Base64.

    • Progress_callback: opcional. Especifica una función de devolución de llamada para reportar el progreso de la consulta.

    • select_params: parámetros y acciones de la operación SelectObject.

    • headers: información de encabezado incluida en la solicitud. Funciona igual que en la operación GetObject. Por ejemplo, configure el campo bytes en el encabezado de la solicitud para especificar el rango del objeto CSV por consultar.

  • La siguiente tabla describe los parámetros compatibles con select_params.

    Parámetro	Descripción
    Json_Type	Si no se especifica este parámetro, el objeto se considera CSV de forma predeterminada. Si se establece en DOCUMENT, el objeto se considera JSON Document. Si se establece en LINES, el objeto se considera JSON LINES.
    CsvHeaderInfo	Información de encabezado del objeto CSV. Valores válidos: None, Ignore y Use. None: El objeto no tiene información de encabezado configurada. Ignore: El objeto tiene información de encabezado configurada, pero no se usa al ejecutar la instrucción SQL. Use: El objeto tiene información de encabezado configurada y los nombres de columna del encabezado se usan al ejecutar la instrucción SQL.
    CommentCharacter	Carácter de comentario en el objeto CSV. El valor debe tener un solo carácter de longitud. El valor predeterminado es None, lo que indica que no se permiten caracteres de comentario.
    RecordDelimiter	Delimitador de filas en el objeto CSV. El valor debe tener uno o dos caracteres de longitud. Valor predeterminado: \n.
    OutputRecordDelimiter	Delimitador de filas en el resultado de salida de la instrucción SELECT. Valor predeterminado: \n.
    FieldDelimiter	Delimitador de columnas en el objeto CSV. El valor debe tener un solo carácter de longitud. El valor predeterminado es la coma (,).
    OutputFieldDelimiter	Delimitador de columnas en el resultado de salida de la instrucción SELECT. El valor predeterminado es la coma (,).
    QuoteCharacter	Carácter de comilla para las columnas en el objeto CSV. El valor debe tener un solo carácter de longitud. El valor predeterminado es la comilla doble ("). Los delimitadores de fila y columna entre caracteres de comilla se procesan como caracteres normales.
    SplitRange	Rango de divisiones en la consulta multiparte. El valor es un intervalo cerrado en formato (inicio, fin) que indica el rango de divisiones por consultar.
    LineRange	Rango de filas en la consulta multiparte. El valor es un intervalo cerrado en formato (inicio, fin) que indica el rango de filas por consultar.
    CompressionType	Formato de compresión del objeto. Valores válidos: GZIP y None. Valor predeterminado: None.
    KeepAllColumns	Si se establece en true, las columnas excluidas por la instrucción SELECT en el objeto CSV quedan vacías en el resultado de salida, pero se conservan sus posiciones. Valor predeterminado: False. Por ejemplo, si las columnas del objeto CSV son firstname, lastname y age, y la instrucción SQL es select firstname, age from ossobject: Si KeepAllColumns se establece en true, el resultado será firstname,,age; se agrega una coma adicional (,) para indicar la posición de la columna excluida lastname. Si KeepAllColumns se establece en false, el resultado será firstname,age. Nota Este parámetro permite reutilizar el código de procesamiento de GetObject para SelectObject sin modificaciones.
    OutputRawData	Si se establece en True, SelectObject devuelve directamente los datos sin procesar. Si no se reciben datos durante mucho tiempo, podría producirse un error de tiempo de espera. Si se establece en False, los datos de salida se encapsulan en tramas. Valor predeterminado: False.
    EnablePayloadCrc	Especifica si se calcula un valor de verificación de redundancia cíclica (CRC) para cada trama. Valor predeterminado: False.
    OutputHeader	Información de encabezado en la primera línea del resultado de salida. Este parámetro solo aplica a objetos CSV.
    SkipPartialDataRecord	Si se establece en True para un objeto CSV, se omite el registro actual cuando alguna de sus columnas no tiene datos. Si se establece en True para un objeto JSON, se omite el registro actual cuando falta alguna clave. Si se establece en False, las columnas sin datos quedan vacías en el resultado de salida. Por ejemplo, si una fila incluye las columnas firstname, lastname y age, y la instrucción SQL es select _1, _4 from ossobject: Si se establece en True, se omite dicha fila. Si se establece en False, se devuelve firstname,\n.
    MaxSkippedRecordsAllowed	Número máximo de filas omitidas permitidas. El valor predeterminado es 0, lo que indica que se devuelve un error si se omite alguna fila.
    ParseJsonNumberAsString	Si se establece en True, todos los números del objeto JSON se analizan como cadenas. Si se establece en False, todos los números del objeto JSON se analizan como enteros o números de punto flotante. Valor predeterminado: False. Los números de punto flotante de alta precisión en un objeto JSON pierden precisión al analizarse como tales. Para conservar la precisión, establezca este parámetro en True y use la función CAST para convertir los datos analizados al tipo decimal.

  • Resultados devueltos por select_object: Se devuelve un objeto SelectObjectResult. Use la función read() o el método _iter_ para obtener todos los resultados.

    Nota

    Si llama a la función read() para leer todos los resultados cuando hay varios registros, se consumen recursos de memoria en exceso y el tiempo de espera aumenta considerablemente. Se recomienda usar el método _iter_ (foreach chunk in result) para obtener y procesar cada fragmento individualmente. El método _iter_ reduce el uso de memoria y permite que el cliente procese oportunamente cada fragmento gestionado por el servidor OSS, sin esperar a recibir todos los resultados.

• select_object_to_file

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

  El ejemplo anterior ejecuta una instrucción SQL en el objeto con la clave especificada y escribe los resultados de la consulta en otro objeto indicado.

  Los demás parámetros son los mismos que los de select_object.

• create_select_object_meta

  • Sintaxis de create_select_object_meta

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

    El ejemplo anterior crea metadatos de selección (Select Meta) para el objeto con la clave especificada u obtiene los metadatos existentes. Select Meta incluye el número total de filas, el número total de columnas (para objetos CSV) y el número total de divisiones del objeto.

    Si ya existen metadatos de selección para un objeto, esta función no los vuelve a crear a menos que el parámetro OverwriteIfExists se establezca en true.

    Para crear metadatos de selección, es necesario escanear el objeto por completo.

  • La siguiente tabla describe los parámetros compatibles con select_meta_params.

    Parámetro	Descripción
    Json_Type	Si no se especifica este parámetro, el objeto se considera CSV de forma predeterminada. Si se especifica, su valor debe ser LINES, lo que indica que el objeto es de tipo JSON LINES. Nota Esta operación no aplica a objetos JSON Document.
    RecordDelimiter	Delimitador de filas en el objeto CSV.
    FieldDelimiter	Delimitador de columnas en el objeto CSV.
    QuoteCharacter	Carácter de comilla en el objeto CSV. Los delimitadores de fila y columna entre caracteres de comilla se procesan como caracteres normales.
    CompressionType	Formato de compresión del objeto. No se admite ningún formato de compresión. El valor predeterminado es None.
    OverwriteIfExists	Especifica si los metadatos de selección creados sobrescriben los originales. En la mayoría de los casos no es necesario configurar este parámetro.

  • Resultados devueltos por create_select_object_meta: Se devuelve un objeto GetSelectObjectMetaResult con los atributos rows y splits. Para un objeto CSV, el objeto select_resp dentro del resultado incluye el atributo columns, que indica el número de columnas del objeto.

Referencias

• Para consultar el código de ejemplo completo sobre cómo consultar objetos, visite GitHub.

• Para obtener más información sobre la operación API para consultar objetos, consulte SelectObject.