### Install OSS SDK v2 from Source

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Use this command to install the OSS SDK for Go directly from its source code.

```bash
go get github.com/aliyun/alibabacloud-oss-go-sdk-v2
```

--------------------------------

### Install OSS SDK for Go v2

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Use 'go get' to install the OSS SDK for Go v2.

```bash
go get github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss
```

--------------------------------

### Configure Logging

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Enable and configure the logging feature. This example sets the log level to Info and directs logs to standard error.

```go
cfg := oss.LoadDefaultConfig().
  WithLogLevel(oss.LogInfo).
  WithLogPrinter(oss.LogPrinterFunc(func(a ...any) {
    fmt.Fprint(os.Stderr, a...)
  }))
```

--------------------------------

### Check Go Version

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Run this command to verify that Go version 1.18 or later is installed.

```bash
go version
```

--------------------------------

### Generate Pre-signed URL for Downloading an Object

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

This example demonstrates how to generate a pre-signed URL for downloading an object using the `Presign` method with a `GetObjectRequest`. The generated URL can be used with a standard HTTP GET request.

```APIDOC
## Presign

### Description
Generates a pre-signed URL for a specified operation, allowing temporary access to objects.

### Method
`Presign`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
client := oss.NewClient(cfg)

result, err := client.Presign(context.TODO(), &oss.GetObjectRequest{
  Bucket: oss.Ptr("bucket"),
  Key:    oss.Ptr("key"),
})

resp, err := http.Get(result.URL)
```

### Response
#### Success Response (200)
- **result** (*PresignResult) - The returned results, including the pre-signed URL, HTTP method, validity period, and request headers.
- **err** (error) - The status of the request. If the request fails, the value of err cannot be nil.

#### Response Example
```json
{
  "Method": "GET",
  "URL": "https://bucket.oss.aliyuncs.com/key?Expires=...&Signature=...",
  "Expiration": "2023-10-27T10:00:00Z",
  "SignedHeaders": {
    "Content-Type": "application/octet-stream"
  }
}
```
```

--------------------------------

### Create OSS Bucket

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

Demonstrates how to create an OSS bucket using the PutBucket API. This example shows setting the bucket name, ACL, resource group ID, and storage class.

```go
client := oss.NewClient(cfg)
result, err := client.PutBucket(context.TODO(), &oss.PutBucketRequest{
  Bucket:          oss.Ptr("bucket"),
  Acl:             oss.BucketACLPrivate,
  ResourceGroupId: oss.Ptr("resource-group-id"),
  CreateBucketConfiguration: &oss.CreateBucketConfiguration{
    StorageClass: oss.StorageClassIA,
  },
})

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

fmt.Printf("PutBucket result:%v", result)
```

--------------------------------

### Manage OSS Buckets: Create, Get Info, Check Existence, Delete

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Demonstrates core bucket lifecycle operations. Ensure the bucket name is provided using oss.Ptr().

```go
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou")
    client := oss.NewClient(cfg)
    ctx := context.TODO()

    // Create a bucket with Standard storage and LRS redundancy
    _, err := client.PutBucket(ctx, &oss.PutBucketRequest{
        Bucket: oss.Ptr("my-new-bucket"),
        Acl:    oss.BucketACLPrivate,
        CreateBucketConfiguration: &oss.CreateBucketConfiguration{
            StorageClass:       oss.StorageClassStandard,
            DataRedundancyType: oss.DataRedundancyLRS,
        },
    })
    if err != nil {
        log.Fatalf("PutBucket: %v", err)
    }

    // Get bucket info
    info, err := client.GetBucketInfo(ctx, &oss.GetBucketInfoRequest{
        Bucket: oss.Ptr("my-new-bucket"),
    })
    if err != nil {
        log.Fatalf("GetBucketInfo: %v", err)
    }
    fmt.Printf("Bucket: %s, StorageClass: %s, Location: %s\n",
        oss.ToString(info.BucketInfo.Name),
        oss.ToString(info.BucketInfo.StorageClass),
        oss.ToString(info.BucketInfo.Location),
    )

    // Check existence
    exists, err := client.IsBucketExist(ctx, "my-new-bucket")
    if err != nil {
        log.Fatalf("IsBucketExist: %v", err)
    }
    fmt.Println("exists:", exists)

    // Delete bucket
    _, err = client.DeleteBucket(ctx, &oss.DeleteBucketRequest{
        Bucket: oss.Ptr("my-new-bucket"),
    })
    if err != nil {
        log.Fatalf("DeleteBucket: %v", err)
    }
}
```

--------------------------------

### Verify OSS SDK for Go Version

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Execute this Go program to check the installed version of the OSS SDK for Go.

```go
package main

