Class UrlFetchApp

网址提取应用

提取资源并通过互联网与其他主机通信。

借助此服务，脚本可以通过提取网址来与其他应用通信或访问 Web 上的其他资源。脚本可以使用网址提取服务发出 HTTP 和 HTTPS 请求并接收响应。网址提取服务使用 Google 的网络基础架构，以提高效率并实现扩缩。

使用此服务发出的请求来自一组 IP 地址范围的池。如果您需要将这些请求列入许可名单或批准，可以查询 IP 地址的完整列表。

此服务需要 https://www.googleapis.com/auth/script.external_request 范围。在大多数情况下，Apps Script 会自动检测并包含脚本所需的范围，但如果您明确设置了范围，则必须手动添加此范围才能使用 UrlFetchApp。

另请参阅

• HTTPResponse
• 设置显式范围

方法

方法	返回类型	简介
fetch(url)	HTTPResponse	发出请求以提取网址。
fetch(url, params)	HTTPResponse	使用可选的高级参数发出请求以提取网址。
fetchAll(requests)	HTTPResponse[]	使用可选的高级参数发出多个请求以提取多个网址。
getRequest(url)	Object	返回在调用操作时发出的请求。
getRequest(url, params)	Object	返回在调用操作时发出的请求。

详细文档

fetch(url)

发出请求以提取网址。

这适用于 HTTP 和 HTTPS。

// The code below logs the HTML code of the Google home page.
const response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());

参数

名称	类型	说明
url	String	要提取的网址。网址最多可包含 2,082 个字符。

返回

HTTPResponse - HTTP 响应数据。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.external_request

---

fetch(url, params)

使用可选的高级参数发出请求以提取网址。

这适用于 HTTP 和 HTTPS。

// Make a GET request and log the returned content.
const response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());

// Make a POST request with form data.
const resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
const formData = {
  name: 'Bob Smith',
  email: '[e-mail]',
  resume: resumeBlob,
};
// Because payload is a JavaScript object, it is interpreted as
// as form data. (No need to specify contentType; it automatically
// defaults to either 'application/x-www-form-urlencoded'
// or 'multipart/form-data')
const options = {
  method: 'post',
  payload: formData,
};
UrlFetchApp.fetch('https://httpbin.org/post', options);

// Make a POST request with a JSON payload.
const data = {
  name: 'Bob Smith',
  age: 35,
  pets: ['fido', 'fluffy'],
};
const options = {
  method: 'post',
  contentType: 'application/json',
  // Convert the JavaScript object to a JSON string.
  payload: JSON.stringify(data),
};
UrlFetchApp.fetch('https://httpbin.org/post', options);

参数

名称	类型	说明
url	String	要提取的网址。网址最多可包含 2,082 个字符。
params	Object	可选的 JavaScript 对象，用于指定下文所定义的高级参数。

高级参数

名称	类型	说明
contentType	String	内容类型（默认为“application/x-www-form-urlencoded”）。内容类型的另一个示例是“application/xml; charset=utf-8”。
headers	Object	请求的 HTTP 标头的 JavaScript 键值对映射
method	String	请求的 HTTP 方法：get、delete、patch、post 或 put。默认值为 get。
payload	String	请求的有效内容（即 POST 正文）。某些 HTTP 方法（例如 GET）不接受载荷。它可以是字符串、字节数组、blob 或 JavaScript 对象。JavaScript 对象会被解读为表单字段名称与值的映射，其中值可以是字符串或 Blob。
useIntranet	Boolean	已弃用。这会指示提取功能通过（已废弃的）SDC 解析与您的网域关联的内部网中的指定网址
validateHttpsCertificates	Boolean	如果为 false，则提取操作会忽略 HTTPS 请求的所有无效证书。默认值为 true。
followRedirects	Boolean	如果 false，提取操作不会自动遵循 HTTP 重定向；它会返回原始 HTTP 响应。默认值为 true。
muteHttpExceptions	Boolean	如果为 true，则在响应代码指示失败时，提取操作不会抛出异常，而是返回 HTTPResponse。默认值为 false。
escaping	Boolean	如果网址中的 false 保留字符未转义。默认值为 true。

返回

HTTPResponse - HTTP 响应数据。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.external_request

---

fetchAll(requests)

使用可选的高级参数发出多个请求以提取多个网址。

这适用于 HTTP 和 HTTPS。

