Acesse o OSS via Endpoints e Domínios de Bucket - Object Storage Service: Central de Documentação do Alibaba Cloud

Cada bucket do OSS possui nomes de domínio padrão para acesso via internet, rede interna e aceleração de transferência. Conheça os formatos de nome de domínio, os casos de uso e a configuração para cada tipo de acesso.

Conceitos fundamentais

Os endereços de acesso ao OSS combinam vários componentes. Compreender os quatro conceitos a seguir é essencial para acessar o OSS corretamente:

Conceito	Descrição	Exemplo	Finalidade
ID da Região	Identificador Geral da Região	`ap-southeast-1`	Usado em cenários de assinatura com SDK e ossutil V4
ID da Região Dedicada	Identificador de Região Dedicada do OSS	`oss-ap-southeast-1`	Usado para compor Endpoints, parâmetros de entrada e retorno de API, entre outros cenários
Endpoint	Endereço de Acesso ao Serviço	`oss-ap-southeast-1.aliyuncs.com`	Configurado no SDK e no ossutil para estabelecer conexões de rede com o serviço OSS
Domínio do Bucket	Endereço de Acesso ao Bucket Específico	`bucket-name.oss-ap-southeast-1.aliyuncs.com`	Indicado para acesso direto via navegador, geração de URLs assinadas, hospedagem de sites estáticos, resolução CNAME de domínio personalizado e outros cenários.

Esses conceitos formam uma hierarquia: o ID da Região identifica um local, o OSS atribui um ID da Região dedicada correspondente, que se combina com o sufixo de domínio para formar o Endpoint. Ao prefixar o nome do bucket ao Endpoint, obtém-se o nome de domínio do Bucket para acesso aos recursos.

Tipos de nome de domínio

O OSS oferece diferentes tipos de nome de domínio para atender a diversos ambientes de rede e requisitos de desempenho.

Importante

Devido a uma alteração de política visando melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do OSS devem usar um nome de domínio personalizado (CNAME) para executar operações de API de dados em buckets do OSS localizados em regiões da China continental. Os Endpoints públicos padrão têm acesso restrito para essas operações. Consulte o anúncio oficial para obter a lista completa das operações afetadas. Se você acessar seus dados via HTTPS, será necessário vincular um Certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao Console do OSS, pois o console impõe o uso de HTTPS.

Nome de domínio de acesso à internet

Ideal para aplicações web, clientes móveis e acesso entre regiões pela internet pública.

Formato do domínio

Endpoint:oss-[RegionID].aliyuncs.com
Domínio do bucket:[BucketName].oss-[RegionID].aliyuncs.com

Exemplos de acesso

File URL

O exemplo a seguir obtém uma URL assinada para um arquivo em um bucket privado por meio do console. Para mais informações sobre como obter URLs assinadas, consulte Usar URLs pré-assinadas para baixar ou visualizar arquivos.

Acesse a Lista de buckets e clique no bucket desejado.
Clique no filename do arquivo alvo ou em Details na coluna Actions.
Em Domain, selecione Internet domain e clique em Copy file URL.
Abra a URL no navegador.

Ao acessar HTML, imagens ou outros arquivos pelo domínio do bucket OSS, o sistema baixa os arquivos em vez de exibi-los no navegador. Para ativar a visualização no navegador, Acesse o OSS por meio de um nome de domínio personalizado.

ossutil

Este exemplo mostra como baixar um arquivo usando o ossutil 2,0. Primeiro, instale e configure o ossutil 2,0. A ferramenta usa o endpoint de internet por padrão. Você também pode especificá-lo explicitamente com o parâmetro -e.

ossutil cp oss://example-bucket/dest.jpg dest.jpg -e oss-ap-southeast-1.aliyuncs.com

SDK

Abaixo estão exemplos de SDK para linguagens comuns. Para outras linguagens, consulte os métodos de inicialização na Referência do SDK.

Java SDK V2

O cliente do SDK usa o endpoint de internet por padrão. Especifique apenas o ID da Região — não é necessário definir um Endpoint explícito. Para o código completo de inicialização, consulte OSS SDK for Java 2.0 (preview).

Java SDK V1

Especifique o endpoint de internet ao inicializar o cliente OSS. Para o código completo de inicialização, consulte OSS Java SDK V1.

// Example using the public network access Endpoint for Singapore
String endpoint = "oss-ap-southeast-1.aliyuncs.com";
// Initialize OSS client
OSS ossClient = OSSClientBuilder.create()
        .credentialsProvider(provider)
        .clientConfiguration(clientBuilderConfiguration)
        .region("ap-southeast-1")
        .endpoint(endpoint)
        .build();