import (
  "fmt"
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
)

func main() {
  fmt.Println("OSS Go SDK Version: ", oss.Version())
}
```

--------------------------------

### Generate Pre-signed URL (v1)

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Example of generating a pre-signed URL for downloading an object using OSS SDK for Go V1.

```go
// v1
import "github.com/aliyun/aliyun-oss-go-sdk/oss"

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))

bucket, err := client.Bucket("examplebucket")

signedURL, err := bucket.SignURL("exampleobject.txt", oss.HTTPGet, 60)

fmt.Printf("Sign Url:%s\n", signedURL)

```

--------------------------------

### OSS Credentials Providers

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Demonstrates various credential provider implementations including static, environment variables, ECS RAM role, anonymous, and custom function providers. Ensure correct setup for each provider.

```go
package main

import (
    "context"
    "fmt"
    "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
    "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
    // 1. Static credentials (access key + secret, optional STS token)
    staticProvider := credentials.NewStaticCredentialsProvider("YOUR_KEY_ID", "YOUR_KEY_SECRET")

    // 2. Environment variables: OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET / OSS_SESSION_TOKEN
    envProvider := credentials.NewEnvironmentVariableCredentialsProvider()

    // 3. ECS RAM role — auto-fetches & refreshes from the instance metadata service
    ecsProvider := credentials.NewEcsRoleCredentialsProvider(
        credentials.EcsRamRole("my-ecs-ram-role"),
    )

    // 4. Anonymous (for public buckets)
    anonProvider := credentials.NewAnonymousCredentialsProvider()

    // 5. Custom function provider
    customProvider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
        return credentials.Credentials{
            AccessKeyID:     "DYNAMIC_KEY",
            AccessKeySecret: "DYNAMIC_SECRET",
        }, nil
    })

    for _, p := range []credentials.CredentialsProvider{staticProvider, envProvider, ecsProvider, anonProvider, customProvider} {
        cred, err := p.GetCredentials(context.TODO())
        if err != nil {
            fmt.Println("error:", err)
            continue
        }
        fmt.Println("key:", cred.AccessKeyID)
    }

    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(staticProvider).
        WithRegion("cn-hangzhou")
    client := oss.NewClient(cfg)
    _ = client
}
```

--------------------------------

### Load Default Configuration (V1 vs V2)

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

V1 uses functional options for configuration, while V2 uses a chained method approach starting with LoadDefaultConfig. V2 requires specifying the region explicitly for V4 signatures.

```go
// v1
import (
  "github.com/aliyun/aliyun-oss-go-sdk/oss"
)
...

// Obtain access credentials from environment variables.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()

// Set the timeout period of an HTTP connection to 20 and the read or write timeout period of an HTTP connection to 60. Unit: seconds.
time := oss.Timeout(20,60)

// Do not verify SSL certificates.
verifySsl := oss.InsecureSkipVerify(true)

// Specify logs.
logLevel := oss.SetLogLevel(oss.LogInfo)

// Endpoint
endpoint := "oss-cn-hangzhou.aliyuncs.com"

client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), time, verifySsl, logLevel)
```

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

...

// Obtain access credentials from environment variables.
provider := credentials.NewEnvironmentVariableCredentialsProvider()

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(provider).
  // Set the timeout period of an HTTP connection to 20. Unit: seconds.
  WithConnectTimeout(20 * time.Second).
  // Set the read or write timeout period of an HTTP connection to 60. Unit: seconds.
  WithReadWriteTimeout(60 * time.Second).
  // Do not verify SSL certificates.
  WithInsecureSkipVerify(true).
  // Specify logs.
  WithLogLevel(oss.LogInfo).
  // Specify the region.
  WithRegion("cn-hangzhou")

client := oss.NewClient(cfg)
```

--------------------------------

### Specify Progress Bar for Streaming Download

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

This example demonstrates how to monitor the progress of an object download using a streaming approach with `GetObject` and `io.TeeReader`.

```APIDOC
## Streaming Download with Progress Monitoring

### Description
Monitors the progress of an object download by reading the response body through a progress-tracking reader.

### Method
`GetObject` and `io.TeeReader`

### Parameters
- `ProgressFn` (func(increment, transferred, total int64)) - Optional - A callback function for progress updates.

### Request Example
```go
client := oss.NewClient(cfg)

result, err := client.GetObject(context.TODO(), &oss.GetObjectRequest{
  Bucket: oss.Ptr("bucket"),
  Key:    oss.Ptr("key"),
})

