Class UrlFetchApp

UrlFetchApp

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

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

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

此服务需要 https://www.googleapis.com/auth/script.external_request 范围。在大多数情况下，Apps 脚本会自动检测并包含脚本所需的范围， 但如果您要明确设置范围 ，则必须手动添加此范围才能使用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 解析与您的网域关联的内网中的指定 网址
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