Python SDK V2

O cliente do SDK utiliza o endpoint de internet por padrão. Informe apenas o ID da Região — nenhum Endpoint explícito é necessário. Para ver o código completo de inicialização, consulte OSS Python SDK V2.

Python SDK V1

Defina o endpoint de internet durante a inicialização do cliente OSS. Para obter o código completo de inicialização, consulte Inicialização.

# Example using the public endpoint for Singapore
endpoint = "https://oss-ap-southeast-1.aliyuncs.com"
# Initialize OSS client instance
bucket = oss2.Bucket(auth, endpoint, "example-bucket", region="ap-southeast-1")

Go SDK V2

Por padrão, o SDK adota o endpoint de internet. Basta especificar o ID da Região, sem necessidade de um Endpoint explícito. O código completo de inicialização está disponível em OSS Go SDK V2.

Go SDK V1

Informe o endpoint de internet ao inicializar o cliente OSS. Para o código completo de inicialização, veja Configurar um cliente (Go SDK V1).

// Create OSS client instance
client, _ := oss.New(
        "oss-ap-southeast-1.aliyuncs.com",	// Example using the public endpoint for Singapore
        "",
        "",
        oss.SetCredentialsProvider(&provider),
        oss.AuthVersion(oss.AuthV4),
        oss.Region("ap-southeast-1"),
)

Endpoints internos

Recomendado para instâncias ECS que acessam o OSS na mesma região. O acesso interno elimina taxas de tráfego de internet, oferecendo menor latência e conexões mais estáveis.

Formato do domínio

Endpoint:oss-[RegionID]-internal.aliyuncs.com
Domínio do bucket:[BucketName].oss-[RegionID]-internal.aliyuncs.com

Recomendações de uso

Otimização da configuração de DNS

Ao usar endpoints internos, configure os endereços de DNS privado da Alibaba Cloud (100.100.2.136 e 100.100.2.138) para garantir a resolução correta de VIP e evitar falhas de acesso relacionadas a DNS.
Integridade da configuração de roteamento de segmentos de VIP

O OSS atribui segmentos fixos de VIP para a rede interna de cada região. O sistema alterna dinamicamente os IPs dentro desses segmentos. Quando você acessa o OSS pela rede interna a partir de dispositivos locais ou data centers, o roteamento deve cobrir todos os segmentos de VIP. Roteamentos incompletos causam interrupções na conexão. Para detalhes sobre os segmentos de VIP, consulte Regiões e endpoints.

Importante
Certifique-se de que sua configuração de roteamento cubra todo o segmento de VIP. Se o acesso ao OSS falhar devido à ausência de rotas para o segmento de VIP, a parte responsável pela configuração arcará com quaisquer perdas resultantes.
Configuração de Regras de Grupo de Segurança

As regras do grupo de segurança da ECS não devem bloquear o acesso a qualquer segmento de VIP usado pelos endpoints internos do OSS.

Exemplos de acesso

ossutil

Neste exemplo, um arquivo é baixado usando o ossutil 2,0 a partir de uma instância ECS na mesma região. Primeiramente, instale e configure o ossutil 2,0. Defina o endpoint interno durante a configuração ou especifique-o com o parâmetro -e.

ossutil cp oss://example-bucket/dest.jpg dest.jpg -e oss-ap-southeast-1-internal.aliyuncs.com

SDK

Veja abaixo exemplos de SDK para linguagens comuns. Para outras linguagens, consulte a Referência do SDK para conhecer os métodos de inicialização de cada linguagem.

Java SDK V2

Especifique o Endpoint ou defina useInternalEndpoint(true) para usar o endpoint interno. Para o código completo de inicialização, consulte OSS SDK for Java 2.0 (preview).

Método 1: Especificar o Endpoint de acesso interno

// Example using the internal access Endpoint for Singapore
String endpoint = "oss-ap-southeast-1-internal.aliyuncs.com";
// Initialize the OSS client
OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("ap-southeast-1")
        .endpoint(endpoint)
        .build();

Método 2: Definir via useInternalEndpoint(true)

// Initialize the OSS client
OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("ap-southeast-1")
        .useInternalEndpoint(true)
        .build();

Java SDK V1

Informe o endpoint interno ao inicializar o cliente OSS. O código completo de inicialização encontra-se em OSS Java SDK V1.