// Make both a POST request with form data, and a GET request.
const resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
const formData = {
  name: 'Bob Smith',
  email: '[e-mail]',
  resume: resumeBlob,
};
// Because payload is a JavaScript object, it is interpreted as
// as form data. (No need to specify contentType; it defaults to either
// 'application/x-www-form-urlencoded' or 'multipart/form-data')
const request1 = {
  url: 'https://httpbin.org/post',
  method: 'post',
  payload: formData,
};
// A request may also just be a URL.
const request2 = 'https://httpbin.org/get?key=value';
UrlFetchApp.fetchAll([request1, request2]);

参数

名称	类型	说明
requests	Object[]	网址或 JavaScript 对象的数组，用于指定如下所述的请求。

高级参数

名称	类型	说明
url	String	要提取的网址。网址最多可包含 2,082 个字符。
contentType	String	内容类型（默认为“application/x-www-form-urlencoded”）。内容类型的另一个示例是“application/xml; charset=utf-8”。
headers	Object	请求的 HTTP 标头的 JavaScript 键值对映射
method	String	请求的 HTTP 方法：get、delete、patch、post 或 put。默认值为 get。
payload	String	请求的有效内容（即 POST 正文）。某些 HTTP 方法（例如 GET）不接受载荷。它可以是字符串、字节数组、blob 或 JavaScript 对象。JavaScript 对象会被解读为表单字段名称与值的映射，其中值可以是字符串或 Blob。
useIntranet	Boolean	已弃用。这会指示提取功能通过（已废弃的）SDC 解析与您的网域相关联的 intranet 中的指定网址
validateHttpsCertificates	Boolean	如果为 false，则提取操作会忽略 HTTPS 请求的所有无效证书。默认值为 true。
followRedirects	Boolean	如果为 false，则提取操作不会自动遵循 HTTP 重定向；它会返回原始 HTTP 响应。默认值为 true。
muteHttpExceptions	Boolean	如果为 true，则在响应代码指示失败时，提取操作不会抛出异常，而是返回 HTTPResponse。默认值为 false。
escaping	Boolean	如果为 false，则不会对网址中的预留字符进行转义。默认值为 true。

返回

HTTPResponse[] - 每个输入请求的 HTTP 响应数据数组。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.external_request

---

getRequest(url)

返回在调用操作时发出的请求。

此方法实际上不会发出请求。

// The code below logs the value for every key of the returned map.
const response = UrlFetchApp.getRequest('http://www.google.com/');
for (const i in response) {
  Logger.log(`${i}: ${response[i]}`);
}

参数

名称	类型	说明
url	String	要查找的网址。网址最多可包含 2,082 个字符。

返回

Object - 字段名称与值的映射。该映射至少包含以下键：url、method、contentType、payload 和 headers。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.external_request

---

getRequest(url, params)

返回在调用操作时发出的请求。

此方法实际上不会发出请求。

参数

名称	类型	说明
url	String	要查找的网址。网址最多可包含 2,082 个字符。
params	Object	一个可选的 JavaScript 对象，用于指定下文所定义的高级参数。

高级参数

名称	类型	说明
contentType	String	内容类型（默认为“application/x-www-form-urlencoded”）。内容类型的另一个示例是“application/xml; charset=utf-8”。
headers	Object	请求的 HTTP 标头的 JavaScript 键值对映射
method	String	请求的 HTTP 方法：get、delete、patch、post 或 put。默认值为 get。
payload	String	请求的有效内容（即 POST 正文）。某些 HTTP 方法（例如 GET）不接受载荷。它可以是字符串、字节数组、blob 或 JavaScript 对象。JavaScript 对象会被解读为表单字段名称与值的映射，其中值可以是字符串或 Blob。
useIntranet	Boolean	已弃用。这会指示提取功能通过（已废弃的）SDC 解析与您的网域关联的内部网中的指定网址
validateHttpsCertificates	Boolean	如果为 false，则提取操作会忽略 HTTPS 请求的所有无效证书。默认值为 true。
followRedirects	Boolean	如果为 false，提取操作不会自动遵循 HTTP 重定向；它会返回原始 HTTP 响应。默认值为 true。
muteHttpExceptions	Boolean	如果为 true，则在响应代码指示失败时，提取操作不会抛出异常，而是返回 HTTPResponse。默认值为 false。
escaping	Boolean	如果网址中的 false 保留字符未转义。默认值为 true。

返回

Object - 字段名称与值的映射。该映射至少包含以下键：url、method、contentType、payload 和 headers。

授权

使用此方法的脚本需要获得以下一个或多个范围的授权：

• https://www.googleapis.com/auth/script.external_request