Access OSS via endpoints and bucket domains - Object Storage Service: Central de Documentação do Alibaba Cloud

Conceitos principais

Um endereço de acesso padrão do oss é composto por vários componentes hierárquicos. Compreender corretamente os quatro conceitos principais a seguir é essencial para acessar o oss adequadamente:

Conceito	Descrição	Formato	Finalidade
ID da região	Identificador geral da região	`<region-id>`, por exemplo `ap-southeast-1`	Usado em cenários como assinaturas V4 em SDKs e ossutil
ID da região dedicada	Identificador de região dedicada do oss	`oss-<region-id>`	Usado para compor Endpoints, parâmetros de solicitação de API e parâmetros de resposta
Endpoint	Endereço de acesso ao service	`oss-<region-id>.aliyuncs.com`	Configurado em SDKs e no ossutil para estabelecer uma conexão de rede com o service oss
Nome de domínio do bucket	Endereço de acesso de um bucket específico	`<bucket-name>.oss-<region-id>.aliyuncs.com`	Aplicável em cenários como acesso direto pelo navegador, geração de URLs assinadas, hospedagem de sites estáticos e resolução CNAME de domínio personalizado

Esses quatro conceitos formam uma hierarquia: o ID da região identifica uma localização geográfica, para a qual o oss atribui um ID da região dedicada correspondente. O ID da região dedicada se combina com o sufixo do nome de domínio para formar o Endpoint (endereço de acesso ao service). Para acessar um bucket específico, utilize o nome de domínio do bucket (endereço de acesso ao recurso), formado pela combinação do nome do bucket com o Endpoint.

Nota

Para consultar os IDs de cada região, consulte Regions and endpoints.

Pré-requisitos

Antes de acessar o oss por meio de uma API ou SDK, obtenha um AccessKey para autenticação de identidade. Um AccessKey consiste em um AccessKey ID e um AccessKey secret.

Para obter um AccessKey:

Faça logon na página de gerenciamento de AccessKey do console Resource Access Management (RAM).
Clique em Create AccessKey para criar um novo AccessKey ou ative um AccessKey desativado.
Selecione a caixa de seleção I acknowledge the security risks of using an Alibaba Cloud account AccessKey e clique em Continue using the Alibaba Cloud account AccessKey.

Para mais informações, consulte Create an AccessKey pair.

Tipos de nome de domínio

O oss fornece diferentes tipos de nomes de domínio de acesso com base nos ambientes de rede e nos requisitos de desempenho.

Importante

Devido a uma alteração de política para 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 restrições 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, deverá vincular um certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao Console oss, pois o console impõe o uso de https.

Tipo de nome de domínio	Cenários aplicáveis	Formato do nome de domínio	Características de faturamento	Ativação necessária
Public endpoint	Acesso pela rede pública a partir de aplicações web, clientes móveis, entre outros	Endpoint: `oss-<region-id>.aliyuncs.com` Nome de domínio do bucket: `<bucket-name>.oss-<region-id>.aliyuncs.com`	Faturado por tráfego de rede pública	Disponível por padrão
Internal endpoint	Acesso pela rede interna dentro da mesma região do Alibaba Cloud (por exemplo, a partir do ecs)	Endpoint: `oss-<region-id>-internal.aliyuncs.com` Nome de domínio do bucket: `<bucket-name>.oss-<region-id>-internal.aliyuncs.com`	Sem taxas de tráfego	Disponível por padrão
Transfer acceleration domain name	Upload/download de alta velocidade entre regiões e fronteiras	Endpoint: `oss-accelerate.aliyuncs.com` Nome de domínio do bucket: `<bucket-name>.oss-accelerate.aliyuncs.com`	Faturado por aceleração de transferência	É necessário ativar o recurso transfer acceleration
CNAME domain name	Vinculação de nome de domínio personalizado (como hospedagem de recursos estáticos)	Nome de domínio do bucket: `<bucket-name>.<region-id>.<cname-domain>`	Faturado por tráfego de rede pública	Você deve acessar o oss por meio de um nome de domínio personalizado
Dual-stack domain name	Acesso ao oss em ambientes de rede IPv6	Endpoint: `<region-id>.oss.aliyuncs.com` Nome de domínio do bucket: `<bucket-name>.<region-id>.oss.aliyuncs.com`	O acesso pela rede pública é faturado por tráfego de rede pública; o acesso pela rede interna não gera taxas de tráfego	Suportado em algumas regiões

Endpoint público

Projetado para acesso à internet, este endpoint é adequado para cenários como aplicações web, clientes móveis e acesso entre regiões. Os SDKs usam o endpoint público por padrão. Basta especifique o ID da região para concluir a configuração, sem necessidade de especifique o Endpoint explicitamente.