// Example of internal access endpoint for Singapore
String endpoint = "oss-ap-southeast-1-internal.aliyuncs.com";
// Initialize OSS client
OSS ossClient = OSSClientBuilder.create()
        .credentialsProvider(provider)
        .clientConfiguration(clientBuilderConfiguration)
        .region("ap-southeast-1")
        .endpoint(endpoint)
        .build();

Python SDK V2

Especifique o Endpoint ou configure use_internal_endpoint = True para utilizar o endpoint interno. Para o código completo de inicialização, acesse OSS Python SDK V2.

Método 1: Especificar o endpoint de acesso interno

# Example of internal access endpoint for Singapore
config.endpoint = "https://oss-ap-southeast-1-internal.aliyuncs.com"
# Initialize OSS client
client = oss.Client(config)

Método 2: Definir via use_internal_endpoint = True

config.use_internal_endpoint = True
# Initialize OSS client
client = oss.Client(config)

Python SDK V1

Configure o endpoint interno durante a inicialização do cliente OSS. Para obter o código completo de inicialização, consulte Inicialização.

# Example using internal access Endpoint for Singapore
endpoint = "oss-ap-southeast-1-internal.aliyuncs.com"
# Initialize OSS client instance
bucket = oss.Bucket(auth, endpoint, bucket, region="ap-southeast-1")

Go SDK V2

Especifique o Endpoint ou use WithUseInternalEndpoint(true) para habilitar o endpoint interno. O código completo de inicialização está disponível em OSS Go SDK V2.

Método 1: Especificar o Endpoint de acesso interno

// Configure OSS client, set credential provider and service region
config := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("ap-southeast-1").
        WithEndpoint("oss-ap-southeast-1-internal.aliyuncs.com") // Example using internal access Endpoint for Singapore

// Initialize OSS client instance
client := oss.NewClient(config)

Método 2: Usar a configuração WithUseInternalEndpoint(true)

// Configure OSS client, set credentials provider and service region
config := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("ap-southeast-1").
        WithUseInternalEndpoint(true)

// Initialize OSS client instance
client := oss.NewClient(config)

Go SDK V1

Defina o endpoint interno ao inicializar o cliente OSS. Para ver o código completo de inicialização, consulte Configurar um cliente (Go SDK V1).

// Create OSS client instance
client, _ := oss.New(
        "oss-ap-southeast-1-internal.aliyuncs.com", // Example using Singapore internal network access endpoint
        "",
        "",
        oss.SetCredentialsProvider(&provider),
        oss.AuthVersion(oss.AuthV4),
        oss.Region("ap-southeast-1"),
)

Nome de Domínio de Aceleração de Transferência

Após ativar o recurso de Acesso ao OSS com aceleração de transferência, utilize domínios dedicados que roteiam dados por nós de aceleração global. Essa opção é adequada para cenários de upload e download entre regiões e transfronteiriços com altos requisitos de latência.

Formato do Nome de Domínio

Endpoint:oss-accelerate.aliyuncs.com
Nome de Domínio do Bucket: [BucketName].oss-accelerate.aliyuncs.com

Exemplos de Acesso

ossutil

O exemplo a seguir baixa arquivos de um bucket entre regiões em uma instância ECS na região de Singapura usando o ossutil 2,0. Antes de começar, instale e configure o ossutil 2,0. É possível definir o endpoint de aceleração de transferência durante a configuração ou especificá-lo com o parâmetro -e.

ossutil cp oss://example-bucket/dest.jpg dest.jpg -e oss-accelerate.aliyuncs.com

SDK

Confira abaixo exemplos de SDK para linguagens comuns. Para outras linguagens, veja os métodos de inicialização na Referência do SDK.

Java SDK V2

Especifique o Endpoint ou configure useAccelerateEndpoint(true) para usar o domínio de aceleração de transferência. Para o código completo de inicialização, consulte OSS SDK for Java 2.0 (preview).

Método 1: Especificar o Endpoint de aceleração de transferência

String endpoint = "oss-accelerate.aliyuncs.com";
// Initialize OSS client
OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("ap-southeast-1")
        .endpoint(endpoint)
        .build();

Método 2: Definir via useAccelerateEndpoint(true)

// Initialize OSS client
OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("ap-southeast-1")
        .useAccelerateEndpoint(true)
        .build();

Java SDK V1

Informe o endpoint de aceleração de transferência ao inicializar o cliente OSS. Para o código completo de inicialização, acesse OSS Java SDK V1.

