Class ScriptApp

ScriptApp

Truy cập và thao tác với tính năng xuất bản và kích hoạt tập lệnh. Lớp này cho phép người dùng tạo trình kích hoạt tập lệnh và kiểm soát hoạt động xuất bản tập lệnh ở dạng dịch vụ.

Thuộc tính

Thuộc tínhLoạiMô tả
AuthModeAuthModeMột bảng liệt kê xác định những danh mục dịch vụ được ủy quyền mà Apps Script có thể thực thi thông qua một hàm đã kích hoạt.
AuthorizationStatusAuthorizationStatusMột bảng liệt kê biểu thị trạng thái uỷ quyền của một tập lệnh.
EventTypeEventTypeMột bảng liệt kê biểu thị loại sự kiện đã kích hoạt.
InstallationSourceInstallationSourceMột bảng liệt kê biểu thị cách cài đặt tập lệnh cho người dùng dưới dạng tiện ích bổ sung.
TriggerSourceTriggerSourceMột bảng liệt kê biểu thị nguồn của sự kiện khiến trình kích hoạt kích hoạt.
WeekDayWeekdayMột bảng liệt kê biểu thị các ngày trong tuần.

Phương pháp

Phương thứcLoại dữ liệu trả vềMô tả ngắn
deleteTrigger(trigger)voidXoá trình kích hoạt đã cho để không còn chạy nữa.
getAuthorizationInfo(authMode)AuthorizationInfoLấy đối tượng dùng để xác định xem người dùng có cần uỷ quyền cho tập lệnh này sử dụng một hoặc nhiều dịch vụ hay không, đồng thời cung cấp URL cho hộp thoại uỷ quyền.
getIdentityToken()StringLấy mã thông báo nhận dạng OpenID Connect cho người dùng hiệu quả, nếu phạm vi openid đã được cấp.
getInstallationSource()InstallationSourceTrả về giá trị enum cho biết cách cài đặt tập lệnh dưới dạng tiện ích bổ sung cho người dùng hiện tại (ví dụ: liệu người dùng đã cài đặt riêng tập lệnh đó thông qua Cửa hàng Chrome trực tuyến hay quản trị viên miền đã cài đặt tập lệnh cho tất cả người dùng).
getOAuthToken()StringLấy mã truy cập OAuth 2.0 cho người dùng hiệu quả.
getProjectTriggers()Trigger[]Lấy tất cả các trình kích hoạt có thể cài đặt được liên kết với dự án hiện tại và người dùng hiện tại.
getScriptId()StringLấy mã nhận dạng duy nhất của dự án tập lệnh.
getService()ServiceLấy đối tượng dùng để kiểm soát việc xuất bản tập lệnh dưới dạng ứng dụng web.
getUserTriggers(document)Trigger[]Lấy tất cả trình kích hoạt có thể cài đặt do người dùng này sở hữu trong tài liệu nhất định, chỉ dành cho tập lệnh hoặc tiện ích bổ sung này.
getUserTriggers(form)Trigger[]Lấy tất cả các trình kích hoạt có thể cài đặt do người dùng này sở hữu trong biểu mẫu nhất định, chỉ dành cho tập lệnh hoặc tiện ích bổ sung này.
getUserTriggers(spreadsheet)Trigger[]Lấy tất cả các trình kích hoạt có thể cài đặt thuộc sở hữu của người dùng này trong bảng tính nhất định, dành cho tập lệnh hoặc tiện ích bổ sung này.
invalidateAuth()voidVô hiệu hóa uỷ quyền mà người dùng hiệu quả phải thực thi tập lệnh hiện tại.
newStateToken()StateTokenBuilderTạo trình tạo cho mã thông báo trạng thái có thể được sử dụng trong API gọi lại (như luồng OAuth).
newTrigger(functionName)TriggerBuilderBắt đầu quy trình tạo một trình kích hoạt có thể cài đặt, khi được kích hoạt, sẽ gọi một hàm nhất định.

Tài liệu chi tiết

deleteTrigger(trigger)

Xoá trình kích hoạt đã cho để không còn chạy nữa. 

// Deletes all triggers in the current project.
var triggers = ScriptApp.getProjectTriggers();
for (var i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Các tham số

TênLoạiMô tả
triggerTriggerTrình kích hoạt cần xoá.

Ủy quyền

Các tập lệnh sử dụng phương pháp này yêu cầu uỷ quyền bằng một hoặc nhiều phạm vi sau:

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

Lấy đối tượng dùng để xác định xem người dùng có cần uỷ quyền cho tập lệnh này sử dụng một hoặc nhiều dịch vụ hay không, đồng thời cung cấp URL cho hộp thoại uỷ quyền. Nếu tập lệnh được xuất bản dưới dạng tiện ích bổ sung sử dụng trình kích hoạt có thể cài đặt, thì thông tin này có thể được dùng để kiểm soát quyền truy cập vào các phần mã mà người dùng không có quyền cần thiết. Ngoài ra, tiện ích bổ sung có thể yêu cầu người dùng mở URL của hộp thoại ủy quyền để giải quyết vấn đề. 

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

Các tham số

TênLoạiMô tả
authModeAuthModechế độ ủy quyền yêu cầu thông tin ủy quyền; trong hầu hết mọi trường hợp, giá trị của authMode phải là ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL) vì không có chế độ ủy quyền nào khác yêu cầu người dùng phải ủy quyền

