Class UrlFetchApp

UrlFetchApp

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

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

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

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

另请参阅

方法

方法返回类型简介
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.
var response = UrlFetchApp.fetch("http://www.google.com/");
Logger.log(response.getContentText());

参数

名称类型说明
urlString要获取的网址。网址最多可包含 2082 个字符。

返程

HTTPResponse - HTTP 响应数据。

授权

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

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

fetch(url, params)

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

该功能适用于 HTTP 和 HTTPS。

// Make a GET request and log the returned content.
var response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());
// Make a POST request with form data.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var formData = {
  'name': 'Bob Smith',
  'email': 'bob@example.com',
  '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')
var options = {
  'method' : 'post',
  'payload' : formData
};
UrlFetchApp.fetch('https://httpbin.org/post', options);
// Make a POST request with a JSON payload.
var data = {
  'name': 'Bob Smith',
  'age': 35,
  'pets': ['fido', 'fluffy']
};
var 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);

参数

名称类型说明
urlString要获取的网址。网址最多可包含 2082 个字符。
paramsObject用于指定高级参数(可选)的可选 JavaScript 对象。

高级参数

名称类型说明
contentTypeString内容类型(默认为“application/x-www-form-urlencoded”)。内容类型的另一个示例是“application/xml; charset=utf-8”。
headersObject请求的 HTTP 标头的 JavaScript 键值对映射
methodString请求的 HTTP 方法:getdeletepatchpostput。默认值为 get
payloadString请求的载荷(即 POST 正文)。某些 HTTP 方法(例如 GET)不接受载荷。它可以是字符串、字节数组、blob 或 JavaScript 对象。JavaScript 对象会被解释为表单字段名称与值的映射,其中的值可以是字符串或 Blob。
useIntranetBoolean已弃用。此命令会指示抓取操作通过(已弃用的)SDC 解析与您的网域关联的内网中的指定网址
validateHttpsCertificatesBoolean如果为 false,则提取会忽略 HTTPS 请求的任何无效证书。默认值为 true
followRedirectsBoolean如果为 false,则提取不会自动跟踪 HTTP 重定向;它将返回原始 HTTP 响应。默认值为 true
muteHttpExceptionsBoolean如果为 true,则在响应代码指示失败时,抓取不会抛出异常,而是返回 HTTPResponse。默认值为 false
escapingBoolean如果网址中的 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.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var formData = {
  'name': 'Bob Smith',
  'email': 'bob@example.com',
  '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')
var request1 = {
  'url': 'https://httpbin.org/post',
  'method' : 'post',
  'payload' : formData
};
// A request may also just be a URL.
var request2 = 'https://httpbin.org/get?key=value';
UrlFetchApp.fetchAll([request1, request2]);

参数

名称类型说明
requestsObject[]一个网址数组或一组 JavaScript 对象,用于指定请求,定义见下文。

高级参数

名称类型说明
urlString要提取的网址。网址最多可包含 2082 个字符。
contentTypeString内容类型(默认为“application/x-www-form-urlencoded”)。内容类型的另一个示例是“application/xml; charset=utf-8”。
headersObject请求的 HTTP 标头的 JavaScript 键值对映射
methodString请求的 HTTP 方法:getdeletepatchpostput。默认值为 get
payloadString请求的载荷(即 POST 正文)。某些 HTTP 方法(例如 GET)不接受载荷。它可以是字符串、字节数组、blob 或 JavaScript 对象。JavaScript 对象会被解释为表单字段名称与值的映射,其中的值可以是字符串或 Blob。
useIntranetBoolean已弃用。此命令会指示抓取操作通过(已弃用的)SDC 解析与您的网域关联的内网中的指定网址
validateHttpsCertificatesBoolean如果为 false,则提取会忽略 HTTPS 请求的任何无效证书。默认值为 true
followRedirectsBoolean如果为 false,则提取不会自动跟踪 HTTP 重定向;它将返回原始 HTTP 响应。默认值为 true
muteHttpExceptionsBoolean如果为 true,则在响应代码指示失败时,抓取不会抛出异常,而是返回 HTTPResponse。默认值为 false
escapingBoolean如果值为 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.
var response = UrlFetchApp.getRequest("http://www.google.com/");
for(i in response) {
  Logger.log(i + ": " + response[i]);
}

参数

名称类型说明
urlString要查询的网址。网址最多可包含 2082 个字符。

返程

Object - 字段名称到值的映射。映射至少具有以下键:urlmethodcontentTypepayloadheaders

授权

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

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

getRequest(url, params)

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

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

参数

名称类型说明
urlString要查询的网址。网址最多可包含 2082 个字符。
paramsObject可选的 JavaScript 对象,定义如下高级参数。

高级参数

名称类型说明
contentTypeString内容类型(默认为“application/x-www-form-urlencoded”)。内容类型的另一个示例是“application/xml; charset=utf-8”。
headersObject请求的 HTTP 标头的 JavaScript 键值对映射
methodString请求的 HTTP 方法:getdeletepatchpostput。默认值为 get
payloadString请求的载荷(即 POST 正文)。某些 HTTP 方法(例如 GET)不接受载荷。它可以是字符串、字节数组、blob 或 JavaScript 对象。JavaScript 对象会被解释为表单字段名称与值的映射,其中的值可以是字符串或 Blob。
useIntranetBoolean已弃用。此命令会指示抓取操作通过(已弃用的)SDC 解析与您的网域关联的内网中的指定网址
validateHttpsCertificatesBoolean如果为 false,则提取会忽略 HTTPS 请求的任何无效证书。默认值为 true
followRedirectsBoolean如果为 false,则提取不会自动跟踪 HTTP 重定向;它将返回原始 HTTP 响应。默认值为 true
muteHttpExceptionsBoolean如果为 true,则在响应代码指示失败时,抓取不会抛出异常,而是返回 HTTPResponse。默认值为 false
escapingBoolean如果网址中有 false 个预留字符未转义,默认值为 true

返程

Object - 字段名称到值的映射。映射至少具有以下键:urlmethodcontentTypepayloadheaders

授权

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

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