Todos os produtos
Search
Central de documentação

Object Storage Service:Document format conversion

Última atualização: Jul 03, 2026

Converta documentos armazenados no OSS para formatos de destino, como PNG, JPG, PDF ou TXT, e salve os resultados em um caminho especificado.

Cenários

  • Visualização online: converta documentos PDF, Word, Excel ou PPT em imagens para visualização direta em dispositivos web ou móveis, sem necessidade de download.

  • Compatibilidade entre plataformas: visualize documentos perfeitamente em diferentes dispositivos e sistemas operacionais.

Tipos de arquivo de entrada compatíveis

Tipo de arquivo

Extensão do arquivo

Word

doc, docx, wps, wpss, docm, dotm, dot, dotx, html

PPT

pptx, ppt, pot, potx, pps, ppsx, dps, dpt, pptm, potm, ppsm, dpss

Excel

xls, xlt, et, ett, xlsx, xltx, csv, xlsb, xlsm, xltm, ets

PDF

pdf

Primeiros passos

Pré-requisitos

Converter formato de documento

Use o OSS SDK for Java, Python ou Go para chamar a API de conversão de documentos e salvar os resultados em um bucket especificado.

Java

É necessário o OSS SDK for Java V3.17.4 ou posterior.

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AsyncProcessObjectRequest;
import com.aliyun.oss.model.AsyncProcessObjectResult;
import com.aliyuncs.exceptions.ClientException;

import java.util.Base64;

public class Demo1 {
    public static void main(String[] args) throws ClientException {
        // Specify the endpoint of the region in which the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain a credential from the 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.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket.
        String bucketName = "examplebucket";
        // Specify the name of the output object.
        String targetKey = "dest.png";
        // Specify the name of the source document.
        String sourceKey = "src.docx";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer in use, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Create a style variable of the string type to store document conversion parameters.
            String style = String.format("doc/convert,target_png,source_docx");
            // Create an asynchronous processing instruction.
            String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
            String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetKey.getBytes());
            String process = String.format("%s|sys/saveas,b_%s,o_%s", style, bucketEncoded, targetEncoded);
            // Create an AsyncProcessObjectRequest object.
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
            // Execute the asynchronous processing task.
            AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
            System.out.println("EventId: " + response.getEventId());
            System.out.println("RequestId: " + response.getRequestId());
            System.out.println("TaskId: " + response.getTaskId());

        } finally {
            // Close your OSSClient.
            ossClient.shutdown();
        }
    }
}

Python

É necessário o OSS SDK for Python 2.18.4 ou posterior.

# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # Obtain the temporary access credentials from the environment variables. Before you execute 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 for 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 Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
    region = 'cn-hangzhou'

    # Specify the name of the bucket. Example: examplebucket.
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

    # Specify the name of the source document.
    source_key = 'src.docx'

    # Specify the name of the output object.
    target_key = 'dest.png'

    # Create a style variable of the string type to store document conversion parameters.
    animation_style = 'doc/convert,target_png,source_docx'

    # Create a processing instruction, in which the name of the bucket and the name of the output object are Base64-encoded.
    bucket_name_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
    target_key_encoded = base64.urlsafe_b64encode(target_key.encode()).decode().rstrip('=')
    process = f"{animation_style}|sys/saveas,b_{bucket_name_encoded},o_{target_key_encoded}"

    try:
        # Execute the asynchronous processing task.
        result = bucket.async_process_object(source_key, process)
        print(f"EventId: {result.event_id}")
        print(f"RequestId: {result.request_id}")
        print(f"TaskId: {result.task_id}")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

Go

É necessário o OSS SDK for Go 3.0.2 ou posterior.

package main

import (
    "encoding/base64"
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "log"
)

func main() {
    // Obtain the temporary access credentials from the environment variables. Before you execute the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // Create an OSSClient instance.
    // 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. Specify your actual endpoint.
    // Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
    client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // Specify the name of the bucket. Example: examplebucket.
    bucketName := "examplebucket"

    bucket, err := client.Bucket(bucketName)
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }

    // Specify the name of the source document.
    sourceKey := "src.docx"
    // Specify the name of the output object.
    targetKey := "dest.png"

    // Create a style variable of the string type to store document conversion parameters.
    animationStyle := "doc/convert,target_png,source_docx"

    // Create a processing instruction, in which the name of the bucket and the name of the output object are Base64-encoded.
    bucketNameEncoded := base64.URLEncoding.EncodeToString([]byte(bucketName))
    targetKeyEncoded := base64.URLEncoding.EncodeToString([]byte(targetKey))
    process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v", animationStyle, bucketNameEncoded, targetKeyEncoded)

    // Execute the asynchronous processing task.
    result, err := bucket.AsyncProcessObject(sourceKey, process)
    if err != nil {
    log.Fatalf("Failed to async process object: %s", err)
    }

    fmt.Printf("EventId: %s\n", result.EventId)
    fmt.Printf("RequestId: %s\n", result.RequestId)
    fmt.Printf("TaskId: %s\n", result.TaskId)
}

