第三方 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。

為說明如何搭配 UrlFetchApp 使用 POST 呼叫,以下範例示範與協作訊息應用程式 Slack 整合,將 Slack 訊息傳送給 Slack 使用者和群組。

設定 Slack

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

與前一個範例中的 OpenWeatherMap 一樣,您必須取得權杖,才能傳送訊息。Slack 會提供專屬網址,讓您傳送訊息給團隊,稱為「傳入 Webhook」。

按一下「Add Incoming WebHooks Integration」,然後按照操作說明設定傳入 Webhook。這個程序應會產生用於傳送訊息的網址。

提出 POST 要求

設定傳入 Webhook 後,如要提出 POST 要求,您必須在傳遞至 UrlFetchApp.fetch 的 options 參數中使用一些額外屬性:

  • method:如前所述,這項設定預設為 GET,但我們在此覆寫並設為 POST。
  • payload:這是要傳送至伺服器的資料,屬於 POST 要求的一部分。在這個範例中,Slack 預期會收到序列化為 JSON 格式的物件,如 Slack 說明文件所述。為此,請使用 [JSON.stringify][json-stringify-url] 方法,並將 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

熱門 API 會使用 OAuth 2.0 提供使用者資料存取權。特定第三方服務的帳戶擁有者會授予特定應用程式權限,允許這些應用程式存取使用者資料。優點是擁有者:

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

如要在 Google Ads 指令碼中使用支援 OAuth 2.0 的服務,請按照下列步驟操作:

指令碼以外

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

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

在指令碼中

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

提出 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);

用戶端憑證授權

[用戶端憑證授權][client-credentials-rfc] 是較簡單的 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

更新權杖授權

更新權杖授權與用戶端憑證授權類似,向伺服器發出的要求會傳回可在工作階段中使用的存取權杖。

重新整理權杖

取得更新權杖

與更新權杖授權的不同之處在於,用戶端憑證授權所需的詳細資料來自應用程式設定 (例如在服務的控制台中),而更新權杖授權則是更複雜流程的一部分,例如 [授權碼授權][authorization-code-rfc],這需要使用者互動:

授權碼

使用 OAuth Playground 取得更新權杖

OAuth2 Playground 提供使用者介面,可讓使用者逐步完成授權碼授權,取得更新權杖。

點選右上方的「設定」按鈕,即可定義要在 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. 在 Google Cloud 控制台中建立新專案,然後按照 Search Ads 360 指南中的程序取得用戶端 ID、用戶端密鑰和更新權杖,並確認已啟用 Search Ads 360 API。
  2. 將 [範例指令碼][search-ads-360-example] 貼到 Google Ads 的新指令碼中。
  3. 在程式碼清單下方貼上 [OAuth2 程式庫範例][oauth20-library-example]。
  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. 按一下專案名稱,前往 Google Cloud 控制台。
  4. 前往「API 和服務」。
  5. 啟用適當的 API,在本例中為 Drive API 和 Apps Script Execution API。
  6. 從選單中的「憑證」項目建立 OAuth 憑證。
  7. 返回指令碼,依序點選「Publish」>「Deploy as API Executable」,發布指令碼以供執行。
建立 Google Ads 指令碼
  1. 將指令碼範例貼到 Google Ads 的新指令碼中。
  2. 此外,請在程式碼清單下方貼上 [OAuth2 程式庫範例][oauth20-library-example]。
  3. 修改指令碼,加入正確的用戶端 ID、用戶端密鑰和更新權杖值。

服務帳戶

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

服務帳戶與授權類型不同,因為服務帳戶並非用於存取使用者資料:驗證後,服務帳戶會代表應用程式提出要求,而非代表可能擁有專案的使用者。舉例來說,如果服務帳戶使用 Drive API 建立檔案,該檔案會屬於服務帳戶,且根據預設,專案擁有者無法存取。

Google Natural Language API 範例

[Natural Language API][natural-language-api-docs] 可為文字提供 [情緒分析][sentiment-analysis-api-docs] 和 [實體分析][entity-analysis-api-docs]。

這個範例說明如何計算廣告文字 (包括廣告標題或說明) 的 [情緒][sentiment-api-docs]。這項指標可衡量 訊息的正面程度和訊息量: 我們賣蛋糕或我們賣倫敦最棒的蛋糕,哪一個比較好?歡迎立即選購!

設定指令碼
  1. 在 Google Cloud 控制台中建立新專案。
  2. 啟用 [Natural Language API][natural-language-api]。
  3. 啟用專案的計費功能。
  4. [建立服務帳戶][create-service-account]。下載憑證 JSON 檔案。
  5. 將 [範例指令碼][natural-language-example] 貼到 Google Ads 的新指令碼中。
  6. 此外,請在程式碼清單下方貼上 [OAuth2 程式庫範例][oauth20-library-example]。
  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

XmlService 可讓指令碼剖析及擷取 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_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

請注意命名空間在根元素中的指定方式。因此,您必須:

  • 從文件中擷取命名空間屬性。
  • 周遊及存取子項元素時,請使用這個命名空間。

以下範例說明如何存取 <schedule> 元素,並在上述文件片段中搜尋其 <sport_event> 子元素:

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

取得值

請參考下方的足球賽程範例:

<sport_event_status status="..." ... />

您可以擷取屬性,例如:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

您可以使用 getText() 讀取元素中的文字,但如果元素有多個文字子項,這些文字會串連在一起。如果可能有多個文字子項,請考慮使用 getChildren() 並疊代每個子項。

Sportradar 範例

這個完整的 Sportradar 範例說明如何擷取足球比賽的詳細資料,特別是英格蘭足球超級聯賽。Soccer API 是 Sportradar 提供的眾多體育賽事動態消息之一。

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

Sportradar 會將不同運動項目分成不同的 API。舉例來說,您可能購買了 Soccer API 的存取權,但沒有 Tennis API 的存取權。您建立的每個應用程式都可以與不同的運動和金鑰建立關聯。

  1. 在「應用程式」下方,按一下「建立新的應用程式」。為應用程式提供名稱和說明,並忽略網站欄位。
  2. 只選取「為 Soccer Trial Europe v2 核發新金鑰」。
  3. 按一下「Register Application」。

成功後,系統會顯示含有新 API 金鑰的頁面。

  1. 將範例指令碼貼到 Google Ads 的新指令碼中。
  2. 將清單中的 API 金鑰替換為新核發的金鑰,並編輯電子郵件地址欄位。

疑難排解

使用第三方 API 時,可能因多種原因發生錯誤,例如:

  • 用戶端向伺服器發出要求的格式不符合 API 預期。
  • 用戶端預期的回應格式與實際收到的格式不同。
  • 用戶端使用無效的權杖或金鑰,或將值留做預留位置。
  • 用戶端達到用量限制。
  • 用戶端提供無效參數。

在上述所有情況和其他情況下,找出問題原因的第一步,就是檢查導致錯誤的回應詳細資料。

剖析回覆

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

如要避免這種行為,並允許檢查錯誤和錯誤訊息,請將選用參數的 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(url, params)

這個方法不會將要求傳送至伺服器,而是建構「原本會」傳送的要求,然後傳回該要求。這樣一來,使用者就能檢查要求元素,確保要求正確無誤。

舉例來說,如果要求中的表單資料是由許多串連在一起的字串組成,則錯誤可能在於您建立用來產生該表單資料的函式。簡單來說:

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;
    }
    

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities