記錄

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

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

  • 內建的 Apps Script 執行記錄。這個記錄檔輕巧且可即時串流，但只會保留一段時間。

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

  • 開發人員控制台中的「Error Reporting」介面，可收集並記錄指令碼執行期間發生的錯誤。

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

使用 Apps Script 執行記錄

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

您可以在內建執行記錄中使用 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 Logs 會自動加上活躍使用者索引鍵標記，方便您在必要時找出特定使用者的記錄訊息。

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

以下範例說明如何使用 console 服務，在 Cloud Operations 中記錄資訊。

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 Logs 記錄項目中輕鬆找出不重複的使用者，且不會洩漏使用者的身分。每個指令碼都有專屬的金鑰，且大約每月變更一次，以便在使用者向開發人員揭露身分時 (例如回報問題)，提供額外的安全防護機制。

與電子郵件地址等記錄 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. 選取「失敗」和「逾時」核取方塊。

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

啟用例外狀況記錄功能

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

  1. 開啟指令碼專案。
  2. 按一下左側的「專案設定」圖示 。
  3. 勾選「將未偵測到的例外狀況記錄到 Cloud Operations」核取方塊。

Error Reporting

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

記錄規定

使用內建執行記錄沒有任何限制。

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