String endpoint = "oss-accelerate.aliyuncs.com";
// Initialize OSS client
OSS ossClient = OSSClientBuilder.create()
        .credentialsProvider(provider)
        .clientConfiguration(clientBuilderConfiguration)
        .region("ap-southeast-1")
        .endpoint(endpoint)
        .build();

Python SDK V2

Especifique o Endpoint ou defina use_accelerate_endpoint = True para utilizar o domínio de aceleração de transferência. Para o código completo de inicialização, consulte OSS Python SDK V2.

Método 1: Especificar o endpoint de aceleração de transferência

config.endpoint = "oss-accelerate.aliyuncs.com"
# Initialize OSS client
client = oss.Client(config)

Método 2: Configurar via use_accelerate_endpoint = True

config.use_accelerate_endpoint = True
# Initialize OSS client
client = oss.Client(config)

Python SDK V1

Defina o endpoint de aceleração de transferência durante a inicialização do cliente OSS. Para obter o código completo de inicialização, veja Inicialização.

endpoint = "oss-accelerate.aliyuncs.com"
# Initialize OSS client instance
bucket = oss.Bucket(auth, endpoint, bucket, region="ap-southeast-1")

Go SDK V2

Especifique o Endpoint ou use WithUseAccelerateEndpoint(true) para ativar a aceleração de transferência. O código completo de inicialização está em OSS Go SDK V2.

Método 1: Especificar o endpoint de aceleração de transferência

// Configure OSS client, set credentials provider and service region
config := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("ap-southeast-1").
        WithEndpoint("oss-accelerate.aliyuncs.com")

// Initialize OSS client instance
client := oss.NewClient(config)

Método 2: Definir via WithUseAccelerateEndpoint(true)

// Configure OSS client, set credentials provider and service region
config := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("ap-southeast-1").
        WithUseAccelerateEndpoint(true)

// Initialize OSS client instance
client := oss.NewClient(config)

Go SDK V1

Informe o endpoint de aceleração de transferência ao inicializar o cliente OSS. Para o código completo de inicialização, consulte Configurar um cliente (Go SDK V1).

// Create OSS client instance
client, _ := oss.New(
        "oss-accelerate.aliyuncs.com",
        "",
        "",
        oss.SetCredentialsProvider(&provider),
        oss.AuthVersion(oss.AuthV4),
        oss.Region("ap-southeast-1"),
)

Domínio CNAME

Trata-se de um domínio CNAME dedicado gerado pelo OSS para vinculação de domínio personalizado. Ao Acessar o OSS por meio de um nome de domínio personalizado, aponte o CNAME do seu domínio personalizado para este endereço. Essa configuração é ideal para hospedar recursos estáticos, como imagens e scripts de sites.

Observações de uso

Apenas resolução de DNS: O domínio CNAME serve exclusivamente para a resolução de DNS de domínios personalizados e não permite acesso direto
Acesso via nome de domínio personalizado: Após concluir a vinculação do domínio, acesse os recursos do OSS através do seu domínio personalizado
Suporte regional: Atualmente compatível com as regiões China (Hangzhou), China (Xangai), China (Qingdao) e Singapura

Formato do Domínio

O OSS atribui um domínio CNAME dentro da região para cada bucket. Diferentes buckets podem receber domínios distintos.

Domínio do Bucket: [BucketName].[RegionId].[CnameDomain] (por exemplo, example-***.cn-hangzhou.taihang***.cn)

Suporte a protocolos

Protocolo HTTP/HTTPS

Todos os endpoints e domínios de bucket suportam HTTP e HTTPS. Em ambientes de produção, utilize HTTPS para garantir a transmissão segura de dados.

Protocolo IP

Todas as regiões oferecem suporte a IPv4. Algumas regiões também permitem acesso dual-stack (IPv4/IPv6), possibilitando que clientes IPv6 se conectem diretamente ao OSS. Nenhuma configuração especial no cliente é necessária. O DNS resolve automaticamente e prioriza endereços IPv6 em ambientes IPv6 ou dual-stack. Instâncias ECS em redes clássicas não suportam acesso IPv4 ou IPv6 ao OSS.

Como verificar o suporte a IPv6 para Endpoints?

Use dig AAAA para verificar se um endpoint suporta IPv6.

dig AAAA ap-southeast-1.oss.aliyuncs.com

Se houver suporte a IPv6, a ANSWER SECTION exibirá registros AAAA.

ap-southeast-1.oss.aliyuncs.com. 60 IN  AAAA    240b:4000:f10::2c5

Documentação relacionada

Lista de Regiões e Endpoints