URL Fetch Java API 總覽

「應用服務引擎」應用程式可以透過擷取 URL 存取網路上的資源，或與其他應用程式溝通。應用程式可以使用「URL 擷取」服務來發出 HTTP 和 HTTPS 要求和接收回應。為求效率和擴充能力，「URL 擷取」服務會使用 Google 的網路基礎架構。

• 使用 java.net 擷取 URL
• 發出要求
• 安全連線和 HTTPS
• 要求標頭
• 回應
• 連線至公司防火牆後方的主機
• URL 擷取和開發伺服器
• 配額和限制

使用 java.net 擷取 URL

您可以利用 java.net.URLConnection 和 Java 標準程式庫的相關類別，從 Java 應用程式建立 HTTP 和 HTTPS 連線。「應用服務引擎」使用 URL 擷取服務實作此介面，您的應用程式不會直接建立通訊端連線。

取得 URL 中之頁面內容的最簡單方法，就是建立 java.net.URL 物件，然後呼叫其 openStream() 方法。該方法會處理建立連線、發出 HTTP GET 要求及抓取回應資料的細節。

import java.net.MalformedURLException;
import java.net.URL;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.IOException;

// ...
        try {
            URL url = new URL("http://www.example.com/atom.xml");
            BufferedReader reader = new BufferedReader(new InputStreamReader(url.openStream()));
            String line;

            while ((line = reader.readLine()) != null) {
                // ...
            }
            reader.close();

        } catch (MalformedURLException e) {
            // ...
        } catch (IOException e) {
            // ...
        }

如需更為複雜的要求資訊，您可以呼叫 URL 物件的 openConnection() 方法以取得 URLConnection 物件 (可能為 HttpURLConnection 或 HttpsURLConnection，視 URL 而定)。 您可以在發出要求前，先備妥此物件的額外資訊。請參閱「使用 java.net」。

發出要求

應用服務可以透過 HTTP (一般) 或 HTTPS (安全) 擷取 URL。URL 會指定要使用的配置：http://... 或 https://...

