Pedidos canónicos

Os pedidos canónicos definem os elementos de um pedido que um utilizador tem de incluir quando envia pedidos autenticados com assinatura V4, como URLs assinados, para o Cloud Storage.

Vista geral

Um pedido canónico é uma string que representa um pedido HTTP específico ao Cloud Storage. Usa um pedido canónico juntamente com uma chave criptográfica, como uma chave RSA, para criar uma assinatura que é incluída no pedido real como autenticação.

Um pedido canónico inclui informações como o verbo HTTP, os parâmetros da string de consulta e os cabeçalhos que se espera que sejam usados no pedido real, bem como o objeto, o contentor ou outro recurso a ser pedido.

Um pedido canónico garante que, quando o Cloud Storage recebe o pedido, consegue calcular a mesma assinatura que calculou. Se a versão e a versão calculada pelo Cloud Storage não corresponderem, o pedido falha.

Estrutura

Os pedidos canónicos têm a seguinte estrutura, incluindo a utilização de novas linhas entre cada elemento:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

Verbos HTTP

Os pedidos assinados podem usar os seguintes verbos HTTP, que têm de ser especificados como parte do pedido canónico:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 Só é possível usar URLs assinados para pedidos POST que iniciem um carregamento retomável. Consulte o artigo Usar URLs assinados com carregamentos retomáveis para mais informações.

Caminho do recurso

Os pedidos canónicos incluem o caminho para o recurso ao qual o pedido se aplica. O caminho para o recurso é tudo o que se segue ao nome do anfitrião, mas precede qualquer string de consulta.

Por exemplo, se o URL do Cloud Storage for https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, o caminho para o recurso é /example-bucket/cat-pics/tabby.jpeg.

Se usar um URL do Cloud Storage alternativo, como https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg , o caminho para o recurso é /cat-pics/tabby.jpeg.

Para ver pontos finais de URL adicionais que podem ser usados com URLs assinados, consulte os pontos finais de pedidos da API XML.

Quando define o caminho do recurso, tem de codificar em percentagem os seguintes carateres reservados: ?=!#$&'()*+,:;@[]" qualquer outra codificação em percentagem usada no URL também deve ser incluída no caminho do recurso.

String de consulta canónica

Os pedidos canónicos especificam cada parâmetro de string de consulta que será posteriormente incluído em qualquer pedido assinado que use a assinatura relevante, com exceção do parâmetro de string de consulta X-Goog-Signature ou X-Amz-Signature. A string de consulta especificada no pedido canónico é denominada string de consulta canónica

A string de consulta é tudo o que aparece depois do ponto de interrogação (?) no final do caminho do recurso.

Por exemplo, se o URL do Cloud Storage for https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, a string de consulta é generation=1360887697105000&userProject=my-project.

Ao construir a string de consulta canónica:

  • Os parâmetros na string de consulta têm de ser ordenados por nome através de uma ordenação lexicográfica por valor de ponto de código.

  • Cada parâmetro na string de consulta tem de ser separado com &.

  • Se a string de consulta canónica estiver vazia, esta parte do pedido canónico geral é apenas uma nova linha (\n).

Parâmetros de string de consulta obrigatórios

A maioria dos parâmetros da string de consulta é adicionada conforme necessário, mas os seguintes têm de ser incluídos no seu pedido canónico quando pretender usá-lo para criar um URL assinado:

  • X-Goog-Algorithm: o algoritmo que vai usar para assinar o URL. Os valores válidos são GOOG4-RSA-SHA256 e GOOG4-HMAC-SHA256.
  • X-Goog-Credential: as credenciais que vai usar para assinar o URL. As credenciais consistem num autorizador e num âmbito de credenciais fornecidos no formato: AUTHORIZER%2FCREDENTIAL_SCOPE. O autorizador pode ser um nome de conta de serviço ou um ID de acesso da chave HMAC.
  • X-Goog-Date: a data e a hora em que o URL assinado fica utilizável, no formato básico ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: a duração do URL assinado, medida em segundos a partir de X-Goog-Date. O valor de expiração mais longo é de 604 800 segundos (7 dias).
  • X-Goog-SignedHeaders: uma lista de nomes de cabeçalhos separados por ponto e vírgula definidos no pedido canónico. Estes também são conhecidos como cabeçalhos assinados. host tem de ser um dos nomes dos cabeçalhos.

