要求標頭與回應

區域 ID

REGION_ID 是 Google 根據您在建立應用程式時選取的地區所指派的縮寫代碼。即使部分區域 ID 看似常用的國家/地區和省份代碼，但該代碼並不對應至國家/地區或省份。如果是 2020 年 2 月後建立的應用程式，App Engine 網址會包含 REGION_ID.r。如果是這段時間前建立的現有應用程式，網址可選擇是否包含區域 ID。

進一步瞭解區域 ID。

本參考頁面詳細說明系統支援的 HTTP 標頭，以及 App Engine 中的要求與回應限制。如要瞭解 App Engine 如何接收要求及傳送回應，請參閱要求的處理方式一文。

要求標頭

傳入 HTTP 要求包含用戶端傳送的 HTTP 標頭。基於安全性考量，部分標頭在送達應用程式之前會由中繼 Proxy 進行處理、修改或移除。

從傳入要求中移除的標頭

如果用戶端傳送下列標頭，系統會從傳入要求中移除這些標頭：

  • 名稱符合 X-Google-* 模式的標頭。這個名稱模式已保留給 Google 使用。

  • 名稱與App Engine 專屬標頭相符的標頭。系統只會移除完全相符 (不區分大小寫) 的項目。舉例來說，系統會移除名為 X-Appengine-Country 或 X-AppEngine-Country 的標頭，但不會移除 X-Appengine-Cntry。

此外，由於下列標頭與用戶端和伺服器之間的 HTTP 資料傳輸有關，因此系統會從傳入要求中移除這些標頭：

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

舉例來說，伺服器可能會根據 Accept-Encoding 要求標頭的值，自動傳送經過 gzip 壓縮的回應。應用程式本身不需要知道用戶端可接受的內容編碼。

App Engine 專屬標頭

App Engine 會為應用程式在所有要求中新增下列標頭：

X-Appengine-Country
要求來源國家/地區，以 ISO 3166-1 alpha-2 國家/地區代碼表示。 App Engine 會根據用戶端的 IP 位址決定這個代碼。請注意，國家/地區資訊並非來自 WHOIS 資料庫；WHOIS 資料庫中含有國家/地區資訊的 IP 位址，可能不會在 X-Appengine-Country 標頭中顯示國家/地區資訊。您的應用程式應處理特殊國家/地區代碼 ZZ (不明國家/地區)。
X-Appengine-Region
發出要求的區域名稱。這個值必須搭配 X -Appengine-Country 中的國家/地區一起理解。舉例來說，如果國家/地區是「US」而地區是「ca」，則「ca」表示「加州」而非加拿大。如需完整的有效區域值清單，請參閱 ISO-3166-2 標準。
X-Appengine-City
要求來源城市的名稱。舉例來說，如果是來自 Mountain View (山景市) 的要求，標頭值可能為「mountain viewmountain view」。這個標頭沒有標準的有效值清單。如果無法解析城市，標頭值會設為 ?。
X-Appengine-CityLatLong
要求來源城市的經緯度。如果是來自 Mountain View (山景城) 的要求，這個字串可能會是「37.386051,-122.083851」。如果無法解析城市，標頭值會設為 0.000000,0.000000。
X-Cloud-Trace-Context
適用於 Cloud Trace 和 Cloud Logging 要求的專屬 ID。由於系統會自動追蹤所有 App Engine 標準環境應用程式，因此您無法停用這個標頭或選擇追蹤的取樣率。
X-Forwarded-For: CLIENT_IP,GLOBAL_FORWARDING_RULE_IP

轉送用戶端要求的 IP 位址清單 (以逗號分隔)。要求通過負載平衡器時，負載平衡器會依下列順序，將兩個 IP 位址附加至 X-Forwarded-For 標頭：

  1. 連線至負載平衡器的用戶端 IP 位址 (CLIENT_IP)。
  2. 負載平衡器轉送規則的 IP 位址 (GLOBAL_FORWARDING_RULE_IP)。

如果傳入的要求缺少這個標頭，負載平衡器會使用下列格式建立標頭並新增至要求：

    X-Forwarded-For: CLIENT_IP,GLOBAL_FORWARDING_RULE_IP

如果傳入的要求已包含這個標頭 (例如，用戶端透過其他 Proxy 轉送)，負載平衡器會使用下列格式將標頭附加至要求：

    X-Forwarded-For: PREVIOUS_ENTRIES,CLIENT_IP,GLOBAL_FORWARDING_RULE_IP

