Solicite cabeçalhos e respostas

ID da região

O REGION_ID é um código abreviado que o Google atribui com base na região que você selecionou ao criar o aplicativo. O código não corresponde a um país ou estado, ainda que alguns IDs de região sejam semelhantes aos códigos de país e estado geralmente usados. Para apps criados após fevereiro de 2020, o REGION_ID.r está incluído nos URLs do App Engine. Para apps existentes criados antes dessa data, o ID da região é opcional no URL.

Saiba mais sobre IDs de região.

OK

Use esta página de referência para ver mais detalhes sobre quais cabeçalhos HTTP são compatíveis, além dos limites de solicitação e resposta no App Engine. Para entender como funciona o recebimento de solicitações e o envio de respostas no App Engine, consulte Como as solicitações são processadas.

Cabeçalhos de solicitação

Uma solicitação HTTP recebida inclui os cabeçalhos HTTP enviados pelo cliente. Para fins de segurança, alguns cabeçalhos são limpos, alterados ou removidos por proxies intermediários antes de chegar ao app.

Cabeçalhos removidos de solicitações recebidas

Os seguintes cabeçalhos são removidos das solicitações recebidas se um cliente as enviar:

• Cabeçalhos com nomes que correspondem ao padrão X-Google-*. Esse padrão de nome é reservado para o Google.

• Cabeçalhos com nomes que correspondem a cabeçalhos específicos do App Engine. Somente correspondências exatas e indiferentes a maiúsculas são removidas. Por exemplo, os cabeçalhos chamados X-Appengine-Country ou X-AppEngine-Country serão removidos, mas X-Appengine-Cntry, não.

Além disso, os seguintes cabeçalhos são removidos das solicitações recebidas porque estão relacionados à transferência dos dados HTTP entre o cliente e o servidor:

• Accept-Encoding
• Connection
• Keep-Alive
• Proxy-Authorization
• TE
• Trailer
• Transfer-Encoding

Por exemplo, o servidor pode enviar automaticamente uma resposta compactada com gzip, dependendo do valor do cabeçalho da solicitação Accept-Encoding. O aplicativo em si não tem a necessidade de saber quais codificações de conteúdo o cliente pode aceitar.

Observação: como os cabeçalhos das entidades (cabeçalhos relacionados ao corpo da solicitação) não são limpos nem verificados, os apps não podem depender deles. Em específico, o cabeçalho da solicitação Content- MD5 é enviado sem modificações ao aplicativo. Por isso, ele pode não corresponder ao hash MD5 do conteúdo. Além disso, o cabeçalho da solicitação Content-Encoding não é verificado pelo servidor. Portanto, se o cliente enviar um corpo de solicitação compactado como gzip, ele será enviado ao aplicativo dessa maneira.

Solicitações e WSGI

O servidor determina qual objeto de aplicativo Python chamar, comparando o URL da solicitação com os padrões de URL no arquivo de configuração do aplicativo. Em seguida, o objeto do aplicativo é chamado usando os argumentos, conforme definido no padrão WSGI. O objeto do aplicativo executa ações apropriadas à solicitação. Em seguida, prepara uma resposta e a retorna como uma lista de strings.

A maioria dos aplicativos usa uma biblioteca, como webapp2, para processar solicitações WSGI. webapp2 está incluído como parte do ambiente de execução do Python 2.7.

Solicitações e CGI

Aviso: o padrão CGI está incluído para compatibilidade com versões anteriores, e o uso dele não é recomendado. Use WSGI, se possível.

O servidor determina qual script de gerenciador do Python executar comparando o URL da solicitação com os padrões de URL no arquivo de configuração do app. Em seguida, ele executa o script em um ambiente preenchido com os dados da solicitação. Conforme descrito no padrão CGI, o servidor coloca os dados da solicitação em variáveis de ambiente e no streaming de entrada padrão. O script realiza ações apropriadas à solicitação, prepara uma resposta e a coloca no streaming de saída padrão.

A maioria dos aplicativos usa uma biblioteca para analisar solicitações CGI e retornar respostas CGI, como o módulo cgi da biblioteca padrão do Python, ou uma biblioteca da Web que conheça o protocolo CGI (como webapp). Você pode consultar a documentação de CGI para detalhes sobre as variáveis de ambiente e o formato dos dados de streaming de entrada.

Cabeçalhos específicos do App Engine

Como um serviço ao aplicativo, o App Engine adiciona estes cabeçalhos a todas as solicitações:

X-Appengine-Country

