Asynchronous processing with OSS SDK for Python V2 - Object Storage Service

Asynchronous processing (x-oss-async-process) lets a program continue executing other tasks without waiting for a task to complete. Use OSS SDK for Python V2 to asynchronously process data, such as document conversion, video transcoding, and video merging.

Usage notes

The sample code uses the region ID cn-hangzhou (China (Hangzhou)) with a public endpoint. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For more information about the OSS regions and endpoints, see Regions and Endpoints.

Method definition

async_process_object(request: AsyncProcessObjectRequest, **kwargs) → AsyncProcessObjectResult

Request parameters

Parameter	Type	Description
request	AsyncProcessObjectRequest	The request parameters for the AsyncProcessObject operation. AsyncProcessObjectRequest.

Response parameters

Type	Description
AsyncProcessObjectResult	The response object. AsyncProcessObjectResult.

Complete method definition: async_process_object.

Sample code

The following example converts a document format:

import base64
import argparse
import alibabacloud_oss_v2 as oss

# Create a parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="async process object sample")

# Specify command-line arguments, including the required region, source bucket name, endpoint, and source object name, destination object name, and destination bucket name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--target_key', help='Specify the name of the processed object.', required=True)
parser.add_argument('--target_bucket', help='Specify the name of the bucket used to store processed object.', required=True)

def main():
    # Parse command-line arguments.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region provided in the command line.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define a style for converting DOCX to PNG.
    style = "doc/convert,target_png,source_docx"

    # Base64-encode the destination bucket name and object name to make them URL-safe.
    target_bucket_base64 = base64.b64encode(args.target_bucket.encode()).decode()
    target_key_base64 = base64.b64encode(args.target_key.encode()).decode()

    # Create a process instruction that includes the style and destination path.
    process = f"{style}|sys/saveas,o_{target_key_base64},b_{target_bucket_base64}"

    # Send the request to asynchronously process the object and store the resulting object in the destination bucket.
    result = client.async_process_object(oss.AsyncProcessObjectRequest(
        bucket=args.bucket,  # The source bucket name.
        key=args.key,  # The source object name.
        process=process, # The processing instruction.
    ))

    # Display the status code and other result information to check the request status and result.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' event id: {result.event_id},'
          f' task id: {result.task_id},'
          f' process request id: {result.process_request_id},'
          )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

Common scenarios

Video transcoding

Video transcoding changes the encoding and container formats of a video, reducing file size by adjusting resolution and bit rate. The following example transcodes a video:

import base64
import argparse
import alibabacloud_oss_v2 as oss

# Create the parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="async process object sample")

# Specify command-line arguments, including the required region, source bucket name, endpoint, and source object name, destination object name, and destination bucket name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--target_key', help='Specify the name of the processed object.', required=True)
parser.add_argument('--target_bucket', help='Specify the name of the bucket used to store processed object.', required=True)

def main():
    # Parse command-line arguments.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region provided in the command line.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define a style for video processing. In this example, the video transcoding settings include the container format, encoding format, resolution, video bit rate, frame rate, audio codec, and audio bit rate.
    style = "video/convert,f_avi,vcodec_h265,s_1920x1080,vb_2000000,fps_30,acodec_aac,ab_100000,sn_1"

    # Base64-encode the destination bucket name and object name to make them URL-safe.
    target_bucket_base64 = base64.b64encode(args.target_bucket.encode()).decode()
    target_key_base64 = base64.b64encode(args.target_key.encode()).decode()

    # Create a process instruction that includes the style and destination path.
    process = f"{style}|sys/saveas,o_{target_key_base64},b_{target_bucket_base64}"

    # Send the request to asynchronously process the object and store the resulting object in the destination bucket.
    result = client.async_process_object(oss.AsyncProcessObjectRequest(
        bucket=args.bucket,  # The source bucket name.
        key=args.key,  # The source object name.
        process=process, # The processing instruction.
    ))

    # Display the status code and other result information to check the request status and result.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' event id: {result.event_id},'
          f' task id: {result.task_id},'
          f' process request id: {result.process_request_id},'
          )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

Video-to-animated-image conversion

Video-to-animated-image conversion extracts frames from a video and produces GIF or WebP animations. The following example creates an animated image from a video:

import base64
import argparse
import alibabacloud_oss_v2 as oss

# Create the parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="async process object sample")

# Specify command-line arguments, including the required region, source bucket name, endpoint, and source object name, destination object name, and destination bucket name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--target_key', help='Specify the name of the processed object.', required=True)
parser.add_argument('--target_bucket', help='Specify the name of the bucket used to store processed object.', required=True)

def main():
    # Parse command-line arguments.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region provided in the command line.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define a style for converting the video to an animated image. In this example, the settings include the GIF width, the GIF height, and the time interval for capturing frames.
    style = "video/animation,f_gif,w_100,h_100,inter_1000"

    # Base64-encode the destination bucket name and object name to make them URL-safe.
    target_bucket_base64 = base64.b64encode(args.target_bucket.encode()).decode()
    target_key_base64 = base64.b64encode(args.target_key.encode()).decode()

    # Create a process instruction that includes the style and destination path.
    process = f"{style}|sys/saveas,o_{target_key_base64},b_{target_bucket_base64}"

    # Send the request to asynchronously process the object and store the resulting object in the destination bucket.
    result = client.async_process_object(oss.AsyncProcessObjectRequest(
        bucket=args.bucket,  # The source bucket name.
        key=args.key,  # The source object name.
        process=process, # The processing instruction.
    ))

    # Display the status code and other result information to check the request status and result.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' event id: {result.event_id},'
          f' task id: {result.task_id},'
          f' process request id: {result.process_request_id},'
          )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