在這個範例中，變數代表下列項目：

  • CLIENT_IP：連線至負載平衡器的用戶端 IP 位址。
  • GLOBAL_FORWARDING_RULE_IP：負載平衡器轉送規則的 IP 位址。
  • PREVIOUS_ENTRIES：用戶端或先前 Proxy 傳送的所有前置 IP 位址。
X-Forwarded-Proto [http | https]

依據用戶端用來連線到您應用程式的通訊協定顯示 http 或 https。

Google Cloud 負載平衡器會終止所有 https 連線，然後透過 http 將流量轉送到 App Engine 執行個體。舉例來說，如果使用者要求透過 https://PROJECT_ID.REGION_ID.r.appspot.com 存取您的網站，則 X-Forwarded-Proto 標頭的值為 https。

此外，App Engine 可能會設定下列標頭，供 App Engine 內部使用：

  • 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

App Engine 服務可能會新增其他要求標頭：

  • 如果您使用舊版套裝服務：

    • 對於 login:admin 或 login:required 處理常式 (在 app.yaml 檔案中指定)，App Engine 會新增下列標頭集：

      • X-Appengine-User-Email，例如「ange@example.com」
      • X-Appengine-Auth-Domain，例如「example.com」標頭
      • X-Appengine-User-ID，例如標頭：「100979712376541954724」
      • X-Appengine-User-Nickname，例如標頭為「ange」
      • X-Appengine-User-Organization，例如「example.com」標頭
      • X-Appengine-User-Is-Admin，例如標題為「1」

    • 工作佇列服務會將額外標頭新增至要求，提供要求中工作的詳細資料，以及工作相關聯的佇列。

    • 如果要求應用程式使用網址擷取服務，來自其他 App Engine 應用程式的要求會包含額外標頭，提供要求來源應用程式的識別資訊：

      X-Appengine-Inbound-Appid

      詳情請參閱應用程式識別說明文件。

要求回應

本 HTTP 標頭說明文件僅適用於連入 HTTP 要求的回應。這個回應在傳回用戶端前可能已經過修改。

移除的標頭

系統會忽略並從回應中移除下列標頭：

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

* 如果回應經 App Engine 壓縮，則此標頭可能會重新加到回應中。

系統也會移除名稱或值含有非 ASCII 字元的標頭。

新增或取代的標頭

系統會在回應中新增或取代下列標頭：

Cache-Control、Expires和Vary

這些標頭會向中繼網路 Proxy (例如 Google Frontend 和網際網路服務供應商) 和瀏覽器指定快取政策。如果應用程式設定這些回應標頭，通常不會修改，除非應用程式也設定 Set-Cookie 標頭，或是為使用管理員帳戶登入的使用者產生回應。

如果應用程式設定 Set-Cookie 回應標頭，系統會將 Cache-Control 標頭設為 private (如果尚未設為更嚴格的值)，並將 Expires 標頭設為目前日期 (如果尚未設為過去的日期)。一般來說，這會允許瀏覽器快取回應，但不會允許中繼 Proxy 伺服器快取回應。這是基於安全考量，因為如果公開快取回應，其他使用者隨後可能會要求相同資源，並擷取第一位使用者的 Cookie。

如果應用程式未設定 Cache-Control 回應標頭，伺服器可能會將其設為 private，並新增 Vary: Accept-Encoding 標頭。

如要進一步瞭解快取，包括 Google 前端支援的 Vary 值清單，請參閱「回應快取」。

Content-Encoding

視要求標頭和回應 Content-Type 而定，伺服器可能會如上所述自動壓縮回應主體。在本例中，它會新增 Content-Encoding: gzip 標頭，指出主體已壓縮。詳情請參閱「回應壓縮」一節。

Content-Length或Transfer-Encoding

伺服器一律會忽略應用程式傳回的 Content-Length 標頭。並將 Content-Length 設為內文長度 (如已壓縮，則為壓縮後的長度) 或刪除 Content-Length，然後使用區塊傳輸編碼 (新增 Transfer-Encoding: chunked 標頭)。如果第二代執行階段的 Content-Length 設定有誤，App Engine 會傳回 500 回應。

Date

設為目前的日期和時間。

Server
設為 Google Frontend。開發伺服器會將這個標頭設為 Development/x，其中「x」x是版本號碼。

如果您使用管理員帳戶登入，並存取網站上的動態網頁，App Engine 會在回應標頭中加入每個要求的統計資料：

X-Appengine-Resource-Usage
要求使用的資源，包括伺服器端時間 (以毫秒為單位)。

系統無法快取包含資源使用統計資料的回應。

在應用程式設定檔中設定的回應標頭

您可以在應用程式的設定檔中，依動態和靜態路徑網址設定自訂 HTTP 回應標頭。詳情請參閱設定說明文件的 http_headers 部分。