como usar o sdk go do oss v2 para fazer upload de arquivos - Object Storage Service: Central de Documentação do Alibaba Cloud

Este tópico descreve como usar o módulo Uploader do SDK Go V2 para fazer upload de arquivos.

Notas de uso

O código de exemplo neste tópico usa o ID da região cn-hangzhou para a região China (Hangzhou). Por padrão, um endpoint público é usado para acessar recursos em um bucket. Se você quiser acessar recursos do bucket usando outros serviços da Alibaba Cloud na mesma região, use o endpoint interno. Para obter mais informações sobre regiões e endpoints do OSS, consulte Regiões e endpoints.
Neste tópico, as credenciais de acesso são recuperadas de variáveis de ambiente. Para obter mais informações sobre como configurar credenciais de acesso, consulte Configurar credenciais de acesso.
Para fazer upload de um arquivo grande, você deve ter a permissão oss:PutObject. Para obter mais informações, consulte Anexar uma política personalizada a um usuário RAM.

Definição do método

Introdução ao Uploader

O Uploader no SDK Go V2 simplifica uploads de arquivos fornecendo uma operação de alto nível que oculta os detalhes de implementação subjacentes.

O Uploader usa a operação de upload multipart para dividir um arquivo grande ou fluxo em várias partes menores e faz upload das partes simultaneamente para melhorar o desempenho.
O Uploader também fornece o recurso de upload retomável. Este recurso registra o status das partes concluídas durante o processo de upload. Se o upload do arquivo falhar devido a problemas como interrupções de rede ou exceções de programa, você pode retomar o upload a partir do registro do ponto de interrupção na próxima vez que tentar fazer upload do arquivo.

O código de exemplo a seguir mostra como usar o Uploader:

type Uploader struct {
  ...
}

// Cria um novo uploader.
func (c *Client) NewUploader(optFns ...func(*UploaderOptions)) *Uploader 

// Faz upload de um fluxo de arquivo.
func (u *Uploader) UploadFrom(ctx context.Context, request *PutObjectRequest, body io.Reader, optFns ...func(*UploaderOptions)) (*UploadResult, error)

// Faz upload de um arquivo local.
func (u *Uploader) UploadFile(ctx context.Context, request *PutObjectRequest, filePath string, optFns ...func(*UploaderOptions)) (*UploadResult, error)

Parâmetros de solicitação

Parâmetro	Tipo	Descrição
ctx	context.Context	O contexto da solicitação.
request	*PutObjectRequest	Os parâmetros de solicitação para fazer upload de um objeto. Os parâmetros são os mesmos da operação PutObject. Para obter mais informações, consulte PutObjectRequest.
body	io.Reader	O fluxo a ser carregado. Se o parâmetro body suportar apenas o tipo io.Reader, você deve armazenar os dados em buffer na memória antes de poder fazer upload dos dados. Se o parâmetro body suportar os tipos io.Reader, io.Seeker e io.ReaderAt, você não precisa armazenar os dados em buffer na memória.
filePath	string	O caminho do arquivo local.
optFns	...func(*UploaderOptions)	(Opcional) Opções de configuração.

A tabela a seguir descreve os parâmetros comuns de UploaderOptions.

Parâmetro	Tipo	Descrição
PartSize	int64	O tamanho da parte. O valor padrão é 6 MiB.
ParallelNum	int	O número de tarefas de upload simultâneas. O valor padrão é 3. Este parâmetro especifica o limite de concorrência para uma única chamada, não o limite de concorrência global.
LeavePartsOnError	bool	Especifica se deve reter as partes carregadas quando um upload falha. Por padrão, as partes carregadas não são retidas.
EnableCheckpoint	bool	Especifica se deve habilitar o recurso de upload retomável. Por padrão, este recurso está desabilitado. Nota O parâmetro EnableCheckpoint é válido apenas para a operação UploadFile e não é suportado pela operação UploadFrom.
CheckpointDir	string	O caminho onde o arquivo de ponto de verificação é salvo. Exemplo: /local/dir/. Este parâmetro é válido somente quando EnableCheckpoint é definido como true.

Quando você instancia um Uploader usando NewUploader, pode especificar opções de configuração para personalizar o comportamento do upload. Essas opções podem ser definidas para a instância do Uploader para aplicar a todos os uploads, ou especificadas para cada operação de upload individual.

Defina os parâmetros de configuração para o Uploader

u := client.NewUploader(func(uo *oss.UploaderOptions) {
  uo.PartSize = 10 * 1024 * 1024
})

Defina os parâmetros de configuração para cada solicitação de upload