if err != nil {
  log.Fatalf("fail to GetObject %v", err)
}

prop := oss.NewProgress(
  func(increment, transferred, total int64) {
    fmt.Printf("increment:%v, transferred:%v, total:%v\n", increment, transferred, total)
  },
  result.ContentLength,
)

io.ReadAll(io.TeeReader(result.Body, prop))
```
```

--------------------------------

### Generate Pre-signed URL (v2)

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Example of generating a pre-signed URL for downloading an object using OSS SDK for Go V2. Note the use of `Presign` and `GetObjectRequest`.

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

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.Presign(
  context.TODO(),
  &oss.GetObjectRequest{
    Bucket: oss.Ptr("examplebucket"),
    Key:    oss.Ptr("exampleobject.txt"),
  },
  oss.PresignExpires(60*time.Second),
)

fmt.Printf("Sign Method:%v\n", result.Method)
fmt.Printf("Sign Url:%v\n", result.URL)
fmt.Printf("Sign Expiration:%v\n", result.Expiration)
for k, v := range result.SignedHeaders {
  fmt.Printf("SignedHeader %v:%v\n", k, v)
}

```

--------------------------------

### Generate Pre-signed URL for Object Download (GET)

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Generates a pre-signed URL for downloading an object. The URL can be used with `http.Get` before it expires.

```go
client := oss.NewClient(cfg)

result, err := client.Presign(context.TODO(), &oss.GetObjectRequest{
  Bucket: oss.Ptr("bucket"),
  Key:    oss.Ptr("key"),
})

resp, err := http.Get(result.URL)
```

--------------------------------

### Multipart Upload with Encryption Client

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

This example shows how to perform a multipart upload with encryption. It requires setting the part size and total data size for the encryption client and providing encryption context for each part.

```go
eclient, err := NewEncryptionClient(client, mc)

var (
  bucketName string = "bucket"
  objectName string = "key"
  length            = int64(500 * 1024)
  partSize          = int64(200 * 1024)
  partsNum          = int(length/partSize + 1)
  data              = make([]byte, length, length)
)

// 加密客户端 需要 设置分片大小和总文件大小
initResult, err := eclient.InitiateMultipartUpload(context.TODO(), &oss.InitiateMultipartUploadRequest{
  Bucket: oss.Ptr(bucketName),
  Key:    oss.Ptr(objectName),
  CSEPartSize: oss.Ptr(partSize),
  CSEDataSize: oss.Ptr(length),
})

var parts oss.UploadParts
for i := 0; i < partsNum; i++ {
  start := int64(i) * partSize
  end := start + partSize
  if end > length {
    end = length
  }

  // 加密客户端 需要 设置分片加密上下文
  upResult, err := eclient.UploadPart(context.TODO(), &oss.UploadPartRequest{
    Bucket:     oss.Ptr(bucketName),
    Key:        oss.Ptr(objectName),
    UploadId:   initResult.UploadId,
    PartNumber: int32(i + 1),
    CSEMultiPartContext: initResult.CSEMultiPartContext,
    Body:                bytes.NewReader(data[start:end]),
  })

  if err != nil {
    log.Fatalf("failed to UploadPart %v", err)
  }
  parts = append(parts, oss.UploadPart{PartNumber: int32(i + 1), ETag: upResult.ETag})
}

sort.Sort(parts)
_, err = eclient.CompleteMultipartUpload(context.TODO(), &oss.CompleteMultipartUploadRequest{
  Bucket:                  oss.Ptr(bucketName),
  Key:                     oss.Ptr(objectName),
  UploadId:                initResult.UploadId,
  CompleteMultipartUpload: &oss.CompleteMultipartUpload{Parts: parts},
})

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

--------------------------------

### MD5 Verification for PutObject

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

This example shows how to manually calculate and provide the MD5 hash for object uploads using `PutObject` to ensure data integrity.

```APIDOC
## PutObject with MD5 Verification

### Description
Enables MD5 verification for object uploads by calculating and providing the `Content-MD5` header.

### Method
`PutObject`

### Parameters
- `ContentMD5` (string) - Required - The Base64-encoded MD5 hash of the object content.
- `Body` (io.Reader) - Required - The object data to upload.

### Request Example
```go
client := oss.NewClient(cfg)

var body io.Reader

