透過網際網路擷取資源並與其他主機通訊。
這項服務可讓指令碼透過擷取網址的方式,與其他應用程式通訊或存取網路上的其他資源。指令碼可以使用網址擷取服務發出 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. 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': '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);
參數
名稱 | 類型 | 說明 |
---|---|---|
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': '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]);
參數
名稱 | 類型 | 說明 |
---|---|---|
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