Subir objeto

Los métodos del SDK listados en esta sección te permitirán subir objetos al bucket de diversas maneras. Puedes subir objetos como un string o como un stream. La referencia de Bucket utilizada en el siguiente fragmento de código es la instancia del componente. Si no tienes Versioning habilitado para tu objeto, y si Stratus recibe múltiples solicitudes de escritura para el mismo objeto, el objeto será sobrescrito continuamente. La última subida del objeto será el único objeto que se almacene. Sin embargo, con Versioning habilitado, cada subida se considerará una versión del objeto, y todas se almacenarán en el bucket, cada una con un version_id único.

file = open('file_path','rb')
res = bucket.put_object("sam/out/sample.txt",file)
print(res)

Subir objeto como string

Usando este método del SDK, puedes subir el objeto como un string. Pasarás el nombre del objeto y los datos a almacenar en el objeto en formato string en el método de subida; put_object()

res = bucket.put_object("sam/out/sample.txt",'content of the file')
print(res)

Subir objeto con opciones

Usando este método del SDK, puedes utilizar las siguientes opciones mientras subes un objeto.

• overwrite: Esta es una opción que puedes usar si Versioning para tu bucket no está habilitado. Sin versioning, necesitas usar esta opción si deseas sobrescribir un recurso. El valor predeterminado es ‘false’.
• ttl: Esta es una opción que puedes usar para establecer el Time-to-Live (TTL) en segundos para un objeto. El valor debe ser mayor o igual a 60 segundos.
• meta_data: Esta es una opción que puedes usar para subir detalles de metadatos del objeto que se está subiendo.
• content_type: Esta es una opción que puedes proporcionar si necesitas establecer el tipo MIME del objeto.

options = {
    'overwrite': 'true',
    'ttl': '300', #especificar el tiempo de vida en segundos
    'meta_data': {
        'author': 'John'
    } 
}
file = open('file_path','rb')
res = bucket.put_object("sam/out/sample.txt",file, options)
print(res)

Subir objeto con opción de extracción

Cuando subes un archivo zip usando el siguiente método, el archivo zip se extraerá y los objetos se subirán al bucket.

# Definir opciones de subida incluyendo extract_upload
options = {
    # Sobrescribir el objeto si ya existe
    'overwrite': 'true',
    # Tiempo de vida en segundos después del cual el objeto expirará
    'ttl': '300',
    # Extraer automáticamente el contenido del archivo ZIP
    'extract_upload': 'true',
    # Tipo MIME del objeto
    'content-type': 'application/zip',
    # Metadatos personalizados asociados al objeto
    'meta_data': {
        'author': 'Sam'
    }
}
#Abrir el archivo en modo binario
file = open('sam.zip', 'rb')
#Subir y extraer el contenido del ZIP
res = bucket.put_object('sam/sample.zip', file, options)

Este método del SDK devolverá un task_id. Puedes usar este task_id en este método del SDK para conocer el estado de la extracción. Respuesta de ejemplo

{ 'task_id': '1234263749' }

Subir objeto usando Multipart

En esta sección vamos a revisar los métodos del SDK que te permitirán subir exitosamente un objeto grande a un bucket en Stratus. La función de subida multipart subirá un archivo grande al bucket en múltiples solicitudes HTTPS. Todas estas solicitudes se combinarán en un solo objeto una vez que todas las partes individuales hayan sido subidas.

init_res = bucket.initiate_multipart_upload(key="")
print(init_res)

Respuesta de ejemplo

{
  bucket: 'zcstratus123-development',
  key: 'objectName.txt',
  upload_id: '01j7xbm4vm5750zbedxqgc4q6m',
  status: 'PENDING'
}

Subir partes del objeto

En el siguiente método del SDK, vamos a realizar subidas de las partes individuales del objeto. Cada parte tendrá un partNumber distinto que varía entre 1 y 1000. Aunque esto representa el orden de las partes, estas partes no necesariamente se subirán en secuencia. Estas partes se combinarán en secuencia una vez que la subida de todas las partes de los objetos esté completa.