// Calculate the Content-Md5 header. If the request body is not of the io.ReadSeeker type, the data is cached and an MD5 hash is calculated.
calcMd5 := func(input io.Reader) (io.Reader, string, error) {
  if input == nil {
    return input, "1B2M2Y8AsgTpgAmY7PhCfg==", nil
  }
  var (
    r  io.ReadSeeker
    ok bool
  )
  if r, ok = input.(io.ReadSeeker); !ok {
    buf, err := io.ReadAll(input)
    if err != nil {
      return input, "", err
    }
    r = bytes.NewReader(buf)
  }

  curPos, err := r.Seek(0, io.SeekCurrent)
  if err != nil {
    return input, "", err
  }
  h := md5.New()
  _, err = io.Copy(h, r)
  if err != nil {
    return input, "", err
  }
  _, err = r.Seek(curPos, io.SeekStart)
  if err != nil {
    return input, "", err
  }

  return r, base64.StdEncoding.EncodeToString(h.Sum(nil)), nil
}

body, md5, err := calcMd5(body)

if err != nil {
  log.Fatalf("fail to calcMd5, %v", err)
}

result, err := client.PutObject(context.TODO(), &oss.PutObjectRequest{
  Bucket:     oss.Ptr("bucket"),
  Key:        oss.Ptr("key"),
  ContentMD5: oss.Ptr(md5),
  Body:       body,
})

if err != nil {
  log.Fatalf("fail to PutObject, %v", err)
}

fmt.Printf("PutObject result, etg:%v", oss.ToString(result.ETag))
```
```

--------------------------------

### Specify Progress Bar for Download to File

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

This example shows how to set a progress bar function when downloading an object to a local file using `GetObjectToFile`.

```APIDOC
## GetObjectToFile with Progress Bar

### Description
Allows specifying a callback function to monitor the progress of an object download to a file.

### Method
`GetObjectToFile`

### Parameters
- `ProgressFn` (func(increment, transferred, total int64)) - Optional - A callback function that receives download progress information.

### Request Example
```go
client := oss.NewClient(cfg)
client.GetObjectToFile(context.TODO(),
  &oss.GetObjectRequest{
    Bucket: oss.Ptr("bucket"),
    Key:    oss.Ptr("key"),
    ProgressFn: func(increment, transferred, total int64) {
      fmt.Printf("increment:%v, transferred:%v, total:%v\n", increment, transferred, total)
    },
  },
  "/local/dir/example",
)
```
```

--------------------------------

### Combine Multiple Local Files into an Object

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

This example demonstrates how to combine data from multiple local files into a single object in OSS by sequentially writing to an appendable file. It shows writing from file readers and directly from byte slices.

```go
...
client := oss.NewClient(cfg)

f, err := client.AppendFile(context.TODO(), "bucket", "key")
if err != nil {
  log.Fatalf("failed to append file %v", err)
}

defer f.Close()

// example1.txt
lf, err := os.Open("/local/dir/example1.txt")
if err != nil {
  log.Fatalf("failed to local file %v", err)
}

_, err = f.WriteFrom(lf)

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

// example2.txt
lf, err = os.Open("/local/dir/example2.txt")
if err != nil {
  log.Fatalf("failed to local file %v", err)
}

_, err = f.WriteFrom(lf)

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

// example3.txt
lb, err := os.ReadFile("/local/dir/example3.txt")

_, err = f.Write(lb)

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

```

--------------------------------

### Initialize OSS Client with Default Config

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Load default configuration, chain With* methods for customization (region, credentials, timeouts, logging), and create a new client.

```go
package main

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

func main() {
    // Credentials loaded from OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET env vars
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou").
        WithConnectTimeout(5 * time.Second).
        WithReadWriteTimeout(30 * time.Second).
        WithRetryMaxAttempts(3).
        WithLogLevel(oss.LogInfo)

    client := oss.NewClient(cfg)
    _ = client
}
```

--------------------------------

### Configure Uploader Options

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Demonstrates how to create a new Uploader instance with custom PartSize configuration.

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

--------------------------------

### Client Initialization

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Demonstrates how to initialize the OSS client by loading default configuration, setting various options like region, timeouts, and retry attempts, and then creating a new client instance.

```APIDOC
## Client Initialization — `LoadDefaultConfig` / `NewClient`

`LoadDefaultConfig` returns a `*Config` that reads the `OSS_SDK_LOG_LEVEL` environment variable. Chain `With*` methods to configure the region, credentials, timeouts, and other options, then pass it to `NewClient`.

```go
package main

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

func main() {
    // Credentials loaded from OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET env vars
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou").
        WithConnectTimeout(5 * time.Second).
        WithReadWriteTimeout(30 * time.Second).
        WithRetryMaxAttempts(3).
        WithLogLevel(oss.LogInfo)

    client := oss.NewClient(cfg)
    _ = client
}
```
```

--------------------------------

