Endpoints de solicitação

Nesta página, explicamos os diferentes endpoints de solicitação (URIs) que podem ser usados para acessar o Cloud Storage.

Solicitações comuns de API

Use os seguintes URIs para fazer solicitações diretamente a uma das APIs do Cloud Storage:

API JSON

Para solicitações gerais da API JSON, exceto uploads de objetos, use o endpoint a seguir, substituindo VALUES_IN_BRACKETS pelos valores adequados:
```
https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
```
Use o endpoint a seguir para uploads de objeto da API JSON, substituindo VALUES_IN_BRACKETS pelos valores adequados:
```
https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
```
Use o endpoint a seguir para solicitações em lote, substituindo VALUES_IN_BRACKETS pelos valores adequados:
```
https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
```
Como opção, é possível usar o endpoint a seguir para downloads de objeto da API JSON, substituindo VALUES_IN_BRACKETS pelos valores apropriados:
```
https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
```

Os endpoints da API JSON só aceitam solicitações HTTPS.

API XML

Para solicitações comuns da API XML (em inglês), é possível usar o endpoint em estilo de hospedagem virtual ou estilo de caminho, substituindo VALUES_IN_BRACKETS pelos valores adequados:

Estilo de hospedagem virtual:
```
https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
```
Estilo de caminho:
```
https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME
```
Observação: endpoints em estilo de hospedagem virtual não podem ser usados para acessar buckets com nome de domínio. Em vez deles, use endpoints em estilo de caminho ou um redirecionamento CNAME.

Outra opção para uploads e downloads é usar os endpoints dedicados da API XML oferecidos pelo Cloud Storage. Esses endpoints de upload e download podem melhorar um pouco o desempenho durante a transferência de grandes quantidades de dados.

Para uploads, é possível usar o endpoint em estilo de hospedagem virtual ou de caminho, substituindo VALUES_IN_BRACKETS pelos valores adequados:

Estilo de hospedagem virtual:
```
https://BUCKET_NAME.storage-upload.googleapis.com/OBJECT_NAME
```
Estilo de caminho:
```
https://storage-upload.googleapis.com/BUCKET_NAME/OBJECT_NAME
```
Para downloads, é possível usar o endpoint em estilo de hospedagem virtual ou de caminho, substituindo VALUES_IN_BRACKETS pelos valores adequados:

Estilo de hospedagem virtual:
```
https://BUCKET_NAME.storage-download.googleapis.com/OBJECT_NAME
```
Estilo de caminho:
```
https://storage-download.googleapis.com/BUCKET_NAME/OBJECT_NAME
```

Todos os endpoints da API XML são compatíveis com criptografia SSL (Secure Sockets Layer), o que significa que é possível usar HTTP ou HTTPS. Recomendamos o uso de HTTPS, especialmente se você faz autenticação no Cloud Storage usando OAuth 2.0.

Para conexões por proxy, consulte o tópico Solução de problemas para conhecer as práticas recomendadas.

Como codificar partes do caminho de URI

Além de seguir as considerações gerais de nomeação de buckets e de objetos, é necessário codificar os seguintes caracteres quando aparecerem no nome do objeto ou na string de consulta de um URI de solicitação para garantir a compatibilidade entre as ferramentas do Cloud Storage:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ] e caracteres de espaço.

Por exemplo, se você enviar uma solicitação GET à API JSON referente ao objeto denominado foo??bar no bucket example-bucket, seu URI de solicitação deverá ser:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

Nem todos os caracteres listados precisam ser codificados em todos os cenários: por exemplo, o caractere / precisa ser codificado apenas quando você reescreve ou copia com a API JSON e somente para o objeto de origem.

Para mais informações sobre o uso de códigos percentuais para URIs, consulte a Seção 3.3 Path (em inglês) na RFC 3986. A codificação costuma ser processada por bibliotecas de cliente, como as bibliotecas de cliente do Cloud Storage (em inglês), para que você passe a elas o nome do objeto bruto.

Endpoints do Console do Cloud

Ao usar o Console do Cloud, você acessa recursos diferentes usando os seguintes URLs:

Recurso	URL
Lista de buckets de um projeto	`https://console.cloud.google.com/storage/browser?project=PROJECT_ID`
Lista de objetos de um bucket	`https://console.cloud.google.com/storage/browser/BUCKET_NAME`
Detalhes de um objeto	`https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME`

Redirecionamentos `CNAME`

Um redirecionamento CNAME é um registro DNS especial que permite usar URIs de seu próprio domínio para acessar recursos no Cloud Storage por meio da API XML sem revelar os URIs reais da API XML. Para isso, é necessário adicionar o seguinte URI à porção do nome do host do registro CNAME:

c.storage.googleapis.com.

Por exemplo, se o domínio for example.com e você quiser disponibilizar mapas de viagem para seus clientes: Crie um bucket no Cloud Storage denominado travel-maps.example.com e depois crie um registro CNAME no DNS que redirecione as solicitações de travel-maps.example.com para o URI do Cloud Storage. Para fazer isso, publique o seguinte registro CNAME no DNS:

NAME                      TYPE     DATA
travel-maps.example.com   CNAME    c.storage.googleapis.com.

Com isso, seus clientes podem usar este URL para acessar um mapa de Paris:

http://travel-maps.example.com/paris.jpg

O serviço de registro de domínio precisa ter como administrar seu domínio, incluindo adicionar um registro de recurso CNAME. Por exemplo, no Google Domains, as instruções para adicionar um registro de recurso estão na página de Ajuda do Google Domains, na seção suspensa Registros de recurso.

Downloads por navegadores autenticados

Os downloads por navegador autenticado usam autenticação baseada em cookies. A autenticação baseada em cookies solicita que os usuários façam login nas respectivas Contas do Google para definir a identidade. Para realizar o download pelo navegador, a Conta do Google especificada precisa ter a permissão adequada para acessar o recurso, que é concedida por meio de políticas do IAM ou de listas de controle de acesso.

Para fazer o download de um objeto usando a autenticação baseada em cookies, use o URL a seguir substituindo VALUES_IN_BRACKETS pelos valores adequados:

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

Por exemplo, se você compartilhou uma imagem london.jpg do bucket example-maps, o URL será:

https://storage.cloud.google.com/example-maps/london.jpg

O uso de HTTPS é necessário ao realizar downloads do navegador autenticado, as tentativas de usar o HTTP fazem o redirecionamento para HTTPS. Para mais informações sobre downloads do navegador autenticado, consulte Autenticação baseada em cookies.

Acesso a objetos públicos

Todas as solicitações para o URI storage.cloud.google.com exigem autenticação. Isso se aplica até mesmo quando allUsers tem permissão para acessar um objeto. Caso queira que os usuários façam o download de objetos acessíveis anonimamente sem autenticação, use o URI storage.googleapis.com documentado nas solicitações de API diretas. Para detalhes e exemplos, consulte Como acessar dados públicos.