Hai chiều

AuthorizationInfo – một đối tượng có thể cung cấp thông tin về trạng thái uỷ quyền của người dùng

getIdentityToken()

Lấy mã thông báo nhận dạng OpenID Connect cho người dùng hiệu quả, nếu phạm vi openid đã được cấp. Phạm vi này không được bao gồm theo mặc định và bạn phải thêm phạm vi này dưới dạng một phạm vi rõ ràng trong tệp kê khai để yêu cầu phạm vi này. Bao gồm các phạm vi https://www.googleapis.com/auth/userinfo.email hoặc https://www.googleapis.com/auth/userinfo.profile để trả về thông tin người dùng bổ sung trong mã thông báo.

Mã thông báo nhận dạng được trả về là một Mã thông báo web JSON (JWT) đã mã hoá, và phải được giải mã để trích xuất thông tin từ mã đó. Các ví dụ sau đây cho thấy cách giải mã mã thông báo và trích xuất mã hồ sơ hiệu quả của người dùng trên Google. 

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
Xem tài liệu OpenID Connect để biết danh sách đầy đủ các trường (thông báo xác nhận quyền sở hữu) được trả về.

Hai chiều

String – Mã thông báo nhận dạng (nếu có); nếu không thì null.

getInstallationSource()

Trả về giá trị enum cho biết cách cài đặt tập lệnh dưới dạng tiện ích bổ sung cho người dùng hiện tại (ví dụ: liệu người dùng đã cài đặt riêng tập lệnh đó thông qua Cửa hàng Chrome trực tuyến hay quản trị viên miền đã cài đặt tập lệnh cho tất cả người dùng).

Hai chiều

InstallationSource — Nguồn cài đặt.

getOAuthToken()

Lấy mã truy cập OAuth 2.0 cho người dùng hiệu quả. Nếu phạm vi OAuth của tập lệnh đủ để ủy quyền cho một API khác của Google thường yêu cầu quy trình OAuth riêng (như Bộ chọn Google), thì các tập lệnh có thể bỏ qua lời nhắc ủy quyền thứ hai bằng cách chuyển mã thông báo này. Mã thông báo sẽ hết hạn sau một khoảng thời gian (tối thiểu là vài phút); các tập lệnh sẽ xử lý lỗi uỷ quyền và gọi phương thức này để lấy mã thông báo mới khi cần.

Mã thông báo được trả về bằng phương thức này chỉ bao gồm các phạm vi mà tập lệnh hiện cần. Các phạm vi đã được uỷ quyền trước đó nhưng không còn được tập lệnh sử dụng nữa sẽ không được đưa vào mã thông báo được trả về. Nếu cần thêm phạm vi OAuth ngoài phạm vi của tập lệnh, thì bạn có thể chỉ định phạm vi đó trong tệp kê khai của tập lệnh.

Hai chiều

String – Bản trình bày chuỗi của mã thông báo OAuth 2.0.

getProjectTriggers()

Lấy tất cả các trình kích hoạt có thể cài đặt được liên kết với dự án hiện tại và người dùng hiện tại. 

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

Hai chiều

Trigger[] – Một mảng các trình kích hoạt hiện tại của người dùng được liên kết với dự án này.

Ủy quyền

Các tập lệnh sử dụng phương pháp này yêu cầu uỷ quyền bằng một hoặc nhiều phạm vi sau:

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

Lấy mã nhận dạng duy nhất của dự án tập lệnh. Đây là phương thức ưu tiên để nhận giá trị nhận dạng duy nhất cho dự án tập lệnh thay vì getProjectKey(). Bạn có thể sử dụng mã nhận dạng này ở tất cả những vị trí đã cung cấp khoá dự án trước đó.

Hai chiều

String – Mã dự án của tập lệnh.

getService()

Lấy đối tượng dùng để kiểm soát việc xuất bản tập lệnh dưới dạng ứng dụng web. 

// Get the URL of the published web app.
var url = ScriptApp.getService().getUrl();

Hai chiều

Service – Một đối tượng dùng để quan sát và kiểm soát việc xuất bản tập lệnh dưới dạng ứng dụng web.

getUserTriggers(document)

Lấy tất cả trình kích hoạt có thể cài đặt do người dùng này sở hữu trong tài liệu nhất định, chỉ dành cho tập lệnh hoặc tiện ích bổ sung này. Bạn không thể sử dụng phương pháp này để xem các trình kích hoạt được đính kèm với tập lệnh khác. 

var doc = DocumentApp.getActiveDocument();
var triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Các tham số