### Modify Backoff Algorithm

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Change the backoff algorithm to a fixed-time delay. This example sets a consistent 2-second delay for each retry.

```go
cfg := oss.LoadDefaultConfig().WithRetryer(retry.NewStandard(func(ro *retry.RetryOptions) {
  ro.Backoff = &retry.NewFixedDelayBackoff(2 * time.Second)
}))
```

--------------------------------

### DataProcess Client

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Introduces the `dataprocess.NewClient` for AI-powered dataset management and querying, with examples for creating datasets and performing simple queries.

```APIDOC
## DataProcess Client — `dataprocess.NewClient`

The `oss/dataprocess` sub-package provides a dedicated client for AI-powered dataset management and querying (IMM integration).

```go
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou")

    client := dataprocess.NewClient(cfg)
    ctx := context.TODO()

    // Create a dataset
    _, err := client.CreateDataset(ctx, &dataprocess.CreateDatasetRequest{
        Bucket:      oss.Ptr("my-bucket"),
        DatasetName: oss.Ptr("my-images"),
    })
    if err != nil {
        log.Fatalf("CreateDataset: %v", err)
    }

    // Simple query: find objects larger than 10 bytes, sorted by size
    result, err := client.SimpleQuery(ctx, &dataprocess.SimpleQueryRequest{
        Bucket:           oss.Ptr("my-bucket"),
        DatasetName:      oss.Ptr("my-images"),
        Query:            oss.Ptr(`{"Field":"Size","Value":"10","Operation":"gt"}`),
        MaxResults:       oss.Ptr(int32(20)),
        Sort:             oss.Ptr("Size"),
        Order:            oss.Ptr("asc"),
        WithFields:       oss.Ptr(`["Filename","Size","MediaType"]`),
        WithoutTotalHits: oss.Ptr(true),
    })
    if err != nil {
        log.Fatalf("SimpleQuery: %v", err)
    }
    fmt.Printf("Found %d files\n", len(result.Files))
    for _, f := range result.Files {
        fmt.Printf("  %s  (%d bytes)\n", f.Filename, f.Size)
    }
}
```
```

--------------------------------

### Create Downloader Instance

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Instantiate a Downloader with custom options. PartSize can be adjusted for download chunk size.

```go
d := client.NewDownloader(func(do *oss.DownloaderOptions) {
  do.PartSize = 10 * 1024 * 1024
})
```

--------------------------------

### Specify Progress Bar for Upload

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

This example demonstrates how to set a progress bar function for uploading a local file using `PutObject`.

```APIDOC
## PutObject with Progress Bar

### Description
Allows specifying a callback function to monitor the progress of an object upload.

### Method
`PutObject`

### Parameters
- `ProgressFn` (func(increment, transferred, total int64)) - Optional - A callback function that receives upload progress information.

### Request Example
```go
client := oss.NewClient(cfg)
client.PutObject(context.TODO(), &oss.PutObjectRequest{
  Bucket: oss.Ptr("bucket"),
  Key:    oss.Ptr("key"),
  ProgressFn: func(increment, transferred, total int64) {
    fmt.Printf("increment:%v, transferred:%v, total:%v\n", increment, transferred, total)
  },
})
```
```

--------------------------------

### Create Client (V1 vs V2)

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

V1's New function accepts endpoint, AK, and SK directly. V2's NewClient function requires a pre-configured Config object and does not support direct endpoint, AK, or SK parameters.

```go
// v1
client, err := oss.New(endpoint, "ak", "sk")
```

```go
// v2
client := oss.NewClient(cfg)
```

--------------------------------

### Configure OSS Client with Default Settings

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Load default configurations and set the region and credentials provider for the OSS client. The region must be explicitly specified.

```go
package main

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

func main() {
  var (
    // In this example, the China (Hangzhou) region is used.
    region = "cn-hangzhou"

    // In this example, the credential is obtained from environment variables.
    provider credentials.CredentialsProvider = credentials.NewEnvironmentVariableCredentialsProvider()
  )

  cfg := oss.LoadDefaultConfig().
    WithCredentialsProvider(provider).
    WithRegion(region)
  }
```

--------------------------------

### Example: Modifying Storage Class

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

Shows how to copy an object while changing its storage class to 'Standard' using the StorageClass field in CopyObjectRequest.

```APIDOC
## Example: Modifying Storage Class

### Description
Shows how to copy an object while changing its storage class to 'Standard' using the StorageClass field in CopyObjectRequest.

### Code Example
```go
client := oss.NewClient(cfg)
copier := client.NewCopier()