Estes parâmetros da string de consulta têm de ser usados posteriormente no próprio URL assinado, juntamente com o parâmetro da string de consulta X-Goog-Signature, que contém a assinatura que autentica o pedido.

Cabeçalhos canónicos

Os pedidos canónicos incluem todos os cabeçalhos que têm de ser incluídos posteriormente em pedidos assinados que usam a assinatura relevante. No entanto, tais pedidos assinados podem incluir cabeçalhos adicionais que não foram especificados no pedido canónico, exceto conforme indicado nos cabeçalhos obrigatórios. Os cabeçalhos especificados no pedido canónico são denominados cabeçalhos canónicos.

Os cabeçalhos canónicos podem incluir cabeçalhos personalizados, bem como cabeçalhos de extensão que começam com x-goog-.

Ao especificar cabeçalhos canónicos, tenha em atenção o seguinte:

  • Certifique-se de que todos os nomes dos cabeçalhos estão em minúsculas.
  • Ordene todos os cabeçalhos por nome do cabeçalho através de uma ordenação lexicográfica por valor do ponto de código.
  • Separe cada cabeçalho com uma nova linha (\n).
  • Elimine nomes de cabeçalhos duplicados criando um nome de cabeçalho com uma lista de valores separados por vírgulas. Certifique-se de que não existe espaço em branco entre os valores e de que a ordem da lista separada por vírgulas corresponde à ordem em que os cabeçalhos aparecem no seu pedido. Para mais informações, consulte a secção 3.2 do RFC 7230.
  • Substitua qualquer espaço em branco de dobragem ou novas linhas (CRLF ou LF) por um único espaço. Para mais informações sobre a união de espaços em branco, consulte a secção 3.2.4 do RFC 7230.

  • Remova todos os espaços em branco à volta dos dois pontos que aparecem após o nome do cabeçalho.

    Por exemplo, a utilização do cabeçalho personalizado x-goog-acl: private sem remover o espaço após os dois pontos devolve um erro 403 Forbidden, porque a assinatura do pedido que calcula não corresponde à assinatura que o Cloud Storage calcula.

Exemplo

Se tiver o seguinte conjunto de cabeçalhos:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

A construção dos cabeçalhos canónicos no pedido canónico seria:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

Cabeçalhos canónicos obrigatórios

A maioria dos cabeçalhos, como content-type, é adicionada conforme necessário, mas os seguintes cabeçalhos têm de ser sempre definidos nos cabeçalhos canónicos se pretender usá-los no pedido assinado:

  • host: o URI usado para aceder ao Cloud Storage.
  • Cabeçalhos com o prefixo x-goog-. O único cabeçalho deste tipo que é opcional incluir como cabeçalho canónico é x-goog-content-sha256.
  • Cabeçalhos com o prefixo x-amz-. O único cabeçalho deste tipo que é opcional incluir como cabeçalho canónico é x-amz-content-sha256.

Cabeçalhos assinados

Um cabeçalho assinado é a parte do nome de um cabeçalho canónico.

Para criar a lista de cabeçalhos assinados, converta todos os nomes dos cabeçalhos em minúsculas, ordene-os por código de carateres e use um ponto e vírgula (;) para separar cada um.

Exemplo

Se tiver o seguinte conjunto de cabeçalhos:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

A construção dos cabeçalhos assinados no pedido canónico seria:

content-type;host;x-goog-meta-reviewer

Payload

  • Se o pedido canónico for usado para criar um URL assinado, este valor deve ser a string UNSIGNED-PAYLOAD.

  • Se o seu pedido canónico for usado para criar uma assinatura para utilização num cabeçalho Authorization:

    • Use UNSIGNED-PAYLOAD se quiser permitir payloads arbitrários como parte do pedido.

    • Use UNSIGNED-PAYLOAD se o pedido iniciar um carregamento retomável, porque o cabeçalho x-goog-content-sha256 é ignorado para carregamentos retomáveis.

    • Se quiser permitir apenas uma carga útil específica, este valor deve ser um hash SHA-256 codificado no formato hexadecimal e em letras minúsculas da carga útil pretendida. Para exigir um payload vazio, use uma string vazia como entrada para a função hash. Um exemplo de um payload com hash (neste caso, um payload vazio) é:

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Exemplo

Segue-se um exemplo de um pedido canónico formado corretamente, com novas linhas apresentadas como novas linhas reais e não \n:

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

O que se segue?