Class 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.
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