País de origem da solicitação, como um código do país ISO 3166-1 alfa-2. O App Engine determina esse código com base no endereço IP do cliente. Observe que as informações do país não são derivadas do banco de dados WHOIS. É possível que um endereço IP com informações de país no banco de dados WHOIS não tenha informações de país no cabeçalho X-Appengine-Country. O app precisa processar o código especial de país ZZ (país desconhecido).

X-Appengine-Region

Nome da região de origem da solicitação. Esse valor só faz sentido no contexto do país em X -Appengine-Country. Por exemplo, se o país é "US" e a região é "ca", esse "ca" significa "Califórnia", e não Canadá. É possível encontrar a lista completa de valores regionais válidos no padrão ISO-3166-2.

X-Appengine-City

Nome da cidade de origem da solicitação. Por exemplo, uma solicitação da cidade de Mountain View pode ter o valor de cabeçalho mountain view. Não há uma lista canônica de valores válidos para esse cabeçalho.

X-Appengine-CityLatLong

Latitude e longitude da cidade de origem da solicitação. Essa string pode ser "37.386051, -122.083851" para uma solicitação de Mountain View.

X-Cloud-Trace-Context

Um identificador exclusivo da solicitação usada para o Cloud Trace e o Cloud Logging. Não há a opção de desativar esse cabeçalho ou escolher a taxa de amostragem para rastreamento, porque todos os aplicativos do ambiente padrão do App Engine são rastreados automaticamente.

X-Forwarded-For: [CLIENT_IP(s)], [global forwarding rule IP]

Uma lista delimitada por vírgulas de endereços IP por meio dos quais a solicitação do cliente foi roteada. O primeiro IP da lista geralmente é o IP do cliente que criou a solicitação. Os IPs subsequentes fornecem informações sobre servidores proxy que também processaram a solicitação antes de ela chegar ao servidor do app. Exemplo:

X-Forwarded-For: clientIp, proxy1Ip, proxy2Ip

X-Forwarded-Proto [http | https]

Mostra http ou https com base no protocolo que o cliente usou para se conectar ao app.

O balanceador de carga do Google Cloud encerra todas as conexões de https e, em seguida, encaminha o tráfego para as instâncias do App Engine em http. Por exemplo, se um usuário solicitar acesso ao site por meio de https://PROJECT_ID.REGION_ID.r.appspot.com, o valor do cabeçalho X- Forwarded-Proto será https.

Além disso, o App Engine pode definir os seguintes cabeçalhos para uso interno:

• X-Appengine-Https
• X-Appengine-User-IP
• X-Appengine-Api-Ticket
• X-Appengine-Request-Log-Id
• X-Appengine-Default-Version-Hostname
• X-Appengine-Timeout-Ms

Os serviços do App Engine podem adicionar outros cabeçalhos de solicitação:

• Para gerenciadores login:admin ou login:required especificados em app.yaml, o App Engine adiciona o seguinte conjunto de cabeçalhos:

  • X-Appengine-User-Email, com cabeçalho de exemplo: "[e-mail]"
  • X-Appengine-Auth-Domain, com cabeçalho de exemplo: "example.com"
  • X-Appengine-User-ID, com exemplo de cabeçalho: "100979712376541954724"
  • X-Appengine-User-Nickname, com cabeçalho de exemplo: "ange"
  • X-Appengine-User-Organization, com cabeçalho de exemplo: "example.com"
  • X-Appengine-User-Is-Admin, com exemplo de cabeçalho: "1"

• O serviço de fila de tarefas adiciona outros cabeçalhos às solicitações que dão detalhes sobre a tarefa da solicitação e a fila associada.

• As solicitações do Cron Service adicionam o seguinte cabeçalho:

  X-Appengine-Cron: true

  Veja mais detalhes em Como proteger URLs para Cron.

• As solicitações provenientes de outros aplicativos do App Engine incluirão um cabeçalho que identifica o aplicativo que faz a solicitação, se o aplicativo solicitante estiver usando o serviço de busca de URL:

  X-Appengine-Inbound-Appid

  Consulte a Documentação da App Identity para ver mais detalhes.

Respostas a solicitações

Esta documentação de cabeçalho HTTP aplica-se apenas a respostas a solicitações HTTP de entrada. A resposta pode ser modificada antes de ser retornada ao cliente. Para cabeçalhos HTTP relacionados a solicitações de saída originadas do seu código do App Engine, consulte a documentação de cabeçalho para URLFetch.

Cabeçalhos removidos

Os seguintes cabeçalhos são ignorados e removidos da resposta:

• Connection
• Content-Encoding*
• Content-Length
• Date
• Keep-Alive
• Proxy-Authenticate
• Server
• Trailer
• Transfer-Encoding
• Upgrade

* Pode ser adicionado novamente se a resposta for compactada pelo App Engine.

