記錄

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

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

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

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

• 開發人員控制台中的「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」和「[e-mail]」的輸入內容執行這個指令碼時，系統會寫入下列記錄：

[16-09-12 13:50:42:193 PDT] 透過電子郵件將資料第 2 列傳送至 [e-mail]
[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 還提供多項服務，例如快訊和指標。目前這些服務無法透過 Apps Script 使用。

使用 Cloud Logging

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

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

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

在記錄時，請避免記錄使用者的任何個人資訊，例如電子郵件地址，以符合隱私權規範。Cloud Logs 會自動加上活躍使用者索引鍵標記，方便您在必要時找出特定使用者的記錄訊息。

您可以使用 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 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. 勾選「Log uncaughtException to Cloud Operations」(將未擷取的例外狀況記錄至 Cloud 作業) 核取方塊。

Error Reporting

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

記錄規定

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

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