Endpoint interno

Destinado à rede interna do Alibaba Cloud, este endpoint é ideal para cenários como instâncias ecs acessando o oss na mesma região. O acesso interno evita taxas de tráfego de rede pública e oferece conexões de rede mais estáveis com menor latência. Recomendações de uso:

Otimização da configuração de DNS

Ao usar um endpoint interno, recomendamos fortemente configure os endereços DNS privados do Alibaba Cloud (100.100.2.136 e 100.100.2.138) para garantir a obtenção do endereço VIP correto e evitar exceções de acesso ao oss causadas por problemas de resolução de DNS.
Integridade da configuração de roteamento do segmento de rede VIP

O oss atribui um intervalo de endereços fixo para o segmento de rede VIP interno de cada região, e o sistema alterna dinamicamente os endereços IP dentro desse segmento especificado. Quando dispositivos locais e data centers acessam o oss pela rede interna, a configuração de roteamento deve abranger todo o segmento de rede VIP; caso contrário, um roteamento incompleto pode causar interrupções na conexão. Para informações sobre o segmento de rede VIP interno de cada região, consulte Regions and endpoints.

Importante
Certifique-se de que sua configuração de roteamento cubra completamente o segmento de rede VIP para evitar problemas de conectividade de rede causados por configurações incompletas. Se a disponibilidade do service oss for afetada devido à falta de configuração do segmento de rede VIP, as perdas resultantes serão de responsabilidade da parte que realizou a configuração.

Ao acessar o oss entre regiões por meio de conexões de peering vpc ou cloud Enterprise Network (CEN), adicione o segmento de rede VIP do endpoint interno do oss na região par à tabela de rotas da vpc. O segmento de rede VIP é fixo, e a configuração de roteamento permanece válida a longo prazo, sem falhas de conectividade causadas por alterações no segmento.
Configuração de regras do grupo de segurança

Ao utilizar uma instância ecs para acessar o oss pela rede interna, as regras do grupo de segurança não devem bloquear o acesso a nenhum segmento de rede VIP, garantindo assim a conectividade da rede.

Como gerar uma URL publicamente acessível para um arquivo enviado por meio de um endpoint interno?

Um arquivo armazenado no oss pode ser acessado por qualquer endpoint, independentemente de ter sido enviado por um endpoint interno ou público. O endpoint usado para o upload não afeta a forma como o arquivo é acessado. Se você enviou um arquivo por meio de um endpoint interno, basta substituir o nome de domínio pelo endpoint público da região correspondente ao gerar a URL de acesso.

Por exemplo, se você enviou o arquivo example.jpg pelo endpoint interno oss-cn-hangzhou-internal.aliyuncs.com, a URL de acesso interno será:

https://bucket.oss-cn-hangzhou-internal.aliyuncs.com/example.jpg

Para gerar uma URL publicamente acessível, substitua o endpoint interno pelo endpoint público:

https://bucket.oss-cn-hangzhou.aliyuncs.com/example.jpg

Nome de domínio de aceleração de transferência

Trata-se de um nome de domínio dedicado que fica disponível após a ativação do recurso transfer acceleration. Ele otimiza o caminho de transmissão de dados por meio de nós de aceleração global, sendo adequado para cenários de upload/download de alta velocidade entre regiões e fronteiras, melhorando significativamente a qualidade da rede em acessos de longa distância.

Nome de domínio CNAME

É um nome de domínio de resolução dedicado que o oss gera para um bucket, utilizado em cenários de vinculação de nome de domínio personalizado. Quando você precisar acessar o oss por meio de um nome de domínio personalizado, aponte o registro CNAME do domínio personalizado para este nome de domínio, em vez de usar o endpoint público.

O oss atribui um nome de domínio CNAME dentro da região para cada bucket, e buckets diferentes podem receber nomes de domínio distintos. Em comparação com todos os buckets compartilhando o mesmo endpoint público, os nomes de domínio CNAME distribuem os links de acesso, proporcionando maior disponibilidade. Observações de uso:

Uso exclusivo para resolução de DNS: O nome de domínio CNAME serve apenas para a configuração de resolução DNS de um domínio personalizado e não suporta acesso direto.
Acesso via domínio personalizado: Após concluir a vinculação do domínio personalizado e a configuração da resolução CNAME, acesse os recursos do oss através do domínio personalizado.

Nome de domínio dual-stack

Este Endpoint suporta acesso dual-stack IPv4 e IPv6, permitindo que clientes em ambientes de rede IPv6 se conectem diretamente aos recursos do oss. Ao usar um nome de domínio dual-stack, os clientes não exigem configurações especiais; em um ambiente de rede IPv6 puro ou dual-stack, o DNS resolve automaticamente e prioriza o uso de endereços IPv6 para estabelecer conexões. Para informações sobre os nomes de domínio dual-stack de cada região, consulte Regions and endpoints.