upload_res = bucket.upload_part(key="",upload_id="", part_number=3, body=open('file_path','rb'))
print(upload_res)

Obtener resumen de subida Multipart

El siguiente método del SDK se puede usar para obtener un resumen operativo de todas las partes subidas. Para ver el resumen, usaremos el método get_multipart_upload_summary().

summary_res = bucket.get_multipart_upload_summary(key="", upload_id="")
print(summary_res)

Respuesta de ejemplo

{
    "bucket": "zcstratus12345-development",
    "key": "sasm.txt",
    "upload_id": "01hyfyeazrrstmt7k5fa7ej726",
    "status": "PENDING",
    "parts": [
        {
            "part_number": 1,
            "size": 0,
            "uploaded_at": 1716374678999
        },
        {
            "part_number": 2,
            "size": 2797094,
            "uploaded_at": 1716374678576
        },
        {
            "part_number": 4,
            "size": 0,
            "uploaded_at": 1716374679136
        }
    ]
}

Completar subida Multipart del objeto

El siguiente método nos permite terminar el proceso multipart una vez que todas las partes se han subido exitosamente. Para completar el proceso pasaremos el uploadId al método complete_multipart_upload().

complete_res = bucket.complete_multipart_upload(key="", upload_id="")
print(complete_res)

Implementación de ejemplo del SDK

from concurrent.futures import ThreadPoolExecutor
import zcatalyst_sdk

def handler(request: Request):
    app = zcatalyst_sdk.initialize()
    if request.path == "/":
        # instancia de stratus
        stratus = app.stratus()
        # instancia del bucket
        bucket = stratus.bucket('bucket_name')
        # subida multiparte
        key = "sam/out/sample.txt"
        file_path = '/sam/smple.mp4'
        initiate_res = bucket.initiate_multipart_upload(key)
        part_number = 1
        part_size = 50 * 1024 * 1024
        futures = []
        try:
            with open(file_path, 'rb') as file:
                with ThreadPoolExecutor(max_workers=3) as executor:
                    while True:
                        chunk = file.read(part_size)
                        if not chunk:
                            break
                        futures.append(executor.submit(
        bucket.upload_part,
        key,
        initiate_res['upload_id'],
        chunk, part_number
        )
       )
                        part_number += 1
            for future in futures:
                future.result()
         except Exception as err:
            raise err
         multipart_upload_res = bucket.complete_multipart_upload(key, initiate_res['upload_id'])
        return multipart_upload_res
        else:
        response = make_response('Unknown path')
        response.status_code = 400
        return response

Subir un objeto usando Transfer Manager

Cuando el objeto que necesitas subir es demasiado grande para subirlo, puedes realizar una operación de transfer manager. La operación de transfer manager dividirá el objeto en múltiples partes y realizará una subida más rápida. En esta sección del SDK, vamos a revisar todos los métodos del SDK disponibles para subir objetos en Stratus usando Transfer Manager.

Obtener instancia de Transfer Manager

Para realizar operaciones de transfer manager, necesitas obtener una instancia de objeto de transfer manager. Nos referiremos a esta instancia del componente en varios fragmentos de código donde trabajamos con operaciones de transfer manager realizadas en objetos almacenados en un bucket en Stratus. Parámetro utilizado bucket: Esta es la instancia de bucket que necesitas haber inicializado anteriormente usando este método del SDK. Asegúrate de que los siguientes paquetes estén importados

from zcatalyst_sdk.stratus.transfer_manager import TransferManager

transfer_manager = TranferManager(bucket)

Subir un objeto usando Transfer Manager

En esta sección vamos a revisar los métodos del SDK que te permitirán subir exitosamente un objeto grande a un bucket en Stratus. La función de subida multipart subirá un archivo grande al bucket en múltiples solicitudes HTTPS. Todas estas solicitudes se combinarán en un solo objeto una vez que todas las partes individuales hayan sido subidas.

init_ins = transfer_manager.create_multipart_instance(key="")

Si necesitas crear una instancia para una operación de subida multipart ya inicializada, entonces copia y usa el fragmento de código que se muestra a continuación.

