Class UrlFetchApp

UrlFetchApp

透過網際網路擷取資源並與其他主機通訊。

這項服務可讓指令碼透過擷取網址的方式，與其他應用程式通訊或存取網路上的其他資源。指令碼可以使用網址擷取服務發出 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.
var 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.
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': '[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')
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);

參數

名稱	類型	說明
url	String	要擷取的網址。網址最多可包含 2,082 個半形字元。
params	Object	用於指定進階參數的選用 JavaScript 物件，定義如下。

進階參數

名稱	類型	說明
contentType	String	內容類型 (預設為「application/x-www-form-url 縮短」)。另一個內容類型範例為「application/xml; charset=utf-8」。
headers	Object	要求的 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.
var resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
var 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')
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]);

參數

名稱	類型	說明
requests	Object[]	網址或 JavaScript 物件陣列，定義如下。

進階參數

名稱	類型	說明
url	String	要擷取的網址。網址最多可包含 2,082 個半形字元。
contentType	String	內容類型 (預設為「application/x-www-form-url 縮短」)。另一個內容類型範例為「application/xml; charset=utf-8」。
headers	Object	要求的 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.
var response = UrlFetchApp.getRequest("http://www.google.com/");
for(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-url 縮短」)。另一個內容類型範例為「application/xml; charset=utf-8」。
headers	Object	要求的 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