request := &oss.PutObjectRequest{Bucket: oss.Ptr("bucket"), Key: oss.Ptr("key")}
result, err := u.UploadFile(context.TODO(), request, "/local/dir/example", func(uo *oss.UploaderOptions) {
  uo.PartSize = 10 * 1024 * 1024
})

Exemplos

Você pode usar o código de exemplo a seguir para fazer upload de um arquivo local para um bucket usando o Uploader.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Defina variáveis globais.
var (
	region     string // A região de armazenamento.
	bucketName string // O nome do bucket.
	objectName string // O nome do objeto.
)

// A função init é usada para inicializar parâmetros de linha de comando.
func init() {
	flag.StringVar(&region, "region", "", "A região em que o bucket está localizado.")
	flag.StringVar(&bucketName, "bucket", "", "O nome do bucket.")
	flag.StringVar(&objectName, "object", "", "O nome do objeto de origem.")
}

func main() {
	// Analise os parâmetros da linha de comando.
	flag.Parse()

	// Verifique se o nome do bucket está vazio.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do bucket obrigatório")
	}

	// Verifique se a região está vazia.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, região obrigatória")
	}

	// Verifique se o nome do objeto está vazio.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do objeto de origem obrigatório")
	}

	// Carregue as configurações padrão e defina o provedor de credenciais e a região.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Crie um cliente OSS.
	client := oss.NewClient(cfg)

	// Crie um uploader.
	u := client.NewUploader()

	// Defina o caminho do arquivo local. Você precisa substituir o caminho pelo caminho e nome do arquivo local real.
	localFile := "/Users/seuCaminhoLocal/seuNomeDeArquivo"

	// Faça o upload do arquivo.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("falha ao fazer upload do arquivo %v", err)
	}

	// Imprima o resultado do upload.
	log.Printf("resultado do upload do arquivo:%#v\n", result)
}

Cenários comuns

Habilite o recurso de upload retomável usando o uploader

Você pode usar o código de exemplo a seguir para habilitar o recurso de upload retomável definindo os parâmetros de configuração do Uploader.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Defina variáveis globais.
var (
	region     string // A região de armazenamento.
	bucketName string // O nome do bucket.
	objectName string // O nome do objeto.
)

// A função init é usada para inicializar parâmetros de linha de comando.
func init() {
	flag.StringVar(&region, "region", "", "A região em que o bucket está localizado.")
	flag.StringVar(&bucketName, "bucket", "", "O nome do bucket.")
	flag.StringVar(&objectName, "object", "", "O nome do objeto de origem.")
}

func main() {
	// Analise os parâmetros da linha de comando.
	flag.Parse()

	// Verifique se o nome do bucket está vazio.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do bucket obrigatório")
	}

	// Verifique se a região está vazia.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, região obrigatória")
	}

	// Verifique se o nome do objeto está vazio.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do objeto de origem obrigatório")
	}

	// Carregue as configurações padrão e defina o provedor de credenciais e a região.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Crie um cliente OSS.
	client := oss.NewClient(cfg)

	// Crie um uploader e habilite o recurso de upload retomável.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.CheckpointDir = "/Users/seuCaminhoLocal/pontoDeVerificacao/" // Especifique o caminho para salvar o arquivo de ponto de verificação.
		uo.EnableCheckpoint = true        // Habilite o upload retomável.
	})

	// Defina o caminho do arquivo local. Você precisa substituir o caminho pelo caminho e nome do arquivo local real.
	localFile := "/Users/seuCaminhoLocal/seuNomeDeArquivo"

	// Faça o upload do arquivo.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("falha ao fazer upload do arquivo %v", err)
	}

	// Imprima o resultado do upload.
	log.Printf("resultado do upload do arquivo:%#v\n", result)
}

Use o uploader para fazer upload de um fluxo de arquivo local

Você pode usar o código de exemplo a seguir para fazer upload de um fluxo de arquivo local usando o Uploader.

package main