init_ins = transfer_manager.create_multipart_instance(key="", upload_id="")

Realizar subida Multipart para partes del objeto

En el siguiente método del SDK, vamos a realizar subidas de las partes individuales del objeto. Cada parte tendrá un part_number distinto que varía entre 1 y 1000. Aunque esto representa el orden de las partes, estas partes no necesariamente se subirán en secuencia. Estas partes se combinarán en secuencia una vez que la subida de todas las partes de los objetos esté completa. Parámetros utilizados

• part_number: Tendrá el orden de las partes que se están subiendo.
• body: Contendrá los datos/contenido del objeto.

upload_res = init_ins.upload_part(body=open('file_path','rb'), part_number=3)
print(upload_res)

Obtener resumen de subida Multipart

El siguiente método del SDK se puede usar para obtener un resumen operativo de todas las partes subidas. Para ver el resumen, usaremos el método get_upload_summary().

summary_res = init_ins.get_upload_summary()
print(summary_res)

Completar subida Multipart del objeto

El siguiente método nos permite terminar el proceso multipart una vez que todas las partes se han subido exitosamente. Para completar el proceso pasaremos el upload_id al método complete_upload().

complete_res = init_ins.complete_upload()
print(complete_res)

Subir un objeto envolviendo toda la funcionalidad de Transfer Manager

El siguiente método del SDK actúa como un envoltorio, donde toda la operación de subida del transfer manager se lleva a cabo sin emplear múltiples pasos. Usando este método, el objeto se divide en múltiples partes, se sube al bucket en múltiples partes y luego se combina una vez que todas las partes están subidas.

upload_res = transfer_res.put_object_as_parts(key='', body=open('file_path', 'rb'), part_size=50)
print(upload_res)

Generar URL prefirmada para subir un objeto

Las URLs prefirmadas son URLs seguras que los usuarios autenticados pueden compartir con sus usuarios no autenticados. Esta URL proporcionará a los usuarios no autenticados autorización temporal para acceder a los objetos. La referencia de Bucket utilizada en el siguiente fragmento de código es la instancia del componente.

pre_signed_url_res = bucket.generate_presigned_url("sam/out/sample.txt",url_action='PUT',expiry_in_sec='300', active_from='1023453725828')
print(pre_signed_url_res)

Respuesta de ejemplo para generar una URL prefirmada para subida

{
  "signature": "https://sadi-development.zohostratus.com/_signed/code.txt?organizationId=96862383&stsCredential=96858154-96862383&stsDate=1747899245773&stsExpiresAfter=300&stsSignedHeaders=host&stsSignature=YBPoNE9txCIUWWX3ntdgVd95VTt1jGFlSuvnTRFbCMQ"
file_path = "/Users/ranjitha-18338/Documents/Pyhton-SDK/filestore2.0/output.txt",
  "expiry_in_seconds": "300",
  "active_from": "1726492859577"
}

Fragmento de ejemplo que ilustra el uso de URL prefirmada para subir un objeto

import requests

#Reemplazar con tu URL prefirmada real
url = "https://sadi-development.zohostratus.com/_signed/code.txt?organizationId=96862383&stsCredential=96858154-96862383&stsDate=1747899245773&stsExpiresAfter=300&stsSignedHeaders=host&stsSignature=YBPoNE9txCIUWWX3ntdgVd95VTt1jGFlSuvnTRFbCMQ"
#Ruta al archivo local que deseas subir
file_path = "file_path"
#Establecer los encabezados requeridos
headers = {
    # 'Content-Type': 'text/plain',  # Especificar el tipo de contenido del archivo
    # 'overwrite': 'true',           # Encabezado personalizado opcional para indicar sobrescritura (si lo requiere el servidor)
}
#Abrir el archivo en modo de lectura binaria y enviar una solicitud PUT para subirlo
with open(file_path, 'rb') as f:
    files = {'file': f}  #Crear un payload de archivo
    response = requests.put(url, headers=headers, files=files)
    #Verificar el estado de la respuesta
    if response.status == 200:
        print('Object uploaded successfully')
    else:
        print('Object upload failed')