Descrição dos parâmetros

Ação: doc/convert

Parâmetros:

Nome do parâmetro

Tipo

Obrigatório

Descrição

target

string

Sim

Formato do objeto de saída. Valores válidos:

  • pdf

  • png

  • jpg

  • txt

source

string

Não

Formato do arquivo de origem. O padrão é a extensão do nome do objeto. Valores válidos:

  • docx (obrigatório ao converter documentos HTML)

  • doc

  • pptx

  • ppt

  • pdf

  • xlsx

  • xls

pages

string

Não

Números das páginas a converter.

Exemplo: 1,2,4-10 indica a conversão da página 1, página 2 e das páginas 4 a 10.

Use sys/saveas para salvar documentos convertidos em um bucket especificado. Consulte Salvar como. Para receber o resultado da conversão, use o parâmetro notify. Consulte Notificações.

Notificações de eventos

A conversão de documentos é assíncrona. Para receber o resultado do processamento sem polling, configure notificações de eventos com o Simple Message Queue (SMQ, anteriormente MNS).

Configurar notificações de eventos

Primeiro, crie um tópico de mensagens na mesma região do bucket. Consulte Início rápido para modelo baseado em tópicos. Codifique o nome do tópico em Base64 seguro para URL. Por exemplo, test-topic torna-se dGVzdC10b3BpYw.

Código de exemplo

Os OSS SDKs para Java, Python e Go oferecem suporte à conversão de documentos.

Java

É necessário o OSS SDK for Java V3.17.4 ou posterior.

import com.aliyun.oss.ClientBuilderConfiguration;
import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.common.auth.CredentialsProviderFactory;
import com.aliyun.oss.common.auth.EnvironmentVariableCredentialsProvider;
import com.aliyun.oss.common.comm.SignVersion;
import com.aliyun.oss.model.AsyncProcessObjectRequest;
import com.aliyun.oss.model.AsyncProcessObjectResult;
import com.aliyuncs.exceptions.ClientException;

import java.util.Base64;

public class Demo1 {
    public static void main(String[] args) throws ClientException {
        // Specify the endpoint of the region in which the bucket is located.
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
        // Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
        String region = "cn-hangzhou";
        // Obtain a credential from the 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.
        EnvironmentVariableCredentialsProvider credentialsProvider = CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();
        // Specify the name of the bucket.
        String bucketName = "examplebucket";
        // Specify the name of the output object.
        String targetKey = "dest.png";
        // Specify the name of the source document.
        String sourceKey = "src.docx";

        // Create an OSSClient instance.
        // When the OSSClient instance is no longer in use, call the shutdown method to release resources.
        ClientBuilderConfiguration clientBuilderConfiguration = new ClientBuilderConfiguration();
        clientBuilderConfiguration.setSignatureVersion(SignVersion.V4);
        OSS ossClient = OSSClientBuilder.create()
                .endpoint(endpoint)
                .credentialsProvider(credentialsProvider)
                .clientConfiguration(clientBuilderConfiguration)
                .region(region)
                .build();

        try {
            // Create a style variable of the string type to store document conversion parameters.
            String style = String.format("doc/convert,target_png,source_docx");
            // Create an asynchronous processing instruction.
            String bucketEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(bucketName.getBytes());
            String targetEncoded = Base64.getUrlEncoder().withoutPadding().encodeToString(targetKey.getBytes());
            String process = String.format("%s|sys/saveas,b_%s,o_%s/notify,topic_dGVzdC10b3BpYw", style, bucketEncoded, targetEncoded);
            // Create an AsyncProcessObjectRequest object.
            AsyncProcessObjectRequest request = new AsyncProcessObjectRequest(bucketName, sourceKey, process);
            // Execute the asynchronous processing task.
            AsyncProcessObjectResult response = ossClient.asyncProcessObject(request);
            System.out.println("EventId: " + response.getEventId());
            System.out.println("RequestId: " + response.getRequestId());
            System.out.println("TaskId: " + response.getTaskId());

        } finally {
            // Close your OSSClient.
            ossClient.shutdown();
        }
    }
}

Python

É necessário o OSS SDK for Python 2.18.4 ou posterior.

# -*- coding: utf-8 -*-
import base64
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

