第三方 API

Google Ads 指令碼的強大功能之一，就是能夠整合第三方 API 的資料和服務。

本指南將介紹下列概念，協助您編寫指令碼以連線至其他服務：

  • 發出 HTTP 要求：如何使用 UrlFetchApp 存取外部 API。
  • 驗證：我們會介紹一些常見的驗證情境。
  • 剖析回應：如何處理傳回的 JSON 和 XML 資料。

我們也提供多個熱門 API 的範例，說明這些概念。

使用 UrlFetchApp 擷取資料

UrlFetchApp 提供與第三方 API 互動所需的核心功能。

以下範例說明如何從 OpenWeatherMap 擷取天氣資料。我們選擇 OpenWeatherMap，是因為其授權方案和 API 相對簡單。

提出要求

OpenWeatherMap 說明文件指定了要求目前天氣的格式，如下所示：

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

這個網址提供第一個授權範例：必須使用參數 apikey，且每位使用者都有專屬的值。您可以透過註冊取得這個金鑰。

註冊完成後，您可以使用下列方式發出使用金鑰的要求：

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

執行這段程式碼後，Google Ads 指令碼中的記錄視窗會寫入長串 JSON 文字。

下一步是將這項資訊轉換為可在指令碼中使用的格式。

JSON 資料

許多 API 會以 JSON 格式提供回應。這代表 JavaScript 物件的簡單序列化，例如物件、陣列和基本類型可做為字串表示和傳輸。

如要將 JSON 字串 (例如 OpenWeatherMap 傳回的字串) 轉換回 JavaScript 物件，請使用內建的 JSON.parse 方法。接續上述範例：

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

JSON.parse 方法會將字串轉換為物件，該物件具有 name 屬性。

如要進一步瞭解如何使用不同格式的 API 回應，請參閱「剖析回應」一節。

處理錯誤

在指令碼中使用第三方 API 時，錯誤處理是重要的考量因素，因為第三方 API 經常變動，並產生意外的回應值，例如：

  • API 的網址或參數可能會在您不知情的情況下變更。
  • API 金鑰 (或其他使用者憑證) 可能會過期。
  • 回應格式可能會變更，恕不另行通知。

HTTP 狀態碼

由於可能會傳回非預期的回應，因此您應檢查 HTTP 狀態碼。根據預設，如果遇到 HTTP 錯誤代碼，UrlFetchApp 會擲回例外狀況。如要變更這項行為，您必須傳遞選用參數，如以下範例所示：

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

回應結構

第三方 API 變更時，開發人員通常不會立即察覺可能會影響指令碼的變更。舉例來說，如果 OpenWeatherMap 範例中傳回的 name 屬性變更為 locationName，使用這個屬性的指令碼就會失敗。

因此，測試傳回的結構是否符合預期可能會很有幫助，例如：

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

使用 UrlFetchApp 傳送 POST 資料

使用 OpenWeatherMap 的入門範例只會擷取資料。一般來說，不會在遠端伺服器變更狀態的 API 呼叫會使用 HTTP GET 方法。

GET 方法是 UrlFetchApp 的預設值。不過，某些 API 呼叫 (例如呼叫傳送簡訊的服務) 需要使用其他方法，例如 POST 或 PUT。

為了說明如何使用 POST 呼叫 UrlFetchApp，以下範例說明如何整合 Slack 這類協作式訊息應用程式，以便將 Slack 訊息傳送給 Slack 使用者和群組。

設定 Slack

本指南假設您已註冊 Slack 帳戶。

如同前述範例中的 OpenWeatherMap，您必須取得權杖才能傳送訊息。Slack 會提供專屬網址，讓你傳送訊息給團隊成員，這稱為「連入 Webhook」。

設定 Incoming Webhook，方法是按一下「Add Incoming WebHooks Integration」並按照操作說明進行操作。這個程序應會發出用於傳送訊息的網址。

提出 POST 要求