result, err := copier.Copy(context.TODO(), &oss.CopyObjectRequest{
  Bucket:       oss.Ptr("bucket"),
  Key:          oss.Ptr("key"),
  SourceBucket: oss.Ptr("src-bucket"),
  SourceKey:    oss.Ptr("src-key"),
  StorageClass: oss.StorageClassStandard,
})

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

fmt.Printf("copy done, etag %v\n", oss.ToString(result.ETag))
```
```

--------------------------------

### OSS Client Configuration Options

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

This table lists various configuration parameters available for initializing the OSS client. Use these options to customize region, credentials, endpoints, timeouts, retry logic, and other client behaviors.

```go
WithRegion("cn-hangzhou")
```

```go
WithCredentialsProvider(provider)
```

```go
WithEndpoint("oss-cn-hanghzou.aliyuncs.com")
```

```go
WithHttpClient(customClient)
```

```go
WithRetryMaxAttempts(5)
```

```go
WithRetryer(customRetryer)
```

```go
WithConnectTimeout(10 * time.Second)
```

```go
WithReadWriteTimeout(30 * time.Second)
```

```go
WithInsecureSkipVerify(true)
```

```go
WithEnabledRedirect(true)
```

```go
WithProxyHost("http://user:passswd@proxy.example-***.com")
```

```go
WithProxyFromEnvironment(true)
```

```go
WithUploadBandwidthlimit(10*1024)
```

```go
WithDownloadBandwidthlimit(10*1024)
```

```go
WithSignatureVersion(oss.SignatureVersionV1)
```

```go
WithLogLevel(oss.LogInfo)
```

```go
WithLogPrinter(customPrinter)
```

```go
WithDisableSSL(true)
```

```go
WithUsePathStyle(true)
```

```go
WithUseCName(true)
```

```go
WithUseDualStackEndpoint(true)
```

```go
WithUseAccelerateEndpoint(true)
```

```go
WithUseInternalEndpoint(true)
```

```go
WithDisableUploadCRC64Check(true)
```

```go
WithDisableDownloadCRC64Check(true)
```

```go
WithAdditionalHeaders([]string{"content-length"})
```

```go
WithUserAgent("user identifier")
```

--------------------------------

### List Buckets with Go SDK

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/README.md

Lists all buckets in your OSS account. Ensure credentials are set via environment variables.

```go
package main

import (
	"context"
	"fmt"
	"log"

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

func main() {
	var (
		region = "cn-hangzhou"
	)

	// Using the SDK's default configuration
	// loading credentials values from the environment variables
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	client := oss.NewClient(cfg)

	// Create the Paginator for the ListBuckets operation.
	p := client.NewListBucketsPaginator(&oss.ListBucketsRequest{})

	// Iterate through the bucket pages
	var i int
	fmt.Println("Buckets:")
	for p.HasNext() {
		i++
		page, err := p.NextPage(context.TODO())
		if err != nil {
			log.Fatalf("failed to get page %v, %v", i, err)
		}
		// Print the bucket found
		for _, b := range page.Buckets {
			fmt.Printf("Bucket:%v, %v, %v\n", oss.ToString(b.Name), oss.ToString(b.StorageClass), oss.ToString(b.Location))
		}
	}
}
```

--------------------------------

### Example: Copying Data Only

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

Illustrates how to copy an object's data without copying its metadata or tags by setting MetadataDirective and TaggingDirective to 'Replace'.

```APIDOC
## Example: Copying Data Only

### Description
Illustrates how to copy an object's data without copying its metadata or tags by setting MetadataDirective and TaggingDirective to 'Replace'.

### Code Example
```go
client := oss.NewClient(cfg)
copier := client.NewCopier()

result, err := copier.Copy(context.TODO(), &oss.CopyObjectRequest{
  Bucket:            oss.Ptr("bucket"),
  Key:               oss.Ptr("key"),
  SourceBucket:      oss.Ptr("src-bucket"),
  SourceKey:         oss.Ptr("src-key"),
  MetadataDirective: oss.Ptr("Replace"),
  TaggingDirective:  oss.Ptr("Replace"),
})

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

fmt.Printf("copy done, etag %v\n", oss.ToString(result.ETag))
```
```

--------------------------------

### Use DataProcess Client for Dataset Management

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Initializes and uses the `oss/dataprocess` client for AI-powered dataset management. This includes creating a dataset and performing a simple query to find objects based on specified criteria.