def main():
    # Obtain the temporary access credentials from the environment variables. Before you execute 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 for 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 Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
    region = 'cn-hangzhou'

    # Specify the name of the bucket. Example: examplebucket.
    bucket = oss2.Bucket(auth, endpoint, 'examplebucket', region=region)

    # Specify the name of the source document.
    source_key = 'src.docx'

    # Specify the name of the output object.
    target_key = 'dest.png'

    # Create a style variable of the string type to store document conversion parameters.
    animation_style = 'doc/convert,target_png,source_docx'

    # Create a processing instruction, in which the name of the bucket and the name of the output object are Base64-encoded.
    bucket_name_encoded = base64.urlsafe_b64encode('examplebucket'.encode()).decode().rstrip('=')
    target_key_encoded = base64.urlsafe_b64encode(target_key.encode()).decode().rstrip('=')
    process = f"{animation_style}|sys/saveas,b_{bucket_name_encoded},o_{target_key_encoded}/notify,topic_dGVzdC10b3BpYw"

    try:
        # Execute the asynchronous processing task.
        result = bucket.async_process_object(source_key, process)
        print(f"EventId: {result.event_id}")
        print(f"RequestId: {result.request_id}")
        print(f"TaskId: {result.task_id}")
    except Exception as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    main()

Go

É necessário o OSS SDK for Go 3.0.2 ou posterior.

package main

import (
    "encoding/base64"
    "fmt"
    "os"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "log"
)

func main() {
    // Obtain the temporary access credentials from the environment variables. Before you execute the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // Create an OSSClient instance.
    // 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. Specify your actual endpoint.
    // Specify the ID of the Alibaba Cloud region in which the bucket is located. Example: cn-hangzhou.
    client, err := oss.New("https://oss-cn-hangzhou.aliyuncs.com", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("cn-hangzhou"))
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // Specify the name of the bucket. Example: examplebucket.
    bucketName := "examplebucket"

    bucket, err := client.Bucket(bucketName)
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }

    // Specify the name of the source document.
    sourceKey := "src.docx"
    // Specify the name of the output object.
    targetKey := "dest.png"

    // Create a style variable of the string type to store document conversion parameters.
    animationStyle := "doc/convert,target_png,source_docx"

    // Create a processing instruction, in which the name of the bucket and the name of the output object are Base64-encoded.
    bucketNameEncoded := base64.URLEncoding.EncodeToString([]byte(bucketName))
    targetKeyEncoded := base64.URLEncoding.EncodeToString([]byte(targetKey))
    process := fmt.Sprintf("%s|sys/saveas,b_%v,o_%v/notify,topic_dGVzdC10b3BpYw", animationStyle, bucketNameEncoded, targetKeyEncoded)

    // Execute the asynchronous processing task.
    result, err := bucket.AsyncProcessObject(sourceKey, process)
    if err != nil {
    log.Fatalf("Failed to async process object: %s", err)
    }

    fmt.Printf("EventId: %s\n", result.EventId)
    fmt.Printf("RequestId: %s\n", result.RequestId)
    fmt.Printf("TaskId: %s\n", result.TaskId)
}

APIs relacionadas

Para personalizações avançadas, chame a API RESTful diretamente. Inclua o cálculo de assinatura no código. Consulte Versão de Assinatura 4 (Recomendado).

Converter formato de documento

  • Objeto de origem

    • Formato do documento: DOCX

    • Nome do documento: example.docx

  • Objeto de destino

    • Formato do objeto: PNG

    • Caminho de armazenamento: oss://test-bucket/doc_images/{index}.png

      • b_dGVzdC1idWNrZXQ=: após a conclusão da conversão, salva em um bucket chamado test-bucket (dGVzdC1idWNrZXQ= é o valor codificado em Base64 de test-bucket).

      • o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw==: o objeto usa a variável {index} para salvar imagens com os números de página de example.docx como nomes de arquivo no diretório doc_images (ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw== é o valor codificado em Base64 de doc_images/{index}.png).

    • Notificação de conclusão da conversão: envia para o tópico do Simple Message Queue (SMQ, anteriormente MNS) chamado test-topic

Exemplo de processamento

// Convert the example.docx file to PNG format image files.
POST /example.docx?x-oss-async-process HTTP/1.1
Host: doc-demo.oss-cn-hangzhou.aliyuncs.com
Date: Fri, 28 Oct 2022 06:40:10 GMT
Authorization: SignatureValue

x-oss-async-process=doc/convert,target_png,source_docx|sys/saveas,b_dGVzdC1idWNrZXQ=,o_ZG9jX2ltYWdlcy97aW5kZXh9LnBuZw==/notify,topic_dGVzdC10b3BpYw

Observações

  • A conversão de documentos oferece suporte apenas ao processamento assíncrono (x-oss-async-process).

  • Não há suporte para acesso anônimo.

  • O tamanho máximo de arquivo para conversão de formato de documento é 200 MB. Esse limite não pode ser ajustado.

Perguntas frequentes

A conversão de documentos do OSS permite especificar o conteúdo de uma planilha do Excel?

Não. A conversão de documentos do OSS converte todas as planilhas de um arquivo Excel. Para converter uma planilha específica, chame a API CreateOfficeConversionTask - Criar tarefa de conversão de documento do IMM com o parâmetro SheetIndex.

Referências

Conversão de formato de documento.