記錄

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

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

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

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

• 開發人員控制台中的「錯誤報告」介面，會收集並記錄指令碼執行時發生的錯誤。

以下各節將說明這些模式。除了這些機制，您也可以建立自己的記錄器程式碼，例如將資訊寫入記錄 試算表或 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」和「[e-mail]」輸入執行這項指令碼時，系統會寫入下列記錄：

[16-09-12 13:50:42:193 PDT] Emailing data row 2 to [e-mail]
[16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

Cloud Logging

Apps Script 也提供 Google Cloud Platform (GCP) Cloud Logging 服務的部分存取權。如果需要保留記錄幾天，或是需要更複雜的記錄解決方案，以用於多使用者正式環境，建議使用 Cloud Logging。如需資料保留時間和其他配額詳細資料，請參閱「Cloud Logging 配額與限制」。

如需更多記錄配額，請提交 Google Cloud Platform 配額要求。您必須有權存取指令碼使用的 Cloud Platform 專案，才能執行這項操作。

注意： 除了儲存記錄外，Cloud Logging 也提供多項服務，例如快訊和指標。目前無法透過 Apps Script 使用這些服務。

使用 Cloud Logging

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

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

注意： 如果您使用 Rhino 執行階段，Cloud Logging 不支援 Apps Script Logger 服務。請改用 console 服務。

記錄時，請避免記錄使用者的任何個人資訊，例如電子郵件地址，這是良好的隱私權做法。雲端記錄會自動標示有效使用者金鑰，您可以在必要時使用這些金鑰找出特定使用者的記錄訊息。

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

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

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 專案後，選取感興趣的記錄項目並展開，即可查看中繼資料 > 標籤 > 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 專案時，才能執行這項操作。