Visão geral da API XML

Neste documento, você terá uma visão geral da API XML do Cloud Storage e destina-se a desenvolvedores de software. Pressupomos que você tenha familiaridade com serviços RESTful e programação de Web e que saiba como criar aplicativos que operam por meio de solicitações HTTP. Se isso não descreve você, considere uma das seguintes alternativas:

Visão geral

A API Cloud Storage XML é uma interface RESTful que permite gerenciar dados do Cloud Storage de maneira programática. Como uma API RESTful, ela usa as informações do método e as informações de escopo para definir as operações a serem executadas:

Você usa métodos HTTP para executar operações no recurso especificado no escopo. Para ver uma lista de operações disponíveis na API XML, consulte Métodos de solicitação da API XML.

O acesso ao Cloud Storage por meio da API XML é útil quando você usa ferramentas e bibliotecas que precisam trabalhar em diferentes provedores de armazenamento ou ao migrar de outro provedor de armazenamento para o Cloud Storage. Nesse caso, basta fazer algumas alterações simples nas ferramentas e bibliotecas atuais para começar a enviar solicitações ao Cloud Storage. Para mais informações sobre como migrar para o Cloud Storage, consulte Como migrar do Amazon S3 para o Google Cloud Storage.

Pedidos

A API XML do Cloud Storage fornece uma interface da Web para fazer solicitações HTTP e processar respostas HTTP. A API é compatível com os protocolos HTTP/1.1, HTTP/2 e HTTP/3. Cada solicitação implementa um método HTTP padrão. Junto com esses métodos, você pode usar vários cabeçalhos de solicitação HTTP.

Autenticação

Todas as solicitações para o Cloud Storage precisam ser autenticadas, com exceção das solicitações feitas para objetos ou buckets acessíveis anonimamente. Para informações detalhadas sobre como definir os cabeçalhos de autorização para solicitações do Cloud Storage, consulte Autenticação.

Endpoints

A maioria das solicitações da API XML do Cloud Storage usa o seguinte URI para acessar buckets e objetos:

storage.googleapis.com

É possível definir ainda mais o escopo adicionando um bucket e um objeto ao URI. O URL resultante pode assumir duas formas:

BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

É possível usar o URI do Cloud Storage com solicitações não seguras (HTTP) e solicitações seguras (HTTPS) que usam criptografia segura da camada de soquetes (SSL).

Para endpoints adicionais, como endpoints de upload e download dedicados para a API XML, consulte Endpoints de solicitação.

Cabeçalhos e parâmetros de string de consulta

A API XML do Cloud Storage é compatível com cabeçalhos de solicitação HTTP. Também é compatível com vários cabeçalhos de solicitação de extensão (personalizados), que têm um prefixo x-goog-. Os requisitos de cabeçalho de solicitação variam de acordo com o tipo de solicitação que você está fazendo. Alguns cabeçalhos de solicitação usados com frequência incluem:

Cabeçalho de solicitação Descrição Utilização
Authorization A string de autenticação para solicitações. Obrigatório para todas as solicitações autenticadas.
Content-Length O tamanho do corpo da solicitação (excluindo cabeçalhos) em bytes. Obrigatório para todas as solicitações PUT e POST, exceto transferências em partes.
Content-Type O tipo MIME do corpo da solicitação, como application/xml ou text/html. Recomendado para solicitações que contêm um corpo de entidade.
Date A data e a hora da solicitação. Obrigatório para todas as solicitações.
Host O URI da solicitação. Obrigatório para todas as solicitações.
x-goog-project-id O ID do projeto que você deseja usar. Necessário para criar buckets ou listar buckets, exceto quando você estiver usando a API XML para interoperabilidade, como para compatibilidade com o Amazon S3. Para mais informações, consulte Como migrar do Amazon S3 para o Google Cloud Storage.

A API XML do Cloud Storage também é compatível com vários parâmetros de string de consulta que podem ser usados para definir o escopo das solicitações. Anexe os parâmetros de string de consulta à parte do caminho HTTP da solicitação com a seguinte sintaxe:

PATH_TO_OBJECT/?PARAMETER=VALUE&PARAMETER=VALUE...

Para uma lista completa de cabeçalhos da API XML e parâmetros de string de consulta, consulte Cabeçalhos HTTP e parâmetros de string de consulta.

Exemplo de solicitação

Uma solicitação autenticada típica do Cloud Storage é mostrada no exemplo a seguir. Essa solicitação recupera uma lista de objetos armazenados em um bucket chamado travel-maps. A solicitação limita a lista de objetos apenas àqueles que têm o prefixo /europe/france.

GET /?prefix=/europe/france/ HTTP/1.1
Host: travel-maps.storage.googleapis.com
Date: Wed, 17 Feb 2010 15:31:56 -0800
Content-Length: 0
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

Respostas

A API XML do Cloud Storage retorna cabeçalhos de resposta HTTP padrão e vários cabeçalhos de resposta de extensão (personalizados). Os cabeçalhos de resposta variam de acordo com a operação realizada. Alguns cabeçalhos de resposta usados com frequência incluem:

Cabeçalho de resposta Descrição
Cache-Control A configuração de controle de cache para a resposta.
Content-Length O tamanho do corpo da resposta (excluindo cabeçalhos) em bytes.
Content-Type O tipo MIME do corpo da resposta, como application/xml ou text/html.
Date A data e a hora da resposta.
ETag Uma tag de entidade HTTP 1.1, que você pode usar para determinar

se um objeto foi alterado.

As respostas também podem incluir um código de status. O Cloud Storage usa códigos de status HTTP padrão. Uma resposta de erro inclui um documento XML no corpo da resposta, com informações sobre as condições do erro. Para ver uma lista de códigos de status usados pela API XML, consulte Status HTTP e códigos de erro.

Uma resposta típica do Cloud Storage é mostrada no exemplo a seguir. Esse exemplo é uma resposta a uma solicitação para listar o conteúdo de um bucket. O nome do bucket é travel-maps, e a solicitação tem escopo para que apenas objetos com o prefixo /europe/france/ sejam retornados na lista.

HTTP/1.1 200 OK
Content-Length: 4061
Content-Type: application/xml
Date: Wed, 17 Feb 2010 23:31:57 GMT
Cache-Control: private, max-age=0

<?xml version='1.0' encoding='utf-8'?>
<ListBucketResult xmlns='http://doc.storage.googleapis.com/2010-03-01'>
  <Name>travel-maps</Name>
  <Prefix>/europe/france/</Prefix>
  <Marker></Marker>
  <IsTruncated>false</IsTruncated>
  <Contents>
    <Key>europe/france/cannes.jpg</Key>
    <LastModified>2010-02-17T22:11:12.487Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
  <Contents>
    <Key>europe/france/paris.jpg</Key>
    <LastModified>2010-02-17T22:09:57.457Z</LastModified>
    <ETag>"53fc311c15eda0a031809982ccf92aac"</ETag>
    <Size>5061631</Size>
    <StorageClass>STANDARD</StorageClass>
    <Owner>
      <ID>84fac329bceSAMPLE777d5d22b8SAMPLE77d85ac2SAMPLE2dfcf7c4adf34da46</ID>
      <DisplayName></DisplayName>
    </Owner>
  </Contents>
</ListBucketResult>