import (
	"context"
	"flag"
	"io"
	"log"
	"os"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Defina variáveis globais.
var (
	region     string // A região de armazenamento.
	bucketName string // O nome do bucket.
	objectName string // O nome do objeto.
)

// A função init é usada para inicializar parâmetros de linha de comando.
func init() {
	flag.StringVar(&region, "region", "", "A região em que o bucket está localizado.")
	flag.StringVar(&bucketName, "bucket", "", "O nome do bucket.")
	flag.StringVar(&objectName, "object", "", "O nome do objeto.")
}

func main() {
	// Analise os parâmetros da linha de comando.
	flag.Parse()

	// Verifique se o nome do bucket está vazio.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do bucket obrigatório")
	}

	// Verifique se a região está vazia.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, região obrigatória")
	}

	// Verifique se o nome do objeto está vazio.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do objeto obrigatório")
	}

	// Carregue as configurações padrão e defina o provedor de credenciais e a região.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Crie um cliente OSS.
	client := oss.NewClient(cfg)

	// Crie um uploader.
	u := client.NewUploader()

	// Substitua "/Users/seuCaminhoLocal/seuNomeDeArquivo" pelo caminho e nome de arquivo real, abra o arquivo local e crie uma instância io.Reader.
	file, err := os.Open("/Users/seuCaminhoLocal/seuNomeDeArquivo")
	if err != nil {
		log.Fatalf("falha ao abrir arquivo local %v", err)
	}
	defer file.Close()

	var r io.Reader = file

	// Faça o upload do fluxo de arquivo.
	result, err := u.UploadFrom(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName),
		},
		r, // O fluxo de arquivo a ser carregado.
	)

	if err != nil {
		log.Fatalf("falha ao fazer upload do fluxo de arquivo %v", err)
	}

	// Imprima o resultado do upload do fluxo de arquivo.
	log.Printf("upload do fluxo de arquivo, etag: %v\n", oss.ToString(result.ETag))
}

Use o uploader para definir o tamanho da parte e a concorrência

Você pode usar o código de exemplo a seguir para definir o tamanho da parte e a concorrência definindo os parâmetros de configuração do Uploader.

package main

import (
	"context"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Defina variáveis globais.
var (
	region     string // A região de armazenamento.
	bucketName string // O nome do bucket.
	objectName string // O nome do objeto.
)

// A função init é usada para inicializar parâmetros de linha de comando.
func init() {
	flag.StringVar(&region, "region", "", "A região em que o bucket está localizado.")
	flag.StringVar(&bucketName, "bucket", "", "O nome do bucket.")
	flag.StringVar(&objectName, "object", "", "O nome do objeto de origem.")
}

func main() {
	// Analise os parâmetros da linha de comando.
	flag.Parse()

	// Verifique se o nome do bucket está vazio.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do bucket obrigatório")
	}

	// Verifique se a região está vazia.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, região obrigatória")
	}

	// Verifique se o nome do objeto está vazio.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do objeto de origem obrigatório")
	}

	// Carregue as configurações padrão e defina o provedor de credenciais e a região.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Crie um cliente OSS.
	client := oss.NewClient(cfg)

	// Crie um uploader.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5     // Defina o tamanho da parte como 5 MB.
		uo.ParallelNum = 5                // Defina o número de uploads simultâneos como 5.
	})

	// Defina o caminho do arquivo local. Você precisa substituir o caminho pelo caminho e nome do arquivo local real.
	localFile := "/Users/seuCaminhoLocal/seuNomeDeArquivo"

	// Faça o upload do arquivo.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName)},
		localFile)
	if err != nil {
		log.Fatalf("falha ao fazer upload do arquivo %v", err)
	}

	// Imprima o resultado do upload.
	log.Printf("resultado do upload do arquivo:%#v\n", result)
}

Use o uploader para definir callbacks de upload

Use o código de exemplo a seguir para notificar um servidor de aplicativo após o upload de um arquivo.

package main