設定好 Incoming Webhook 後，只要在傳遞至 UrlFetchApp.fetch 的 options 參數中使用一些額外屬性，即可提出 POST 要求：

  • method：如前所述，預設值為 GET，但我們在此覆寫並將其設為 POST。

  • payload：這是要傳送至伺服器的資料，也是 POST 要求的一部分。在這個範例中，Slack 會預期物件序列化為 JSON 格式，如 Slack 說明文件所述。為此，我們使用 JSON.stringify 方法，並將 Content-Type 設為 application/json。

      // Change the URL for the one issued to you from 'Setting up Slack'.
  const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
  const slackMessage = {
    text: 'Hello, slack!'
  };

  const options = {
    method: 'POST',
    contentType: 'application/json',
    payload: JSON.stringify(slackMessage)
  };
  UrlFetchApp.fetch(SLACK_URL, options);

延長 Slack 範例

上方範例顯示啟用 Slack 訊息接收功能的最低要求。以下是擴充的範例，說明如何建立並傳送廣告活動成效報表給群組，以及一些格式和顯示選項。

收到的訊息

如要進一步瞭解 Slack 訊息，請參閱 Slack 說明文件中的「訊息格式」。

表單資料

上方的範例示範了如何使用 JSON 字串做為 POST 要求的 payload 屬性。

視 payload 的格式而定，UrlFetchApp 會採用不同的方法建構 POST 要求：

  • 如果 payload 是字串，字串引數會傳送為要求的內容。

  • 當 payload 是物件時，例如值對應：

    {to: 'mail@example.com', subject:'Test', body:'Hello, World!'}

    鍵/值組合會轉換為表單資料：

    subject=Test&to=mail@example.com&body=Hello,+World!

    要求的 Content-Type 標頭也設為 application/x-www-form-urlencoded。

有些 API 在提交 POST 要求時，需要使用表單資料，因此請記得自動將 JavaScript 物件轉換為表單資料。

HTTP 基本驗證

HTTP 基本驗證是最簡單的驗證形式之一，許多 API 都會使用這項功能。

驗證方式是將經過編碼的使用者名稱和密碼附加至每個要求中的 HTTP 標頭。

HTTP 基本驗證

建構要求

如要產生已驗證的要求，請按照下列步驟操作：

  1. 將使用者名稱和密碼連結在一起，並加上冒號 (例如 username:password)，即可形成密碼字串。
  2. 使用 Base64 編碼密碼金鑰，例如 username:password 會變成 dXNlcm5hbWU6cGFzc3dvcmQ=。
  3. 將 Authorization 標頭附加至要求，格式為 Authorization: Basic <encoded passphrase>

下列程式碼片段說明如何在 Google Ads 指令碼中執行此操作：

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

基本驗證範例

「程式碼範例」一節包含兩個說明如何使用 HTTP 基本驗證的範例：

Plivo

Plivo 是一項服務，可透過 API 傳送及接收簡訊。這個範例說明如何傳送訊息。

  1. 向 Plivo 註冊。
  2. 將範例指令碼貼到 Google Ads 中的新指令碼中。
  3. 將 PLIVO_ACCOUNT_AUTHID 和 PLIVO_ACCOUNT_AUTHTOKEN 值替換為管理資訊主頁中的值。
  4. 請按照指令碼中指定的方式插入電子郵件地址，以便接收錯誤通知。
  5. 如要使用 Plivo，您必須購買號碼，或在試用帳戶中新增號碼。新增沙箱號碼，以便與試用帳戶搭配使用。
  6. 請一併新增要顯示為寄件人的號碼，以及收件者的號碼。
  7. 將指令碼中的 PLIVO_SRC_PHONE_NUMBER 更新為剛註冊的沙箱號碼之一。這應該包含國際國家/地區代碼，例如英國號碼的 447777123456。

Twilio

