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