TênLoạiMô tả
documentDocumentTệp Google Tài liệu có thể chứa các trình kích hoạt có thể cài đặt.

Hai chiều

Trigger[] – Một dãy các trình kích hoạt do người dùng này sở hữu trong tài liệu nhất định.

Ủy quyền

Các tập lệnh sử dụng phương pháp này yêu cầu uỷ quyền bằng một hoặc nhiều phạm vi sau:

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(form)

Lấy tất cả các trình kích hoạt có thể cài đặt do người dùng này sở hữu trong biểu mẫu nhất định, chỉ dành cho tập lệnh hoặc tiện ích bổ sung này. Bạn không thể sử dụng phương pháp này để xem các trình kích hoạt được đính kèm với tập lệnh khác. 

var form = FormApp.getActiveForm();
var triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Các tham số

TênLoạiMô tả
formFormTệp Google Biểu mẫu có thể chứa các trình kích hoạt có thể cài đặt.

Hai chiều

Trigger[] – Một mảng các trình kích hoạt do người dùng này sở hữu trong biểu mẫu nhất định.

Ủy quyền

Các tập lệnh sử dụng phương pháp này yêu cầu uỷ quyền bằng một hoặc nhiều phạm vi sau:

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(spreadsheet)

Lấy tất cả các trình kích hoạt có thể cài đặt thuộc sở hữu của người dùng này trong bảng tính nhất định, dành cho tập lệnh hoặc tiện ích bổ sung này. Bạn không thể sử dụng phương pháp này để xem các trình kích hoạt được đính kèm với tập lệnh khác. 

var ss = SpreadsheetApp.getActiveSpreadsheet();
var triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Các tham số

TênLoạiMô tả
spreadsheetSpreadsheetMột tệp Google Trang tính có thể chứa các trình kích hoạt có thể cài đặt.

Hai chiều

Trigger[] – Một mảng các trình kích hoạt do người dùng này sở hữu trong bảng tính đã cho.

Ủy quyền

Các tập lệnh sử dụng phương pháp này yêu cầu uỷ quyền bằng một hoặc nhiều phạm vi sau:

  • https://www.googleapis.com/auth/script.scriptapp

invalidateAuth()

Vô hiệu hóa uỷ quyền mà người dùng hiệu quả phải thực thi tập lệnh hiện tại. Dùng để vô hiệu hoá mọi quyền đối với tập lệnh hiện tại. Điều này đặc biệt hữu ích đối với các hàm được gắn thẻ là uỷ quyền một lần. Do các hàm uỷ quyền một lần chỉ có thể được gọi lần chạy đầu tiên sau khi tập lệnh đã nhận được uỷ quyền, nên nếu bạn muốn thực hiện một hành động sau đó, bạn phải thu hồi mọi uỷ quyền mà tập lệnh đã có để người dùng có thể xem lại hộp thoại uỷ quyền. 

ScriptApp.invalidateAuth();

Gửi

Error — khi không hợp lệ

newStateToken()

Tạo trình tạo cho mã thông báo trạng thái có thể được sử dụng trong API gọi lại (như luồng OAuth). 

// Generate a callback URL, given the name of a callback function. The script does not need to
// be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var stateToken = ScriptApp.newStateToken()
      .withMethod(callbackFunction)
      .withTimeout(120)
      .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

Trong hầu hết các luồng OAuth2, mã thông báo state được chuyển trực tiếp đến điểm cuối ủy quyền (không phải là một phần của URL gọi lại) và điểm cuối ủy quyền sau đó chuyển điểm cuối dưới dạng một phần của URL gọi lại.

Ví dụ:

  • Tập lệnh chuyển hướng người dùng đến URL ủy quyền OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
  • Người dùng nhấp vào ủy quyền và trang uỷ quyền OAuth2 sẽ chuyển hướng người dùng quay lại https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • Lệnh chuyển hướng ở trên (quay lại http://script.google.com/...), khiến yêu cầu trình duyệt trở thành /usercallback, dẫn đến phương thức do StateTokenBuilder.withMethod(method) chỉ định.

Hai chiều

StateTokenBuilder — Một đối tượng dùng để tiếp tục quy trình xây dựng mã thông báo của tiểu bang.

newTrigger(functionName)

Bắt đầu quy trình tạo một trình kích hoạt có thể cài đặt, khi được kích hoạt, sẽ gọi một hàm nhất định. 

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Các tham số

TênLoạiMô tả
functionNameStringHàm gọi khi trình kích hoạt kích hoạt. Bạn có thể sử dụng các hàm từ các thư viện đi kèm, chẳng hạn như Library.libFunction1.

Hai chiều

TriggerBuilder – Một đối tượng dùng để tiếp tục quy trình xây dựng trình kích hoạt.

Ủy quyền

Các tập lệnh sử dụng phương pháp này yêu cầu uỷ quyền bằng một hoặc nhiều phạm vi sau:

  • https://www.googleapis.com/auth/script.scriptapp

Các phương thức ngừng hoạt động