Cách sử dụng PropertiesService một cách hiệu quả

Google Apps Script là một nền tảng mạnh mẽ giúp bạn tự động hóa các tác vụ với Google Workspace như Google Sheets, Docs, Drive, Gmail… Một trong những công cụ quan trọng để lưu trữ dữ liệu cấu hình, thông tin tạm thời hay trạng thái của script chính là PropertiesService.

Trong bài viết này, chúng ta sẽ tìm hiểu cách sử dụng PropertiesService một cách hiệu quả, giúp code của bạn sạch hơn, dễ bảo trì hơn và hoạt động ổn định hơn trong môi trường Google Apps Script.

---

1. PropertiesService là gì?

PropertiesService là một dịch vụ trong Google Apps Script cho phép bạn lưu trữ và truy xuất các cặp khóa-giá trị (key-value pairs). Dữ liệu được lưu ở dạng văn bản (string) và được phân loại theo 3 loại chính:

• Script Properties: dùng chung cho toàn bộ dự án script. Mọi người dùng đều truy cập được.
• User Properties: chỉ áp dụng với người dùng hiện tại.
• Document Properties: chỉ dùng được trong các tài liệu (Docs, Sheets, Slides) và gắn với tài liệu đó.

---

2. Khi nào nên dùng PropertiesService?

Bạn nên sử dụng PropertiesService trong các trường hợp sau:

• Lưu API key, token xác thực.
• Ghi lại trạng thái chạy của script (lần chạy cuối, ID xử lý cuối…).
• Lưu cấu hình do người dùng thiết lập.
• Cache dữ liệu nhỏ để giảm truy vấn API lặp lại.

Lưu ý: PropertiesService không nên dùng để lưu trữ dữ liệu lớn hoặc nhạy cảm như mật khẩu chưa mã hóa. Giới hạn lưu trữ là 500KB mỗi loại property.

---

3. Cách sử dụng các loại Properties

a. Script Properties

javascriptCopyEditfunction setScriptProperty() {
  var scriptProperties = PropertiesService.getScriptProperties();
  scriptProperties.setProperty("API_KEY", "abc123");
}

function getScriptProperty() {
  var scriptProperties = PropertiesService.getScriptProperties();
  var apiKey = scriptProperties.getProperty("API_KEY");
  Logger.log(apiKey);
}

b. User Properties

javascriptCopyEditfunction setUserProperty() {
  var userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty("theme", "dark");
}

function getUserProperty() {
  var userProperties = PropertiesService.getUserProperties();
  var theme = userProperties.getProperty("theme");
  Logger.log(theme);
}

c. Document Properties

javascriptCopyEditfunction setDocumentProperty() {
  var docProperties = PropertiesService.getDocumentProperties();
  docProperties.setProperty("lastEditedBy", Session.getActiveUser().getEmail());
}

function getDocumentProperty() {
  var docProperties = PropertiesService.getDocumentProperties();
  var editor = docProperties.getProperty("lastEditedBy");
  Logger.log(editor);
}

---

4. Quản lý nhiều thuộc tính cùng lúc

Bạn có thể lưu và truy xuất nhiều giá trị cùng lúc bằng cách sử dụng đối tượng JavaScript:

javascriptCopyEdit// Set nhiều properties
function setMultipleProperties() {
  var props = {
    "username": "admin",
    "timeout": "30",
    "language": "vi"
  };
  PropertiesService.getScriptProperties().setProperties(props);
}

// Lấy toàn bộ properties
function getAllProperties() {
  var allProps = PropertiesService.getScriptProperties().getProperties();
  Logger.log(allProps);
}

---

5. Xóa thuộc tính

Bạn có thể xóa từng thuộc tính hoặc xóa toàn bộ:

javascriptCopyEdit// Xóa một key
function deleteProperty() {
  PropertiesService.getScriptProperties().deleteProperty("username");
}

// Xóa tất cả key
function deleteAllProperties() {
  PropertiesService.getScriptProperties().deleteAllProperties();
}

---

6. Những lưu ý để sử dụng hiệu quả

• Không lưu dữ liệu nhạy cảm dưới dạng plaintext: Nếu bạn lưu token hoặc thông tin quan trọng, hãy mã hóa trước.
• Sử dụng ScriptProperties cho các cấu hình toàn cục, ví dụ như cấu hình API.
• Dùng UserProperties khi cần lưu dữ liệu tùy biến theo từng người dùng.
• Ghi chú rõ ràng các key được sử dụng trong properties để tránh trùng lặp hoặc bị ghi đè.
• Kết hợp với giao diện UI (Google Sheets sidebar, dialog) để cho phép người dùng chỉnh sửa cài đặt và lưu qua PropertiesService.

---

7. Tình huống thực tế: Lưu Token API

Ví dụ, bạn kết nối đến một API và token chỉ có hiệu lực 1 giờ. Bạn có thể lưu token và thời gian hết hạn vào ScriptProperties, và chỉ lấy token mới khi cần:

javascriptCopyEditfunction getApiToken() {
  var props = PropertiesService.getScriptProperties();
  var token = props.getProperty("token");
  var expiresAt = parseInt(props.getProperty("expires_at"));

  if (!token || Date.now() > expiresAt) {
    // Gọi API để lấy token mới
    var response = UrlFetchApp.fetch("https://example.com/get-token");
    var data = JSON.parse(response.getContentText());
    token = data.token;

    // Lưu token và thời gian hết hạn
    props.setProperties({
      "token": token,
      "expires_at": (Date.now() + 3600000).toString() // 1 giờ
    });
  }

  return token;
}

---

8. Kết luận

PropertiesService là một công cụ cực kỳ hữu ích giúp bạn lưu trữ dữ liệu cấu hình và trạng thái trong Google Apps Script một cách gọn gàng và hiệu quả. Khi được sử dụng đúng cách, nó giúp cho mã nguồn của bạn rõ ràng hơn, dễ bảo trì hơn và có thể mở rộng nhanh chóng trong các dự án tự động hóa Google Workspace.