Class UrlFetchApp

網址擷取應用程式

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

這項服務可讓指令碼透過擷取網址,與其他應用程式通訊或存取網路上的其他資源。指令碼可使用網址擷取服務,發出 HTTP 和 HTTPS 要求,然後接收回應。網址擷取服務會使用 Google 的網路基礎架構,以提高效率和擴充服務。

使用這項服務提出的要求會來自特定的 IP 範圍集區。如果您需要將這些要求加入許可清單或核准,可以查看完整的 IP 位址清單

這項服務需要 https://www.googleapis.com/auth/script.external_request 範圍。在大多數情況下,Apps Script 會自動偵測並納入指令碼所需的範圍,但如果您明確設定範圍,就必須手動新增這個範圍才能使用 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.
const response = UrlFetchApp.fetch('http://www.google.com/');
Logger.log(response.getContentText());

參數

名稱類型說明
urlString要擷取的網址。網址長度上限為 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: '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')
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);

參數

名稱類型說明
urlString要擷取的網址。網址長度上限為 2,082 個半形字元。
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.
const resumeBlob = Utilities.newBlob('Hire me!', 'text/plain', 'resume.txt');
const 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')
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]);

參數

名稱類型說明
requestsObject[]網址或 JavaScript 物件的陣列,用於指定要求,如以下所定義。

進階參數

名稱類型說明
urlString要擷取的網址。網址長度上限為 2,082 個半形字元。
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.
const response = UrlFetchApp.getRequest('http://www.google.com/');
for (const i in response) {
  Logger.log(`${i}: ${response[i]}`);
}

參數

名稱類型說明
urlString要查詢的網址。網址長度上限為 2,082 個半形字元。

回攻員

Object:欄位名稱與值的對應。地圖至少包含下列索引鍵:urlmethodcontentTypepayloadheaders

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權:

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

getRequest(url, params)

傳回在作業叫用時所提出的要求。

這個方法不會實際發出要求。

參數

名稱類型說明
urlString要查詢的網址。網址長度上限為 2,082 個半形字元。
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