本頁面由 Cloud Translation API 翻譯而成。

記錄

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

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

內建的 Apps Script 執行記錄。這個記錄輕量且會即時串流，但僅保留一小段時間。
Developer Console 的 Cloud Logging 介面，提供的記錄會在建立後保留幾天。
Developer Console 的 Error Reporting 介面，可收集並記錄指令碼執行期間發生的錯誤。

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

使用 Apps Script 執行記錄

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

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

這些記錄檔僅供在開發和偵錯期間進行簡易檢查，且不會太久。

例如，請考量這個函式：

utils/logging.gs

前往 GitHub 查看

/**
 * 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

前往 GitHub 查看

/**
 * 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 Log 項目中找出不重複使用者，而不需揭露這些使用者的身分。每個指令碼都有不同的金鑰，而且大約每個月會變更一次，以便在使用者向開發人員透露自己的身分時提供額外的安全性，例如在使用者回報問題時提供。

暫時性的活躍使用者金鑰比電子郵件地址等記錄 ID 更出色，原因如下：

您不必新增任何項目，因為記錄中已含有這些項目！
而且不需要使用者授權。
能保護使用者隱私。

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

您也可以在指令碼中呼叫 Session.getTemporaryActiveUserKey()，取得臨時的有效使用者金鑰。這個方法的其中一種方法是，在使用者執行指令碼時向使用者顯示索引鍵。使用者可以選擇在回報問題時納入金鑰，以協助您找出相關記錄檔。

例外狀況記錄

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

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

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

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

啟用例外狀況記錄功能

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

開啟指令碼專案。
按一下左側的「Project Settings」圖示。
勾選「將未偵測到的例外狀況記錄至 Cloud 作業套件」核取方塊。

Error Reporting

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

記錄需求

使用內建的執行記錄不需要。

您可以在 Apps Script 資訊主頁查看簡化的 Cloud 記錄版本。不過，如要充分運用 Cloud Logging 和錯誤報告，您必須具備指令碼 GCP 專案的存取權。只有在指令碼專案使用標準 Google Cloud 專案時，才能執行這項操作。