Twilio 是另一項服務，可透過其 API 傳送及接收簡訊。這個範例說明如何傳送訊息。

  1. 向 Twillio 註冊。
  2. 將範例指令碼貼到 Google Ads 中的新指令碼中。
  3. 將 TWILIO_ACCOUNT_SID 和 TWILIO_ACCOUNT_AUTHTOKEN 值替換為帳戶主控台頁面上顯示的值。
  4. 將 TWILIO_SRC_PHONE_NUMBER 替換為資訊主頁中的號碼，這是 Twilio 授權用於傳送訊息的號碼。

OAuth 1.0

許多熱門服務都會使用 OAuth 進行驗證。OAuth 有許多變化版本。

在 HTTP 基本驗證中，使用者只有一個使用者名稱和密碼，但 OAuth 允許第三方應用程式使用該應用程式專屬的憑證，授予存取使用者帳戶和資料的權限。此外，存取權限的範圍也將視該應用程式而定。

如要瞭解 OAuth 1.0 的背景資訊，請參閱 OAuth 核心指南。特別是 6. 使用 OAuth 進行驗證。在完整的 三方 OAuth 1.0 中，程序如下：

  1. 應用程式 (「消費者」) 取得要求權杖。
  2. 使用者授權要求權杖。
  3. 應用程式會將要求權杖換成存取權杖。
  4. 對於所有後續資源要求，存取權杖會用於已簽署的要求。

第三方服務如要使用 OAuth 1.0 而無需使用者互動 (例如 Google Ads 指令碼所需的互動)，則無法執行步驟 1、2 和 3。因此，部分服務會透過設定控制台發出存取權權杖，讓應用程式直接進入步驟 4。這就是所謂的單邊 OAuth 1.0。

OAuth1

Google Ads 指令碼中的 OAuth 1.0

就 Google Ads 指令碼而言，每個指令碼通常會解讀為一個應用程式。通常必須透過服務的控制台/管理設定頁面，執行以下操作：

  • 設定應用程式設定，以代表指令碼。
  • 指定要授予指令碼的權限。
  • 取得用戶端金鑰、用戶端密鑰、存取權杖和存取密鑰，以便搭配單向 OAuth 使用。

OAuth 2.0

OAuth 2.0 可用於熱門 API，提供使用者資料存取權。特定第三方服務的帳戶擁有者會將權限授予特定應用程式，允許這些應用程式存取使用者資料。這樣做的優點如下：

  • 不必與應用程式共用帳戶憑證。
  • 可控管哪些應用程式可存取資料，以及存取的程度。(例如，授予的存取權可能為唯讀，或僅限於資料的子集)。

如要在 Google Ads 指令碼中使用支援 OAuth 2.0 的服務，請完成以下幾個步驟：

在指令碼外

授權 Google Ads 指令碼透過第三方 API 存取您的使用者資料。在大多數情況下，您需要在第三方服務的主控台中設定應用程式。這個應用程式代表您的 Google Ads 指令碼。

您可以指定應授予 Google Ads 指令碼應用程式哪些存取權，通常會指派用戶端 ID。這樣一來，您就能透過 OAuth 2 控管哪些應用程式可存取第三方服務中的資料，以及這些應用程式可查看或修改哪些資料。

在指令碼中

透過遠端伺服器授權。視伺服器允許的授權類型而定，您需要遵循不同的一組步驟 (稱為流程)，但最終都會發出存取權存證，並用於該工作階段的所有後續要求。

發出 API 要求。在每個要求中傳遞存取權杖。

授權流程

每種授權類型和對應的流程都適用於不同的使用情境。舉例來說，如果使用者正在參與互動工作階段，就會採用不同的流程，而非在沒有使用者參與的情況下，應用程式需要在背景中執行的情況。

API 供應商會決定接受哪些授權類型，並引導使用者如何繼續整合 API。

導入作業

所有不同的 OAuth 流程都是為了取得存取權杖，以便在後續工作階段中驗證要求。

程式庫範例說明如何為每種不同的流程類型進行驗證。每個方法都會傳回物件，用於取得及儲存存取權杖，並協助處理已驗證的要求。