```go
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou")

    client := dataprocess.NewClient(cfg)
    ctx := context.TODO()

    // Create a dataset
    _, err := client.CreateDataset(ctx, &dataprocess.CreateDatasetRequest{
        Bucket:      oss.Ptr("my-bucket"),
        DatasetName: oss.Ptr("my-images"),
    })
    if err != nil {
        log.Fatalf("CreateDataset: %v", err)
    }

    // Simple query: find objects larger than 10 bytes, sorted by size
    result, err := client.SimpleQuery(ctx, &dataprocess.SimpleQueryRequest{
        Bucket:           oss.Ptr("my-bucket"),
        DatasetName:      oss.Ptr("my-images"),
        Query:            oss.Ptr(`{"Field":"Size","Value":"10","Operation":"gt"}`),
        MaxResults:       oss.Ptr(int32(20)),
        Sort:             oss.Ptr("Size"),
        Order:            oss.Ptr("asc"),
        WithFields:       oss.Ptr(`["Filename","Size","MediaType"]`),
        WithoutTotalHits: oss.Ptr(true),
    })
    if err != nil {
        log.Fatalf("SimpleQuery: %v", err)
    }
    fmt.Printf("Found %d files\n", len(result.Files))
    for _, f := range result.Files {
        fmt.Printf("  %s  (%d bytes)\n", f.Filename, f.Size)
    }
}
```

--------------------------------

### Example: Default Copy Operation

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

Demonstrates a basic object copy operation using the Copier, where both metadata and tags are copied from the source object by default.

```APIDOC
## Example: Default Copy Operation

### Description
Demonstrates a basic object copy operation using the Copier, where both metadata and tags are copied from the source object by default.

### Code Example
```go
client := oss.NewClient(cfg)
copier := client.NewCopier()

result, err := copier.Copy(context.TODO(), &oss.CopyObjectRequest{
  Bucket:       oss.Ptr("bucket"),
  Key:          oss.Ptr("key"),
  SourceBucket: oss.Ptr("src-bucket"),
  SourceKey:    oss.Ptr("src-key"),
})

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

fmt.Printf("copy done, etag %v\n", oss.ToString(result.ETag))
```
```

--------------------------------

### Upload and Download Objects with Encryption Client

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

Demonstrates using the encryption client for standard object operations like PutObject, GetObject, and file transfers using Downloader and Uploader. Also shows how to open and read files directly.

```go
eclient, err := NewEncryptionClient(client, mc)

// Use PutObject
_, err = eclient.PutObject(context.TODO(), &oss.PutObjectRequest{
  Bucket: oss.Ptr("bucket"),
  Key:    oss.Ptr("key"),
  Body:   bytes.NewReader([]byte("hello world")),
})

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

// Use GetObject
gresult, err := eclient.GetObject(context.TODO(), &oss.GetObjectRequest{
  Bucket: oss.Ptr("bucket"),
  Key:    oss.Ptr("key"),
})

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

io.Copy(io.Discard, gresult.Body)
gresult.Body.Close()

// Use Downloader
d := eclient.NewDownloader()
_, err = d.DownloadFile(context.TODO(),
  &oss.GetObjectRequest{
    Bucket: oss.Ptr("bucket"),
    Key:    oss.Ptr("key"),
  },
  "/local/dir/example",
)
if err != nil {
  log.Fatalf("failed to DownloadFile %v", err)
}

// Use Uploader
u := eclient.NewUploader()
_, err = u.UploadFile(context.TODO(),
  &oss.PutObjectRequest{
    Bucket: oss.Ptr("bucket"),
    Key:    oss.Ptr("key"),
  },
  "/local/dir/example",
)
if err != nil {
  log.Fatalf("failed to UploadFile %v", err)
}

// Use ReadOnlyFile
f, err := eclient.OpenFile(context.TODO(), "bucket", "key")
if err != nil {
  log.Fatalf("failed to OpenFile %v", err)
}
defer f.Close()

_, err = io.Copy(io.Discard, f)
if err != nil {
  log.Fatalf("failed to Copy %v", err)
}
```

--------------------------------

### MasterCipher Interface and Custom Implementation

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Defines the MasterCipher interface for custom CMK management and provides an example implementation (MasterCustomCipher) for encrypting and decrypting data keys.

```APIDOC
## MasterCipher Interface

```go
type MasterCipher interface {
  Encrypt([]byte) ([]byte, error)
  Decrypt([]byte) ([]byte, error)
  GetWrapAlgorithm() string
  GetMatDesc() string
}
```

### API Operations of MasterCipher

| Operation        | Description                                                    |
|------------------|----------------------------------------------------------------|
| Encrypt          | Encrypts the data key and the initial values (IV) of the encrypted data. |
| Decrypt          | Decrypts the data key and the initial values (IV) of the encrypted data. |
| GetWrapAlgorithm | Returns the encryption algorithm of the data key.                |
| GetMatDesc       | Returns the description of the CMK in JSON format.             |

## MasterCustomCipher Example

```go
type MasterCustomCipher struct {
  MatDesc    string
  SecrectKey string
}