import (
	"context"
	"encoding/base64"
	"encoding/json"
	"flag"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Defina variáveis globais.
var (
	region     string // A região de armazenamento.
	bucketName string // O nome do bucket.
	objectName string // O nome do objeto.
)

// A função init é usada para inicializar parâmetros de linha de comando.
func init() {
	flag.StringVar(&region, "region", "", "A região em que o bucket está localizado.")
	flag.StringVar(&bucketName, "bucket", "", "O nome do bucket.")
	flag.StringVar(&objectName, "object", "", "O nome do objeto de origem.")
}

func main() {
	// Analise os parâmetros da linha de comando.
	flag.Parse()

	// Verifique se o nome do bucket está vazio.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do bucket obrigatório")
	}

	// Verifique se a região está vazia.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, região obrigatória")
	}

	// Verifique se o nome do objeto está vazio.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do objeto de origem obrigatório")
	}

	// Carregue as configurações padrão e defina o provedor de credenciais e a região.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Crie um cliente OSS.
	client := oss.NewClient(cfg)

	// Crie um uploader e habilite o recurso de upload retomável.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5 // Defina o tamanho da parte como 5 MB.
		uo.ParallelNum = 5            // Defina o número de uploads simultâneos como 5.
	})

	// Defina o caminho do arquivo local. Você precisa substituir o caminho pelo seu caminho de arquivo local real.
	localFile := "/Users/seuCaminhoLocal/seuNomeDeArquivo"

	// Defina os parâmetros de callback.
	callbackMap := map[string]string{
		"callbackUrl":      "https://example.com:23450/callback",                                                        // Defina o URL do servidor de callback. Exemplo: https://example.com:23450.
		"callbackBody":     "bucket=${bucket}&object=${object}&size=${size}&my_var_1=${x:my_var1}&my_var_2=${x:my_var2}", // Defina o corpo da solicitação de callback.
		"callbackBodyType": "application/x-www-form-urlencoded",                                                          // Defina o tipo do corpo da solicitação de callback.
	}

	// Converta os parâmetros de callback para JSON e depois execute a codificação Base64 para passá-los como parâmetros de callback.
	callbackStr, err := json.Marshal(callbackMap)
	if err != nil {
		log.Fatalf("falha ao converter mapa de callback: %v", err)
	}
	callbackBase64 := base64.StdEncoding.EncodeToString(callbackStr)

	// Defina parâmetros de callback personalizados.
	callbackVarMap := map[string]string{}
	callbackVarMap["x:my_var1"] = "isto é var 1"
	callbackVarMap["x:my_var2"] = "isto é var 2"

	// Converta os parâmetros de callback para JSON e depois execute a codificação Base64 para passá-los como parâmetros de callback.
	callbackVarStr, err := json.Marshal(callbackVarMap)
	if err != nil {
		log.Fatalf("falha ao converter variável de callback: %v", err)
	}
	callbackVarBase64 := base64.StdEncoding.EncodeToString(callbackVarStr)

	// Faça o upload do arquivo grande.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket:      oss.Ptr(bucketName),
			Key:         oss.Ptr(objectName),
			Callback:    oss.Ptr(callbackBase64),    // Especifique os parâmetros de callback.
			CallbackVar: oss.Ptr(callbackVarBase64), // Especifique os parâmetros de callback personalizados.
		},
		localFile)
	if err != nil {
		log.Fatalf("falha ao fazer upload do arquivo %v", err)
	}

	// Imprima o resultado do upload.
	log.Printf("resultado do upload do arquivo:%#v\n", result)
}

Use o uploader para exibir um gráfico de barra de progresso

package main

import (
	"context"
	"flag"
	"fmt"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// Defina variáveis globais.
var (
	region     string // A região de armazenamento.
	bucketName string // O nome do bucket.
	objectName string // O nome do objeto.
)

// A função init é usada para inicializar parâmetros de linha de comando.
func init() {
	flag.StringVar(&region, "region", "", "A região em que o bucket está localizado.")
	flag.StringVar(&bucketName, "bucket", "", "O nome do bucket.")
	flag.StringVar(&objectName, "object", "", "O nome do objeto de origem.")
}

func main() {
	// Analise os parâmetros da linha de comando.
	flag.Parse()

	// Verifique se o nome do bucket está vazio.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do bucket obrigatório")
	}

	// Verifique se a região está vazia.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, região obrigatória")
	}

	// Verifique se o nome do objeto está vazio.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("parâmetros inválidos, nome do objeto de origem obrigatório")
	}

	// Carregue as configurações padrão e defina o provedor de credenciais e a região.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Crie um cliente OSS.
	client := oss.NewClient(cfg)

	// Crie um uploader.
	u := client.NewUploader(func(uo *oss.UploaderOptions) {
		uo.PartSize = 1024 * 1024 * 5 // Defina o tamanho da parte como 5 MB.
		uo.ParallelNum = 3            // Defina o número de uploads simultâneos como 3.
	})

	// Substitua o caminho pelo seu caminho de arquivo local real.
	localFile := "/Users/seuCaminhoLocal/seuNomeDeArquivo"

	// Faça o upload do arquivo grande.
	result, err := u.UploadFile(context.TODO(),
		&oss.PutObjectRequest{
			Bucket: oss.Ptr(bucketName),
			Key:    oss.Ptr(objectName),
			ProgressFn: func(increment, transferred, total int64) {
				fmt.Printf("incremento:%v, transferido:%v, total:%v\n", increment, transferred, total)
			}, // A função de callback para progresso. Esta função é usada para exibir o progresso do upload.
		},
		localFile)
	if err != nil {
		log.Fatalf("falha ao fazer upload do arquivo %v", err)
	}

	// Imprima o resultado do upload.
	log.Printf("resultado do upload do arquivo:%#v\n", result)
}

Referências

Para obter mais informações sobre o Uploader, consulte Guia do Desenvolvedor.
Para obter mais informações sobre as operações de API que você pode usar para fazer upload de arquivos grandes, consulte UploadFrom e UploadFile.