一般使用模式如下：

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

用戶端憑證授權

用戶端憑證授權是 OAuth2 流程的簡易形式之一，其中應用程式會交換應用程式專屬的 ID 和密碼，以換取有效期限有限的存取權杖。

用戶端憑證

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

更新權杖授權

重新整理權杖核發權限與用戶端憑證核發權限類似，因為向伺服器提出的簡單要求會傳回可在工作階段中使用的存取權杖。

重新整理權杖

取得更新權杖

與重新整理憑證核發作業的差異在於，用戶端憑證核發作業所需的詳細資料來自應用程式設定 (例如服務的控制台)，而重新整理憑證核發作業則是透過更複雜的流程 (例如授權碼核發作業) 進行，因此需要使用者互動：

授權碼

使用 OAuth Playground 取得更新權杖

OAuth2 Playground 提供 UI，可讓使用者逐步完成授權碼授權，取得更新憑證。

您可以使用右上方的設定按鈕，定義在 OAuth 流程中使用的所有參數，包括：

  • 授權端點：用於授權流程的起點。
  • 權杖端點：搭配更新權杖使用，以取得存取權杖。
  • 用戶端 ID 和密鑰：應用程式的憑證。

OAuth Playground

使用指令碼取得重新整理權杖

您可以在重新整理權杖產生範例中，找到以指令碼為基礎的替代方法，用於完成流程。

更新權杖用途

完成初始授權後，服務就能發出重新整理權杖，並以類似用戶端憑證流程的方式使用。請參考以下兩個範例：

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

Search Ads 360 範例

Search Ads 360 就是一個可搭配重新整理權杖使用的 API 範例。在這個範例中，指令碼會產生並傳回報表。如要進一步瞭解可執行的其他動作，請參閱 Search Ads 360 API 參考資料。

建立指令碼
  1. 在 API 控制台中建立新專案，並按照 DoubleClick 指南中的程序取得用戶端 ID、用戶端密鑰和重新整理權杖，確保您已啟用 DoubleClick Search API。
  2. 將範例指令碼貼到 Google Ads 中的新指令碼中。
  3. 在程式碼清單下方貼上 OAuth2 程式庫範例。
  4. 修改指令碼，讓其包含用戶端 ID、用戶端密鑰和更新權杖的正確值。

Apps Script Execution API 範例

這個範例說明如何使用 Apps Script Execution API，在 Apps Script 中執行函式。這樣一來，您就能從 Google Ads 指令碼呼叫 Apps Script。

建立 Apps Script 指令碼

建立新指令碼。以下範例會列出雲端硬碟中的 10 個檔案：

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}
設定要執行的 Apps Script
  1. 儲存指令碼。
  2. 依序點選「資源」>「Cloud Platform 專案」。
  3. 按一下專案名稱，前往 API 控制台。
  4. 前往「API 和服務」。
  5. 啟用適當的 API，在本例中為 Drive API 和 Apps 指令碼執行 API。
  6. 透過選單中的「憑證」項目建立 OAuth 憑證。
  7. 回到指令碼，從「發布」>「以 API 可執行檔部署」發布要執行的指令碼。
建立 Google Ads 指令碼
  1. 將範例指令碼貼到 Google Ads 中的新指令碼中。
  2. 此外，請在程式碼清單下方貼上 OAuth2 範例程式庫。
  3. 修改指令碼，讓其包含用戶端 ID、用戶端密鑰和更新權杖的正確值。

服務帳戶

服務帳戶概念是上述授權類型的替代方案。

服務帳戶與上述帳戶的不同之處在於，服務帳戶不會用於存取使用者資料：在驗證完成後，服務帳戶會代表應用程式提出要求，而非代表可能擁有專案的使用者。舉例來說，如果服務帳戶使用 Drive API 建立檔案，該檔案就會屬於服務帳戶，因此專案擁有者預設無法存取。

