网址提取 Java API 概述

App Engine 应用程序可通过提取网址，与其他应用程序进行通信或访问网络上的资源。应用程序可以使用网址提取服务发出 HTTP 和 HTTPS 请求以及接收响应。网址提取服务使用 Google 的网络基础架构以提高效率和进行扩展。

• 用 java.net 提取网址
• 发出请求
• 安全连接和 HTTPS
• 请求标头
• 响应
• 连接公司防火墙后面的主机
• 网址提取和开发服务器
• 配额和限制

用 java.net 提取网址

您可以使用 Java 标准库中的 java.net.URLConnection 和相关类，通过 Java 应用程序创建 HTTP 和 HTTPS 连接。App Engine 使用网址提取服务实现此接口；您的应用程序不会直接创建套接字连接。

获取某网址的页面内容的一种简单方法是创建 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) {            // ...        }

对于更复杂的请求，您可以调用网址对象的 openConnection() 方法以获取 URLConnection 对象（HttpURLConnection 或 HttpsURLConnection，视网址而定）。在发出请求之前，您可以用更多信息准备此对象。请参阅使用 java.net。

发出请求

应用程序可以使用 HTTP（普通）或 HTTPS（安全）提取网址。网址指定了要使用的方案：http://... 或 https://...

要提取的网址可以使用以下范围内的任意端口号：80-90、440-450、1024-65535。如果网址中未提到端口，则使用方案暗指的端口：http://... 使用端口 80，https://... 使用端口 443。

提取可以使用任何以下 HTTP 方法：GET（常用于请求网页和数据）、POST（常用于提交网络表单）、PUT、HEAD 和 DELETE。提取可以包含 HTTP 请求标头和负载（HTTP 请求正文）。

网址提取服务使用符合 HTTP/1.1 的代理提取结果。

为了防止应用程序造成请求无限循环，不允许请求处理程序提取自己的网址。但其他做法仍可能会造成无限循环，因此，如果应用程序可以提取对用户提供的网址的请求，则要非常小心。

您可以设置请求的截止时间，即，该服务等待响应的最长时间。默认情况下，提取截止时间为 5 秒。最大截止时间为 10 秒。在使用 URLConnection 接口时，该服务将连接超时 (setConnectTimeout()) 和读取超时 (setReadTimeout()) 之和作为截止时间。

网址提取服务支持同步和异步请求。对于同步请求，用于提取网址的 API 调用将一直等到远程主机返回结果，然后将控制权返还给应用程序。应用程序可以指定在进行调用时等待的最长时间。如果超过了最长等待时间，调用将引发异常。

对于异步请求，网址提取服务将启动该请求，然后立即返回一个对象。应用程序可以在提取网址的同时执行其他任务。当应用程序需要结果时，它将针对该对象调用一个方法，该方法等待请求完成（如有必要），然后返回结果。应用程序最多可以具有 10 个并发异步网址提取调用。在请求处理程序退出时，如果任何网址提取请求处于未完成状态，应用程序服务器将等待所有其余请求返回或到达截止时间，然后再向用户返回响应。

在 Java 中，只有在直接使用低级 API 时，才能使用异步接口。fetchAsync() 方法返回 java.util.concurrent.Future<HTTPResponse>。

安全连接和 HTTPS

应用程序可以使用 HTTPS 方法提取网址以连接到安全服务器。请求和响应数据以加密形式通过网络进行传输。

网址提取服务使用的代理无法验证要连接的主机。由于没有证书信任链，代理将接受所有证书，包括自签名证书。在使用 HTTPS 时，代理服务器无法检测 App Engine 和远程主机之间的“中间人”攻击。

请求标头

应用程序可以设置传出请求的 HTTP 标头。

在发送 HTTP POST 请求时，如果未明确设置 Content-Type 标头，则会将标头设置为 x-www-form-urlencoded。这是网络表单使用的内容类型。

出于安全考虑，应用程序无法修改以下标头：

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

根据需要，App Engine 将这些标头设置为准确的值。例如，App Engine 通过请求数据计算 Content-Length 标头，并在发送之前将其添加到请求中。

响应

网址提取服务返回所有响应数据，包括响应代码、标头和正文。

默认情况下，如果网址提取服务收到具有重定向代码的响应，该服务将进行重定向。该服务最多进行 5 次重定向，然后返回最终资源。您可以使用该 API 通知网址提取服务不要进行重定向，而是直接向应用程序返回重定向响应。

默认情况下，如果传入响应超过最大响应大小限制，网址提取服务将引发异常。（请参阅下文以了解该限制值。）您可以通知该 API 截断响应，而不是引发异常。

连接公司防火墙后面的主机

您的应用程序可以使用 Google 安全数据连接器 (SDC) 连接到公司防火墙后面的系统。在您的网络中设置 SDC 代理后，在 Google Apps 域上运行的 App Engine 应用程序可以在该代理中进行身份验证并访问您的 Intranet 上的网址。SDC 代理确保仅您的应用程序可以连接到 Intranet，并且仅为使用您的域中的 Apps 帐户登录的用户执行此操作。

您的应用程序可以使用网址提取服务访问 Intranet 网址。该应用程序在其请求中包含一个特殊标头，以声明请求针对的是 SDC 代理。标头的名称为 use_intranet，值为 yes。不需要进行其他更改；将自动处理用户验证、身份验证和安全连接。

以下示例说明如何通过使用 java.net.HttpURLConnection 接口对标头 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 安全数据连接器网站。

网址提取和开发服务器

当应用程序在您的计算机上的开发服务器中运行时，将在本地处理对网址提取服务的调用。开发服务器使用您的计算机用于访问互联网的任何网络配置，直接从您的计算机中连接到远程主机以提取网址。

在测试提取网址的应用程序功能时，请确保您的计算机可以访问远程主机。

如果应用程序使用 Google 安全数据连接器访问 Intranet 上的网址，请确保在连接到防火墙后面的 Intranet 时测试应用程序。与 App Engine 不同，开发服务器不使用 SDC 代理来解析 Intranet 网址。仅 Google Apps 和 App Engine 可以在 SDC 代理中进行身份验证。

配额和限制

每个网址提取请求将计入网址提取 API 调用配额。

使用网址提取服务在 HTTP 或 HTTPS 请求中发送的数据将计入以下配额：

• 传出带宽（可计费）
• 发送的网址提取数据

除了这些配额以外，在 HTTPS 请求中发送的数据还会计入以下配额：

• 安全传出带宽（可计费）

在使用网址提取服务的 HTTP 或 HTTPS 请求响应中接收的数据将计入以下配额：

• 传入带宽（可计费）
• 接收的网址提取数据

除了这些配额以外，在 HTTPS 请求响应中接收的数据还会计入以下配额：

• 安全传入带宽（可计费）

有关配额的详细信息，请参阅配额以及管理控制台的“配额详细信息”部分。

除了配额以外，在使用网址提取服务时，还应遵循以下限制：