Frame capture

Frame capture extracts video frames and converts them to a specified image format. The following example captures frames from a video:

import base64
import argparse
import alibabacloud_oss_v2 as oss

# Create the parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="async process object sample")

# Specify command-line arguments, including the required region, source bucket name, endpoint, and source object name, destination object name, and destination bucket name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--target_key', help='Specify the name of the processed object.', required=True)
parser.add_argument('--target_bucket', help='Specify the name of the bucket used to store processed object.', required=True)

def main():
    # Parse command-line arguments.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region provided in the command line.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define a style for frame capture.
    style = "video/snapshots,f_jpg,w_100,h_100,scaletype_crop,inter_10000"

    # Base64-encode the destination bucket name and object name to make them URL-safe.
    target_bucket_base64 = base64.b64encode(args.target_bucket.encode()).decode()
    target_key_base64 = base64.b64encode(args.target_key.encode()).decode()

    # Create a process instruction that includes the style and destination path.
    process = f"{style}|sys/saveas,o_{target_key_base64},b_{target_bucket_base64}"

    # Send the request to asynchronously process the object and store the resulting object in the destination bucket.
    result = client.async_process_object(oss.AsyncProcessObjectRequest(
        bucket=args.bucket,  # The source bucket name.
        key=args.key,  # The source object name.
        process=process, # The processing instruction.
    ))

    # Display the status code and other result information to check the request status and result.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' event id: {result.event_id},'
          f' task id: {result.task_id},'
          f' process request id: {result.process_request_id},'
          )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

Audio transcoding

Audio transcoding converts audio files between formats. The following example transcodes an audio file:

import base64
import argparse
import alibabacloud_oss_v2 as oss

# Create the parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="async process object sample")

# Specify command-line arguments, including the required region, source bucket name, endpoint, and source object name, destination object name, and destination bucket name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--target_key', help='Specify the name of the processed object.', required=True)
parser.add_argument('--target_bucket', help='Specify the name of the bucket used to store processed object.', required=True)

def main():
    # Parse command-line arguments.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region provided in the command line.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Define a style for audio transcoding.
    style = "audio/convert,ss_10000,t_60000,f_aac,ab_96000"

    # Base64-encode the destination bucket name and object name to make them URL-safe.
    target_bucket_base64 = base64.b64encode(args.target_bucket.encode()).decode()
    target_key_base64 = base64.b64encode(args.target_key.encode()).decode()

    # Create a process instruction that includes the style and destination path.
    process = f"{style}|sys/saveas,o_{target_key_base64},b_{target_bucket_base64}"

    # Send the request to asynchronously process the object and store the resulting object in the destination bucket.
    result = client.async_process_object(oss.AsyncProcessObjectRequest(
        bucket=args.bucket,  # The source bucket name.
        key=args.key,  # The source object name.
        process=process, # The processing instruction.
    ))

    # Display the status code and other result information to check the request status and result.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' event id: {result.event_id},'
          f' task id: {result.task_id},'
          f' process request id: {result.process_request_id},'
          )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

Blind watermark decoding

The following example decodes a blind watermark from an image:

import base64
import argparse
import alibabacloud_oss_v2 as oss

# Create a parser for parsing command-line arguments and describe the purpose of the script.
parser = argparse.ArgumentParser(description="async process object sample")

# Specify command-line arguments, including the required region, source bucket name, endpoint, and source object name, destination object name, and destination bucket name.
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--target_key', help='Specify the name of the processed object.', required=True)
parser.add_argument('--target_bucket', help='Specify the name of the bucket used to store processed object.', required=True)

def main():
    # Parse command-line arguments.
    args = parser.parse_args()

    # Obtain access credentials from environment variables for authentication.
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    # Use the default configuration to create a cfg object and specify the credential provider.
    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider

    # Set the region attribute of the cfg object to the region provided in the command line.
    cfg.region = args.region

    # If a custom endpoint is provided, update the endpoint attribute of the cfg object with the provided endpoint.
    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    # Use the preceding settings to initialize the OSSClient instance.
    client = oss.Client(cfg)

    # Decode the watermark from the specified image.
    style = "image/deblindwatermark,s_low,t_text"

    # Base64-encode the destination bucket name and object name to make them URL-safe.
    target_bucket_base64 = base64.b64encode(args.target_bucket.encode()).decode()
    target_key_base64 = base64.b64encode(args.target_key.encode()).decode()

    # Create a process instruction that includes the style and destination path.
    process = f"{style}|sys/saveas,o_{target_key_base64},b_{target_bucket_base64}"

    # Send the request to asynchronously process the object and store the resulting object in the destination bucket.
    result = client.async_process_object(oss.AsyncProcessObjectRequest(
        bucket=args.bucket,  # The source bucket name.
        key=args.key,  # The source object name.
        process=process, # The processing instruction.
    ))

    # Display the status code and other result information to check the request status and result.
    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' event id: {result.event_id},'
          f' task id: {result.task_id},'
          f' process request id: {result.process_request_id},'
          )

# Call the main function to start the processing logic when the script is directly run.
if __name__ == "__main__":
    main()  # Specify the entry point of the script. The control flow starts here.

References

For more information about asynchronous processing, see Asynchronous processing.
Complete sample code: async_process_object.py.