Google Natural Language API 範例

自然語言 API 可為文字提供情緒分析和實體分析。

本例說明如何計算廣告文字 (包括廣告標題或說明) 的情緒。這項指標可評估訊息的正面程度和重要性：我們販售蛋糕和我們販售倫敦最棒的蛋糕，哪個比較好？歡迎立即選購！

設定指令碼
  1. 在 API 控制台中建立新專案
  2. 啟用 Natural Language API
  3. 為專案啟用計費功能。
  4. 建立服務帳戶。下載憑證 JSON 檔案。
  5. 將範例指令碼貼到 Google Ads 中的新指令碼。
  6. 此外，請在程式碼清單下方貼上 OAuth2 範例程式庫。
  7. 替換必要的值：
    • serviceAccount：服務帳戶的電子郵件地址，例如 xxxxx@yyyy.iam.gserviceaccount.com。
    • key：建立服務帳戶時下載的 JSON 檔案中的金鑰。開始時間為 -----BEGIN PRIVATE KEY...，結束時間為 ...END PRIVATE KEY-----\n。

API 回應

API 可傳回多種格式的資料。其中最值得注意的是 XML 和 JSON。

JSON

JSON 通常比 XML 更容易用於回應格式。不過，仍可能發生一些問題。

回應驗證

從 API 呼叫取得成功回應後，通常的下一步是使用 JSON.parse 將 JSON 字串轉換為 JavaScript 物件。此時，處理剖析失敗的情況會比較合理：

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

此外，如果您無法控制 API，請注意回應的結構可能會變更，屬性也可能不再存在：

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

驗證

XML 仍是建構 API 的熱門格式。您可以使用 XmlService parse 方法剖析 API 呼叫的回應：

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

XmlService.parse 雖然會偵測 XML 中的錯誤並擲回例外狀況，但無法驗證 XML 是否符合結構定義。

根元素

假設 XML 文件已成功剖析，則會使用 getRootElement() 方法取得根元素：

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

命名空間

在以下範例中，我們使用 Sportradar API 取得所選足球賽事的結果。XML 回應的格式如下：

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

請注意，在根元素中如何指定命名空間。因此，您必須：

  • 從文件中擷取命名空間屬性。
  • 在遍歷及存取子元素時使用這個命名空間。

以下範例說明如何存取上述文件片段中的 <matches> 元素：

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

取得值

以下是足球賽程的範例：

<match status="..." category="..." ... >
  ...
</match>

您可以擷取屬性，例如：

const status = matchElement.getAttribute('status').getValue();

您可以使用 getText() 讀取元素內含的文字，但如果元素有多個文字子項，這些文字會串連在一起。如果可能會有多個文字子項，建議您使用 getChildren() 並對每個子項進行迴圈。

Sportradar 範例

這個完整的 Sportradar 範例說明如何擷取足球賽事的詳細資料，特別是英超聯賽的賽事。Soccer API 是 Sportradar 提供的眾多運動動態饋給之一。

設定 Sportradar 帳戶
  1. 前往 Sportradar 開發人員網站
  2. 註冊試用帳戶。
  3. 註冊完成後，請登入帳戶。
  4. 登入後，前往「我的帳戶」MyAccount。

Sportradar 會將不同運動分類至不同的 API。舉例來說，您可以購買足球 API 的存取權，但不購買網球 API 的存取權。您建立的每個應用程式都可以與不同的運動和鍵盤按鍵建立關聯。

  1. 在「Applications」下方，按一下「Create a new Application」。為應用程式提供名稱和說明，並忽略網站欄位。
  2. 只選取「Issue a new key for Soccer Trial Europe v2」。
  3. 按一下「註冊應用程式」。

成功後，這個頁面應會顯示新的 API 金鑰。

  1. 將範例指令碼貼到 Google Ads 中的新指令碼中。
  2. 將清單中的 API 金鑰替換為上述取得的金鑰，然後編輯電子郵件地址欄位。