URL 必須使用 HTTP 的標準連接埠 (80) 和 HTTPS 的標準連接埠 (443)。配置會隱含連接埠，但是如果配置使用的是標準連接埠 (https://...:443/)，則可能會直接在 URL 中提及。應用程式不可以連線至遠端主機的任意一個連接埠，也不可以使用非標準的配置連接埠。

擷取可以使用下列任何一種 HTTP 方法：GET (一般用於要求網頁和資料)、POST (一般用於提交網頁表單)、PUT、HEAD 以及 DELETE。擷取可以包括 HTTP 要求標頭以及裝載 (HTTP 要求內文)。

「URL 擷取」服務使用與 HTTP/1.1 相容的 proxy 來擷取結果。

為避免應用程式造成要求的無限遞迴，要求處理常式不得擷取自己的 URL。其他因素也可能造成無限遞迴，所以如果您的應用程式可以向使用者提供的 URL 擷取要求，請特別小心。

對「URL 擷取」服務所發出的呼叫是同步的，而且必須等到服務收到遠端主機的回應之後，呼叫才會傳回。您的應用程式要求計時器可能會在遠端主機回應之前即開始計時。要求發出之後是無法取消的。

安全連線和 HTTPS

應用程式可以使用 HTTPS 的方法擷取 URL，以連線至安全的伺服器。要求與回應資料會以加密的形式透過網路傳輸。

「URL 擷取」服務使用的 proxy 「無法」認證正在連線的主機。因為沒有憑證信任鏈，所以 proxy 會接受所有憑證，包括自我簽署的憑證。使用 HTTPS 時，proxy 伺服器無法偵測「應用服務引擎」和遠端主機之間的「中間人」攻擊。

要求標頭

應用程式可以為連出要求設定 HTTP 標頭。

傳送 HTTP POST 要求時，若 Content-Type 標頭未明確設定，則標頭會設定為 x-www-form-urlencoded。這是網頁表單使用者的內容類型。

基於安全理由，應用程式無法修改下列標頭：

• Content-Length
• Host
• Referer
• Vary
• Via
• X-Forwarded-For

「應用服務引擎」會視情況將這些標頭設為正確的值。例如，「應用服務引擎」會計算要求資料的 Content-Length 標頭，並將結果加到要求中，再傳送出去。

回應

「URL 擷取」服務會傳回所有回應資料，包括回應代碼、標頭以及內文。

按照預設，如果「URL 擷取」服務收到一個含有重新導向代碼的回應，將追蹤這個重新導向。服務最多可以追蹤 5 個重新導向回應，並傳回最終的資源。您可以透過 API 指示「URL 擷取」服務不要追蹤重新導向，只要將重新導向回應傳回至應用程式即可。

按照預設，如果連入回應超過回應大小上限，回應將遭到截斷。當回應超過大小上限時，您可以透過 API 使服務引發例外狀況。(如需查看回應大小上限值，請參閱下方)。

連線至公司防火牆後方的主機

您的應用程式可以透過 Google Secure Data Connector (SDC)，連線至公司防火牆後方的系統。在您的網路上安裝「SDC 代理程式」之後，「Google 應用服務」網域上執行的「應用服務引擎」應用程式即可以透過「代理程式」進行驗證，並存取內部網路的 URL。「SDC 代理程式」可以確保您的內部網路只有您的應用程式能夠連線，且使用者必須登入您的網域的「應用服務」帳戶。

您的應用程式可以使用「URL 擷取」服務來存取內部網路。應用程式的要求包括一個特殊標頭，用於宣告這個要求是針對您的「SDC 代理程式」而發出。標頭的名稱為 use_intranet，標頭的值為 yes。「代理程式」會自動處理使用者驗證、驗證以及安全連線，因此您不需要做出任何其他變更。

以下範例說明如何利用 java.net.HttpURLConnection 介面，使用 URL 擷取並搭配 use_intranet 標頭。

import java.net.HttpURLConnection;
import java.net.URL;

// ...
        URL url = new URL("http://www.corp.example.com/sales.csv");
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestProperty("use_intranet", "true");

如需詳細資訊，請參閱 Google Secure Data Connector 網站。

URL 擷取和開發伺服器

當您的應用程式在電腦的開發伺服器中執行時，本機會處理對「URL 擷取」所發出的呼叫。開發伺服器會直接從您的電腦連線至遠端主機來擷取 URL，而連線設定則是您的電腦存取網際網路時所使用的網路設定。

測試擷取 URL 的應用程式的功能時，請確定您的電腦可以存取遠端主機。

如果您的應用程式是透過 Google Secure Data Connector 存取內部網路的 URL，請務必在連線防火牆後方的內部網路之後，測試您的應用程式。不同於「應用服務引擎」，開發伺服器不會使用「SDC 代理程式」解析內部網路 URL。只有「Google 應用服務」和「應用服務引擎」可以透過您的「SDC 代理程式」進行驗證。

配額和限制

每個「URL 擷取」要求會算入 URL Fetch API Calls (URL 擷取 API 呼叫) 的配額中。

透過「URL 擷取」服務所傳送的 HTTP 或 HTTPS 要求資料會算入下列配額中：

• 連出頻寬 (可調整)
• 傳送的 URL 擷取資料

除了這些配額之外，HTTPS 要求所傳送的資料也會算入下列配額中：

• 安全連出頻寬 (可調整)

透過「URL 擷取」服務所接收的 HTTP 或 HTTPS 要求回應資料會算入下列配額中：

• 連入頻寬 (可調整)
• 接收的 URL 擷取資料

除了這些配額之外，HTTPS 要求回應所接收的資料也會算入下列配額中：

• 安全連入頻寬 (可調整)

如需瞭解配額的詳細資訊，請參閱「配額」，或參閱「管理控制台」的「配額詳細資訊」一節。

除了配額之外，使用「URL 擷取」服務時也需遵循下列限制：