記錄

開發任何類型的應用程式時，您經常會想記錄資訊，以在開發期間診斷錯誤、識別及診斷客戶問題，以及用於其他用途。

Apps Script 提供三種不同的記錄機制：

  • 內建的 Apps Script 執行記錄。 這個記錄是輕量的資料，會即時串流，但只會保留一小段時間。

  • 開發人員控制台的 Cloud Logging 介面，提供建立後可持續保留幾天的記錄。

  • Developer Console 中的 Error Reporting 介面，該介面會收集並記錄指令碼執行期間發生的錯誤。

我們會在以下各節中說明。除了這些機制，您也可以建構自己的記錄器程式碼，例如將資訊寫入記錄試算表或 JDBC 資料庫。

使用 Apps Script 執行記錄

記錄 Apps Script 的基本方法是使用內建執行記錄。如要查看這些記錄，請按一下編輯器頂端的「Execution log」(執行記錄)。執行函式或使用偵錯工具時，記錄檔串流會即時串流。

您可以使用內建執行記錄檔中的 Logger 或 console 記錄服務。

這些記錄適用於在開發和偵錯期間的簡單檢查，且不會保留太久。

例如，請思考這個函式：

utils/logging.gs
/**
 * Logs Google Sheet information.
 * @param {number} rowNumber The spreadsheet row number.
 * @param {string} email The email to send with the row data.
 */
function emailDataRow(rowNumber, email) {
  console.log('Emailing data row ' + rowNumber + ' to ' + email);
  try {
    const sheet = SpreadsheetApp.getActiveSheet();
    const data = sheet.getDataRange().getValues();
    const rowData = data[rowNumber - 1].join(' ');
    console.log('Row ' + rowNumber + ' data: ' + rowData);
    MailApp.sendEmail(email, 'Data in row ' + rowNumber, rowData);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

執行這個指令碼時，如果輸入內容為「2」和「john@example.com」，系統會寫入下列記錄檔：

[16-09-12 13:50:42:193 PDT] 將第 2 列的電子郵件傳送至 john@example.com
[16-09-12 13:50:42:271 PDT] 第 2 列資料：費用 103.24

Cloud Logging

Apps Script 也提供 Google Cloud Platform (GCP) Cloud Logging 服務的部分存取權。當您需要保留數天的記錄，或多使用者實際工作環境需要更複雜的記錄解決方案時，建議您選用 Cloud Logging。如需瞭解資料保留及其他配額，請參閱 Cloud Logging 配額與限制。

如需更多記錄配額，您可以提交 Google Cloud Platform 配額申請。您必須能夠存取指令碼使用的 Cloud Platform 專案。

使用 Cloud Logging

Cloud 記錄會附加至與 Apps Script 相關聯的 Google Cloud 專案。您可以前往 Apps Script 資訊主頁查看這些記錄的簡化版本。

如要充分利用 Cloud Logging 及其功能，請使用標準 Google Cloud 專案搭配指令碼專案。這可讓您直接在 GCP 主控台中存取 Cloud 記錄，並提供更多查看和篩選選項。

記錄時，為避免記錄使用者的任何個人資訊 (例如電子郵件地址)，為確保隱私權是很好的做法。Cloud 記錄檔會自動為有效使用者金鑰加上標籤，讓您在必要時找出特定使用者的記錄訊息。

您可以使用 Apps Script console 服務提供的函式記錄字串、格式化字串，甚至是 JSON 物件。

以下範例說明如何使用 console 服務在 Cloud 作業套件中記錄資訊。

utils/logging.gs
/**
 * Logs the time taken to execute 'myFunction'.
 */
function measuringExecutionTime() {
  // A simple INFO log message, using sprintf() formatting.
  console.info('Timing the %s function (%d arguments)', 'myFunction', 1);

  // Log a JSON object at a DEBUG level. The log is labeled
  // with the message string in the log viewer, and the JSON content
  // is displayed in the expanded log structure under "jsonPayload".
  const parameters = {
    isValid: true,
    content: 'some string',
    timestamp: new Date()
  };
  console.log({message: 'Function Input', initialData: parameters});
  const label = 'myFunction() time'; // Labels the timing log entry.
  console.time(label); // Starts the timer.
  try {
    myFunction(parameters); // Function to time.
  } catch (e) {
    // Logs an ERROR message.
    console.error('myFunction() yielded an error: ' + e);
  }
  console.timeEnd(label); // Stops the timer, logs execution duration.
}

有效使用者金鑰

臨時活躍使用者金鑰可讓您輕鬆在 Cloud 記錄項目中找出不重複使用者，而無須揭露這些使用者的身分。每個指令碼都有金鑰，每個月大約變更一次，如果使用者 (例如在回報問題時) 揭露身分，這個功能可提供額外的安全防護。

臨時活躍使用者金鑰優於記錄電子郵件地址等 ID，原因如下：

  • 您無需在記錄中新增任何項目，因為系統就是您！
  • 因此不需要使用者授權。
  • 能保護使用者隱私。

如要在 Cloud 記錄項目中尋找暫時性的活躍使用者金鑰，請在 Google Cloud 控制台中查看 Cloud 記錄檔。只有在指令碼專案使用您能存取的標準 Google Cloud 專案時，才能執行這項操作。在主控台中開啟 Google Cloud 專案後，選取您想查看的記錄項目，然後展開該項目來查看 metadata > labels >script.googleapis.com/user_key。

您也可以在指令碼中呼叫 Session.getTemporaryActiveUserKey()，取得臨時活躍使用者金鑰。使用此方法的方法之一，就是在使用者執行指令碼時向使用者顯示金鑰。使用者可以選擇在回報問題時納入金鑰，以協助您找出相關記錄。

記錄例外狀況

例外狀況記錄功能會將指令碼專案程式碼中未處理的例外狀況，以及堆疊追蹤傳送至 Cloud Logging。

如要查看例外狀況記錄，請按照下列步驟操作：

  1. 開啟 Apps Script 專案。
  2. 按一下左側的「執行」圖示 。
  3. 依序按一下頂端的「新增篩選器」>「狀態」。
  4. 勾選「失敗」和「逾時」核取方塊。

您也可以在 GCP 控制台中查看記錄的例外狀況，前提是指令碼專案使用的是您有權存取的標準 Google Cloud 專案。

啟用例外狀況記錄功能

新專案預設會啟用例外狀況記錄功能。如要為較舊的專案啟用例外狀況記錄，請按照下列步驟操作：

  1. 開啟指令碼專案。
  2. 按一下左側的「專案設定」圖示 。
  3. 勾選「Log uncaughtException to Cloud Operations」(將未擷取的例外狀況記錄至 Cloud 作業) 核取方塊。

Error Reporting

例外狀況記錄功能會自動與 Cloud Error Reporting 整合，這項服務可以匯總並顯示指令碼產生的錯誤。您可以在 Google Cloud 控制台中查看 Cloud 錯誤報告。 如果系統提示您「設定 Error Reporting」，是因為您的指令碼尚未記錄任何例外狀況。除了啟用例外狀況記錄以外，完全不需要設定。

記錄需求

使用內建執行記錄沒有任何要求。

您可以在 Apps Script 資訊主頁中查看簡化版的 Cloud 記錄檔。但為了充分運用 Cloud Logging 和錯誤報告，您必須能夠存取指令碼的 GCP 專案。只有在指令碼專案使用標準 Google Cloud 專案時，才能採用這種做法。