Access an object by using its URL, which is the public endpoint of the bucket-Object Storage Service(OSS)-阿里云帮助中心

By default, OSS generates a URL for each object using the bucket's public endpoint — for example, https://examplebucket.oss-cn-hangzhou.aliyuncs.com/example.jpg. To serve objects under your own domain, such as https://www.example.com/example.jpg, add a CNAME record that maps your custom domain to the bucket.

This document covers the full workflow using Go SDK V1:

Create a CNAME token (required for domain ownership verification)
Get a CNAME token (retrieve an existing token)
Add a CNAME record (map the domain, with or without an SSL certificate)
Disassociate a certificate
Query CNAME records
Delete a CNAME record

Usage notes

Examples in this document use the China (Hangzhou) region endpoint. To access OSS from other Alibaba Cloud services in the same region, use an internal endpoint. For more information, see Regions and endpoints.
Access credentials are read from environment variables. For setup instructions, see Configure access credentials.
Examples create an OSSClient instance using an OSS endpoint. To create an OSSClient using a custom domain name or Security Token Service (STS), see Configure OSSClient instances.

Create a CNAME token

Generate a CNAME token for the domain you want to map. The response includes an expiry time (ExpireTime).

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"
	// Specify the custom domain name.
	cname := "www.example.com"

	// Create a CNAME token.
	cbResult, err := client.CreateBucketCnameToken(bucketName, cname)
	if err != nil {
		log.Fatalf("Failed to create CNAME token: %v", err)
	}

	// Print the CNAME token information.
	log.Printf("Cname: %s", cbResult.Cname)
	log.Printf("Token: %s", cbResult.Token)
	log.Printf("ExpireTime: %s", cbResult.ExpireTime)
}

Get a CNAME token

Retrieve an existing CNAME token when you need the token value after the initial creation.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"
	// Specify the custom domain name.
	cname := "www.example.com"

	// Get the CNAME token.
	cbResult, err := client.GetBucketCnameToken(bucketName, cname)
	if err != nil {
		log.Fatalf("Failed to get CNAME token: %v", err)
	}

	// Print the CNAME token information.
	log.Printf("Cname: %s", cbResult.Cname)
	log.Printf("Token: %s", cbResult.Token)
	log.Printf("ExpireTime: %s", cbResult.ExpireTime)
}

Add a CNAME record

Map a custom domain name

Map the custom domain name to the bucket without associating an SSL certificate.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"
	// Specify the custom domain name.
	cname := "www.example.com"

	// Map the custom domain name to the bucket.
	err = client.PutBucketCname(bucketName, cname)
	if err != nil {
		log.Fatalf("Failed to put bucket CNAME: %v", err)
	}

	// Print the success message.
	log.Println("Put Bucket Cname Success!")
}

Map a custom domain name and associate a certificate

Map the custom domain name and bind an SSL certificate at the same time.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"

	// Configure the CNAME record and certificate.
	putCnameConfig := oss.PutBucketCname{
		Cname: "www.example.com",
		CertificateConfiguration: &oss.CertificateConfiguration{
			CertId:      "92******-cn-hangzhou",
			Certificate: "-----BEGIN CERTIFICATE-----MIIGeDCCBOCgAwIBAgIRAPj4FWpW5XN6kwgU7*******-----END CERTIFICATE-----",
			PrivateKey:  "-----BEGIN CERTIFICATE-----MIIFBzCCA++gT2H2hT6Wb3nwxjpLIfXmSVcV*****-----END CERTIFICATE-----",
			Force:       true,
		},
	}

	// Map the custom domain name and associate the certificate.
	err = client.PutBucketCnameWithCertificate(bucketName, putCnameConfig)
	if err != nil {
		log.Fatalf("Failed to bind CNAME and certificate: %v", err)
	}

	// Print the success message.
	log.Println("Bind Certificate Success!")
}

Disassociate a certificate

Remove the SSL certificate associated with a custom domain name without deleting the CNAME record itself.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Failed to create credentials provider: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Failed to create OSS client: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"

	// Configure the CNAME record and delete the certificate.
	putCnameConfig := oss.PutBucketCname{
		Cname: "www.example.com",
		CertificateConfiguration: &oss.CertificateConfiguration{
			DeleteCertificate: true,
		},
	}

	// Map the custom domain name and disassociate the certificate.
	err = client.PutBucketCnameWithCertificate(bucketName, putCnameConfig)
	if err != nil {
		log.Fatalf("Failed to unbind CNAME and delete certificate: %v", err)
	}

	// Print the success message.
	log.Println("Unbind Certificate Success!")
}

Query CNAME records

List all CNAME records for a bucket. Each entry includes the domain's Status, LastModified timestamp, and — if a certificate is associated — certificate details including ValidStartDate, ValidEndDate, and Fingerprint.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Error: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"

	// Query the CNAME records.
	cnResult, err := client.ListBucketCname(bucketName)
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	var certificate oss.Certificate
	log.Printf("Bucket: %s", cnResult.Bucket)
	log.Printf("Owner: %s", cnResult.Owner)

	if len(cnResult.Cname) > 0 {
		for _, cnameInfo := range cnResult.Cname {
			// Print the custom domain name.
			log.Printf("Domain: %s", cnameInfo.Domain)
			// Print the time when the custom domain name was mapped.
			log.Printf("LastModified: %s", cnameInfo.LastModified)
			// Print the status of the domain name.
			log.Printf("Status: %s", cnameInfo.Status)
			if cnameInfo.Certificate != certificate {
				// Print the source of the certificate.
				log.Printf("Type: %s", cnameInfo.Certificate.Type)
				// Print the certificate ID.
				log.Printf("CertId: %s", cnameInfo.Certificate.CertId)
				// Print the status of the certificate.
				log.Printf("Status: %s", cnameInfo.Certificate.Status)
				// Print the time when the certificate was associated.
				log.Printf("CreationDate: %s", cnameInfo.Certificate.CreationDate)
				// Print the signature of the certificate.
				log.Printf("Fingerprint: %s", cnameInfo.Certificate.Fingerprint)
				// Print the start time of the certificate validity period.
				log.Printf("ValidStartDate: %s", cnameInfo.Certificate.ValidStartDate)
				// Print the end time of the certificate validity period.
				log.Printf("ValidEndDate: %s", cnameInfo.Certificate.ValidEndDate)
			}
		}
	}
}

Delete a CNAME record

Remove a custom domain name mapping from the bucket.

package main

import (
	"log"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {
	// Obtain access credentials from environment variables. Before you run this 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 {
		log.Fatalf("Error: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, use the actual endpoint.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, use the actual region ID.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	// Specify the bucket name, for example, examplebucket.
	bucketName := "examplebucket"
	// Specify the custom domain name.
	cname := "www.example.com"

	// Delete the CNAME record.
	err = client.DeleteBucketCname(bucketName, cname)
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	// Print the success message.
	log.Println("Delete Bucket Cname Success!")
}

Map custom domain names (Go SDK V1)