疑難排解

使用第三方 API 時，可能會因多種原因發生錯誤，例如：

  • 用戶端向伺服器發出 API 不預期的格式要求。
  • 用戶端預期的回應格式與實際格式不同。
  • 用戶端使用無效的符記或鍵，或將值留作預留位置。
  • 客戶達到用量限制。
  • 用戶端提供無效的參數。

在所有這些情況 (以及其他情況) 中，要找出問題的原因，第一步就是檢查導致錯誤的回應詳細資料。

剖析回應

根據預設，Google Ads 指令碼引擎會擲回任何傳回錯誤 (狀態碼為 400 以上) 的回應。

如要避免發生這種行為，並允許檢查錯誤和錯誤訊息，請將選用參數的 muteHttpExceptions 屬性設為 UrlFetchApp.fetch。例如：

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

常見狀態碼

  • 200 OK 表示成功。如果回應中沒有預期的資料，請考慮以下因素：

    • 部分 API 允許您指定要使用的欄位和/或回應格式。詳情請參閱 API 說明文件。
    • API 可能有可呼叫的多個資源。請參閱說明文件，判斷是否應使用其他資源，並能傳回所需資料。
    • 程式碼編寫後，API 可能已變更。如需進一步說明，請參閱說明文件或洽詢開發人員。

  • 400 Bad Request 通常表示傳送至伺服器的要求格式或結構有誤。檢查要求並與 API 規格進行比較，確保要求符合預期。如要進一步瞭解如何檢查要求，請參閱「檢查要求」。

  • 401 Unauthorized 通常表示 API 在未提供或成功執行授權的情況下遭到呼叫。

    • 如果 API 使用基本授權，請確認 Authorization 標頭已建構並在要求中提供。
    • 如果 API 使用 OAuth 2.0，請確認已取得存取權杖，並以不記名憑證的形式提供。
    • 對於任何其他授權變化，請務必提供要求所需的憑證。

  • 403 Forbidden 表示使用者沒有所要求資源的權限。

    • 確認使用者已獲得必要權限，例如在檔案要求中授予使用者檔案存取權。

  • 404 Not Found 表示要求的資源不存在。

    • 請確認用於 API 端點的網址是否正確。
    • 如果要擷取資源，請檢查所參照的資源是否存在 (例如，檔案型 API 的檔案是否存在)。

檢查要求

當 API 回應指出要求格式不正確 (例如傳回 400 狀態碼) 時，檢查要求就很有用。為協助檢查要求，UrlFetchApp 提供了 fetch() 方法的伴隨方法，稱為 getRequest()

這個方法不會將要求傳送至伺服器，而是會建構「會」傳送的要求，然後傳回該要求。這可讓使用者檢查要求的元素，確保要求看起來正確無誤。

舉例來說，如果要求中的表單資料包含許多連結在一起的字串，錯誤可能出在您用來產生該表單資料所建立的函式。最簡單的做法如下：

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

可讓您檢查要求的元素。

記錄要求和回應

為協助檢查第三方 API 的要求和回應的整個程序，您可以使用下列輔助函式取代 UrlFetchApp.fetch()，記錄要求和回應。

  1. 將程式碼中的所有 UrlFetchApp.fetch() 例項替換為 logUrlFetch()。

  2. 將下列函式新增至指令碼結尾。

    function logUrlFetch(url, opt_params) {
  const params = opt_params || {};
  params.muteHttpExceptions = true;
  const request = UrlFetchApp.getRequest(url, params);
  console.log('Request:       >>> ' + JSON.stringify(request));
  const response = UrlFetchApp.fetch(url, params);
  console.log('Response Code: <<< ' + response.getResponseCode());
  console.log('Response text: <<< ' + response.getContentText());
  if (response.getResponseCode() >= 400) {
    throw Error('Error in response: ' + response);
  }
  return response;
}

執行指令碼時，所有要求和回應的詳細資料都會記錄到控制台，方便您進行偵錯。