Read-only file access (Go SDK V2) - Object Storage Service

This topic describes how to use the File-Like operation provided by Object Storage Service (OSS) SDK for Go 2.0 to access objects in a bucket.

Notes

The sample code in this topic uses the China (Hangzhou) region ID, cn-hangzhou, as an example. The public endpoint is used by default. If you want to access OSS from other Alibaba Cloud products in the same region, use the internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure the access credentials, see Configure access credentials.
To download a file, you must have the oss:GetObject permission. For more information, see Grant custom permissions to a RAM user.

Method

The File-Like operation provided by OSS SDK for Go 2.0 lets you access objects in a bucket using the ReadOnlyFile method.

The ReadOnlyFile method provides the single stream and prefetch modes. You can change the number of tasks in parallel to improve the read speed.
The ReadOnlyFile method provides a reconnection mechanism, which has strong robustness in a more complex network environment.

type ReadOnlyFile struct {
...
}

func (c *Client) OpenFile(ctx context.Context, bucket string, key string, optFns ...func(*OpenOptions)) (file *ReadOnlyFile, err error)

Request parameters

Parameter	Type	Description
ctx	context.Context	The context of the request.
bucket	string	The name of the bucket.
key	string	The name of the object.
optFns	...func(*OpenOptions)	Optional. The options that you can configure when you open the object.

Options of OpenOptions

Option	Type	Description
Offset	int64	The initial offset when the object is opened. Default value: 0.
VersionId	*string	The version number of the specified object. This parameter is valid only if multiple versions of the object exist.
RequestPayer	*string	Specifies that if pay-by-requester is enabled, RequestPayer must be set to requester.
EnablePrefetch	bool	Specifies whether to enable the prefetch mode. By default, the prefetch mode is disabled.
PrefetchNum	int	The number of prefetched chunks. Default value: 3. This parameter is valid when the prefetch mode is enabled.
ChunkSize	int64	The size of each prefetched chunk. Default value: 6 MiB. This parameter is valid when the prefetch mode is enabled.
PrefetchThreshold	int64	The number of bytes to be read in sequence before the prefetch mode is enabled. Default value: 20 MiB. This parameter is valid when the prefetch mode is enabled.

Response parameters

Parameter	Type	Description
file	*ReadOnlyFile	The instance of ReadOnlyFile. This parameter is valid when the value of err is nil. For more information, see ReadOnlyFile.
err	error	The status of ReadOnlyFile. If an error occurs, the value of err cannot be nil.

Common methods of ReadOnlyFile

Method	Description
Close() error	Closes the file handles to release resources, such as memory and active sockets.
Read(p []byte) (int, error)	Reads a byte whose length is len(p) from the data source, stores the byte in p, and returns the number of bytes that are read and the encountered errors.
Seek(offset int64, whence int) (int64, error)	Specifies the offset for the next read or write. Valid values of whence: 0: the head. 1: the current offset. 2: the tail.
Stat() (os.FileInfo, error)	Queries the object information, including the object size, last modified time, and metadata.

Important

Note: If the prefetch mode is enabled and multiple out-of-order reads occur, the single stream mode is automatically used.

Examples

Read the entire object using the single stream mode

package main

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

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

// Specify the global variables.
var (
	region     string // The region in which the bucket is located.
	bucketName string // The name of the bucket.
	objectName string // The name of the object.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the object.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the bucket name is empty.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Check whether the object name is empty.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, object name required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	// Open the object.
	f, err := client.OpenFile(context.TODO(), bucketName, objectName)

	if err != nil {
		log.Fatalf("failed to open file %v", err)
	}
	defer f.Close()

	// Read the content of the object using io.Copy.
	written, err := io.Copy(io.Discard, f)
	if err != nil {
		log.Fatalf("failed to read file %v", err)
	}

	log.Printf("read %d bytes from file", written)
}

Read the entire object using the prefetch mode

package main

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

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

// Specify the global variables.
var (
	region     string // The region in which the bucket is located.
	bucketName string // The name of the bucket.
	objectName string // The name of the object.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the object.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the bucket name is empty.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Check whether the object name is empty.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, object name required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	// Open the object.
	f, err := client.OpenFile(context.TODO(),
		bucketName,
		objectName,
		func(oo *oss.OpenOptions) {
			oo.EnablePrefetch = true // Enable the prefetch mode.
		})

	if err != nil {
		log.Fatalf("failed to open file %v", err)
	}

	defer f.Close()

	// Read the object.
	written, err := io.Copy(io.Discard, f)

	if err != nil {
		log.Fatalf("failed to read file %v", err)
	}

	log.Printf("read %d bytes from file", written)
}

Read remaining data from a specific position using the Seek method

package main

import (
	"context"
	"flag"
	"io"
	"log"
	"net/http"

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

// Specify the global variables.
var (
	region     string // The region in which the bucket is located.
	bucketName string // The name of the bucket.
	objectName string // The name of the object.
)

// Specify the init function used to initialize command line parameters.
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the object.")
}

func main() {
	// Parse command line parameters.
	flag.Parse()

	// Check whether the bucket name is empty.
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// Check whether the region is empty.
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// Check whether the object name is empty.
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, object name required")
	}

	// Load the default configurations and specify the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// Create an OSSClient instance.
	client := oss.NewClient(cfg)

	// Open the object.
	f, err := client.OpenFile(context.TODO(), bucketName, objectName)

	if err != nil {
		log.Fatalf("failed to open file %v", err)
	}

	defer f.Close()

	// Query the object information.
	info, _ := f.Stat()

	// Display the basic attributes of the object.
	log.Printf("size:%v, mtime:%v\n", info.Size(), info.ModTime())

	// Query object metadata.
	if header, ok := info.Sys().(http.Header); ok {
		log.Printf("content-type:%v\n", header.Get(oss.HTTPHeaderContentType))
	}

	// Specify the offset when you read the object, such as starting from 123.
	_, err = f.Seek(123, io.SeekStart)
	if err != nil {
		log.Fatalf("failed to seek file %v", err)
	}

	// Read the content of the object using io.Copy.
	written, err := io.Copy(io.Discard, f)

	if err != nil {
		log.Fatalf("failed to read file %v", err)
	}

	log.Printf("read %d bytes from file", written)
}

References

For more information about read-only class files, see the Developer Guide.
For the complete sample code of File-Like, visit GitHub.
For more information about the API operation of File-Like, visit OpenFile.