Os cabeçalhos com caracteres que não sejam ASCII no nome ou no valor também são removidos.

Cabeçalhos adicionados ou substituídos

Os seguintes cabeçalhos são adicionados ou substituídos na resposta:

Cache-Control, Expires e Vary

Esses cabeçalhos especificam a política de armazenamento em cache para proxies da Web intermediários (como o Google Frontend e os provedores de acesso à Internet) e navegadores. Se o app definir esses cabeçalhos de resposta, eles geralmente não serão modificados, a menos que o app também defina um cabeçalho Set-Cookie ou a resposta seja gerada para um usuário que fez login usando uma conta de administrador.

Se o app definir um cabeçalho de resposta Set-Cookie, o cabeçalho Cache-Control será definido como private (se já não for mais restritivo) e o cabeçalho Expires será definido como a data atual (se não estiver no passado). Dessa forma, os navegadores geralmente podem armazenar a resposta em cache, mas não em servidores proxy intermediários. Isso ocorre por questões de segurança porque, se a resposta for armazenada em cache publicamente, outro usuário poderá posteriormente solicitar o mesmo recurso e recuperar o cookie do primeiro usuário.

Observação: por padrão, o servidor de desenvolvimento desativa o armazenamento em cache (para script e conteúdo estático). Assim, se você não especificar cabeçalhos de cache, não terá conteúdo armazenado ao desenvolver seu aplicativo.

Se você usar um framework baseado em webob (como webapp ou webapp2), ele vai definir o cabeçalho Cache-Control como no-cache por padrão. Portanto, substitua-o se quiser armazenar em cache no gerenciadores de script.

Se o app não definir o cabeçalho de resposta Cache-Control, o servidor poderá configurá-lo como private e adicionar um cabeçalho Vary: Accept-Encoding.

Para mais informações sobre o armazenamento em cache, incluindo a lista de valores Vary aceitos pelo front-end do Google, consulte Armazenamento de resposta em cache.

Content-Encoding

Dependendo dos cabeçalhos de solicitação e do Content-Type de resposta, o servidor poderá compactar automaticamente o corpo de resposta, como descrito anteriormente. Nesse caso, ele adiciona um cabeçalho Content-Encoding: gzip para indicar que o corpo está compactado. Consulte a seção sobre compactação de resposta para ver mais detalhes.

Content-Length ou Transfer-Encoding

O servidor sempre ignora o cabeçalho Content-Length retornado pelo aplicativo. Ele configura Content-Length com o comprimento do corpo (após a compactação, caso seja aplicada) ou exclui Content-Length e usa a codificação de transferência fragmentada (acrescentando um cabeçalho Transfer-Encoding: chunked).

Content-Type

Se não for especificado pelo aplicativo, o servidor definirá um cabeçalho Content-Type: text/html padrão.

Observação: se você usar um framework baseado em webob (como webapp ou webapp2), o cabeçalho Content-Type vai ser definido como text/html; charset=utf-8 por padrão. Portanto, esse padrão (sem uma propriedade do conjunto de caracteres) não se aplica.

Date

Define data e hora atuais.

Server

Defina como Google Frontend. No servidor de desenvolvimento, ele é definido como Development/x, em que x é o número da versão.

Se você acessar páginas dinâmicas em seu site enquanto estiver conectado com uma conta de administrador, os cabeçalhos de resposta do App Engine terão estatísticas por solicitação:

X-Appengine-Resource-Usage

Os recursos utilizados pela solicitação, incluindo o tempo do lado do servidor em milissegundos.

As respostas com estatísticas de uso de recursos não poderão ser armazenadas em cache.

Se o cabeçalho X-Appengine-BlobKey estiver na resposta do aplicativo, ele e o cabeçalho X-Appengine-BlobRange opcional serão usados para substituir o corpo por todo o conteúdo do blob de um blob. Se Content-Type não for especificado pelo aplicativo, ele vai ser configurado para o tipo MIME do blob. Se um intervalo for solicitado, o status da resposta será alterado para 206 Partial Content e um cabeçalho Content-Range vai ser adicionado. Os cabeçalhos X-Appengine-BlobKey e X-Appengine-BlobRange vão ser removidos da resposta. Normalmente, você não precisa definir esses cabeçalhos, porque a classe blobstore_handlers.BlobstoreDownloadHandler os define. Consulte Como veicular um blob para ver detalhes.

Cabeçalhos de resposta configurados no aplicativo

Os cabeçalhos de resposta HTTP personalizados podem ser configurados por URL para caminhos dinâmicos e estáticos no arquivo de configuração do aplicativo. Consulte as seções http_headers na documentação de configuração para mais detalhes.