func (mrc MasterCustomCipher) GetWrapAlgorithm() string {
  return "Custom/None/NoPadding"
}

func (mrc MasterCustomCipher) GetMatDesc() string {
  return mrc.MatDesc
}

func (mrc MasterCustomCipher) Encrypt(plainData []byte) ([]byte, error) {
  // TODO
}

func (mrc MasterCustomCipher) Decrypt(cryptoData []byte) ([]byte, error) {
  // TODO
}

func MasterCustomCipher(matDesc map[string]string, secrectKey string) (crypto.MasterCipher, error) {
  var jsonDesc string
  if len(matDesc) > 0 {
    b, err := json.Marshal(matDesc)
    if err != nil {
      return nil, err
    }
    jsonDesc = string(b)
  }
  return MasterCustomCipher{MatDesc: jsonDesc, SecrectKey: secrectKey}, nil
}

// Usage Example:
// client := oss.NewClient(cfg)
// materialDesc := make(map[string]string)
// materialDesc["desc"] = "your master encrypt key material describe information"
// mc, err := MasterCustomCipher(materialDesc, "yourSecrectKey")
// eclient, err := NewEncryptionClient(client, mc)
```
```

--------------------------------

### Initialize Encryption Client with Custom CMK

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Demonstrates how to initialize an OSS encryption client using a custom MasterCipher implementation. This involves creating an OSS client, instantiating the custom cipher, and then creating the encryption client.

```go
client := oss.NewClient(cfg)
materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"
mc, err := MasterCustomCipher(materialDesc, "yourSecrectKey")
eclient, err := NewEncryptionClient(client, mc)
```

--------------------------------

### Create RSA Encryption Client

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE-CN.md

Initialize an OSS client and then create an encryption client using RSA master keys. It's recommended to provide a description for the master key material for easier management and decryption.

```go
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/crypto"

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

// 创建一个主密钥的描述信息，创建后不允许修改。主密钥描述信息和主密钥一一对应。
// 如果所有的对象都使用相同的主密钥，主密钥描述信息可以为空，但后续不支持更换主密钥。
// 如果主密钥描述信息为空，解密时无法判断使用的是哪个主密钥。
// 强烈建议为每个主密钥都配置主密钥描述信息，由客户端保存主密钥和描述信息之间的对应关系。
materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

// 创建只包含 主密钥 的 加密客户端
mc, err := crypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")
eclient, err := NewEncryptionClient(client, mc)
```

--------------------------------

### Configure OSS Client with Proxy from Environment

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Enables the use of proxy servers configured via environment variables.

```go
WithProxyFromEnvironment(true)
```

--------------------------------

### Get OSS Object Metadata or Check Existence

Source: https://context7.com/aliyun/alibabacloud-oss-go-sdk-v2/llms.txt

Retrieves metadata for an object using `HeadObject` or checks if an object exists using `IsObjectExist`. `IsObjectExist` returns `false` without an error if the object is not found.

```go
package main

import (
    "context"
    "fmt"
    "log"

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

func main() {
    cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("cn-hangzhou")
    client := oss.NewClient(cfg)
    ctx := context.TODO()

    // HeadObject returns all metadata
    meta, err := client.HeadObject(ctx, &oss.HeadObjectRequest{
        Bucket: oss.Ptr("my-bucket"),
        Key:    oss.Ptr("hello.txt"),
    })
    if err != nil {
        log.Fatalf("HeadObject: %v", err)
    }
    fmt.Printf("Size: %d, ETag: %s, ContentType: %s\n",
        oss.ToInt64(meta.ContentLength),
        oss.ToString(meta.ETag),
        oss.ToString(meta.ContentType),
    )
    for k, v := range meta.Metadata {
        fmt.Printf("  x-oss-meta-%s: %s\n", k, v)
    }

    // IsObjectExist — returns false (not an error) for NoSuchKey
    exists, err := client.IsObjectExist(ctx, "my-bucket", "hello.txt")
    if err != nil {
        log.Fatalf("IsObjectExist: %v", err)
    }
    fmt.Println("exists:", exists) // true
}
```

--------------------------------

### Configure OSS Client with Log Level

Source: https://github.com/aliyun/alibabacloud-oss-go-sdk-v2/blob/master/DEVGUIDE.md

Sets the log level for the SDK. Use oss.LogInfo for informational logs.

```go
WithLogLevel(oss.LogInfo)
```