Como verifique o suporte a IPv6 de um nome de domínio dual-stack?

Use o comando dig AAAA para verifique se um Endpoint dual-stack suporta acesso IPv6. Tome a região Singapore como exemplo:

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

Se houver suporte a IPv6, a ANSWER SECTION na saída do comando exibirá um registro AAAA:

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

Exemplos de uso

Navegador

Importante

Ao acessar arquivos como HTML e imagens pelos nomes de domínio de acesso fornecidos pelo oss, o navegador força o download em vez de permitir a visualização online. Para habilitar a visualização de arquivos, acesse o oss por meio de um nome de domínio personalizado.

O exemplo a seguir demonstra como obter a URL assinada de um arquivo em um bucket privado por meio do console. Para outras formas de obter URLs assinadas, consulte Use presigned URLs to download or preview files.

Acesse a Lista de buckets e clique em no bucket desejado.
Clique em no nome do arquivo alvo ou em View Details na coluna Actions, defina Domain Name como Public Endpoint e clique em Copy Object URL.
Acesse a URL em um navegador.

ossutil

O exemplo a seguir demonstra como usar o ossutil command-line tool para baixe um arquivo. O ossutil usa o endpoint público por padrão, mas você pode especifique outros tipos de Endpoints por meio do parâmetro -e:

ossutil cp oss://<bucket-name>/<object-name> <local-path> -e <endpoint>

Configurações de parâmetros para diferentes tipos de nome de domínio:

Tipo de nome de domínio	Configuração do parâmetro
Endpoint público (padrão)	Omita o parâmetro `-e` ou especifique `-e oss-<region-id>.aliyuncs.com`
Endpoint interno	`-e oss-<region-id>-internal.aliyuncs.com`
Nome de domínio de aceleração de transferência	`-e oss-accelerate.aliyuncs.com`
Nome de domínio personalizado	`-e <custom-domain> --addressing-style cname`

SDK

A seguir são apresentados exemplos de inicialização dos SDKs V2 para linguagens comuns. Os SDKs usam o endpoint público por padrão, e basta especifique a Região para concluir a configuração.

Java

OSSClient client = OSSClient.newBuilder()
        .credentialsProvider(provider)
        .region("<region-id>")
        .build();

Para o código completo de inicialização, consulte OSS Java SDK V2.

Python

cfg = oss.config.load_default()
cfg.credentials_provider = credentials_provider
cfg.region = '<region-id>'

client = oss.Client(cfg)

Para o código completo de inicialização, consulte OSS Python SDK V2.

Go

cfg := oss.LoadDefaultConfig().
        WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
        WithRegion("<region-id>")

client := oss.NewClient(cfg)

Para o código completo de inicialização, consulte OSS Go SDK V2.

PHP

$cfg = Configuration::loadDefault();
$cfg->setCredentialsProvider($provider);
$cfg->setRegion('<region-id>');

$client = new Oss\Client($cfg);

Para o código completo de inicialização, consulte OSS PHP SDK V2.

C#

var cfg = OSS.Configuration.LoadDefault();
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
cfg.Region = "<region-id>";

using var client = new OSS.Client(cfg);

Para o código completo de inicialização, consulte OSS C# SDK V2.

Node.js

const client = new OSS({
    region: 'oss-<region-id>',
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    authorizationV4: true,
});

Para o código completo de inicialização, consulte OSS Node.js SDK.

Alternar o tipo de nome de domínio

Os SDKs V2 permitem alternar rapidamente o tipo de nome de domínio por meio de itens de configuração, sem a necessidade de concatenar manualmente a string do Endpoint:

Linguagem	Endpoint público	Endpoint interno	Nome de domínio de aceleração de transferência	Nome de domínio dual-stack
Java	Defina apenas `region`	`.useInternalEndpoint(true)`	`.useAccelerateEndpoint(true)`	`.useDualStackEndpoint(true)`
Python	Defina apenas `region`	`use_internal_endpoint = True`	`use_accelerate_endpoint = True`	`use_dualstack_endpoint = True`
Go	Defina apenas `Region`	`WithUseInternalEndpoint(true)`	`WithUseAccelerateEndpoint(true)`	`WithUseDualStackEndpoint(true)`
PHP	Defina apenas `setRegion`	`setUseInternalEndpoint(true)`	`setUseAccelerateEndpoint(true)`	`setUseDualStackEndpoint(true)`
C#	Defina apenas `Region`	`UseInternalEndpoint = true`	`UseAccelerateEndpoint = true`	`UseDualStackEndpoint = true`