Class ScriptApp

ScriptApp

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

Thuộc tính

Tài sảnLoạiNội dung mô tả
AuthModeAuthModeMột bảng liệt kê xác định những danh mục dịch vụ được uỷ quyền mà Apps Script có thể thực thi thông qua một hàm được kích hoạt.
AuthorizationStatusAuthorizationStatusNội dung liệt kê cho biết trạng thái uỷ quyền của một tập lệnh.
EventTypeEventTypeMột bảng liệt kê cho biết loại sự kiện được kích hoạt.
InstallationSourceInstallationSourceBảng liệt kê cho biết cách tập lệnh được cài đặt cho người dùng dưới dạng tiện ích bổ sung.
TriggerSourceTriggerSourceBảng liệt kê cho biết 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ê các ngày trong tuần.

Phương thức

Phương thứcKiểu dữ liệu trả vềMô tả ngắn
deleteTrigger(trigger)voidXoá điều kiện kích hoạt nhất định để nó 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 cho phép 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ề một 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ó tự cài đặt tập lệnh đó thông qua Cửa hàng Chrome trực tuyến hay không hoặc liệu quản trị viên miền có cài đặt tập lệnh đó cho tất cả người dùng hay khô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 điều kiện kích hoạt có thể cài đặt được liên kết với dự án 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 một ứng dụng web.
getUserTriggers(document)Trigger[]Lấy tất cả các điều kiện 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 này hoặc tiện ích bổ sung này.
getUserTriggers(form)Trigger[]Lấy tất cả các điều kiện kích hoạt có thể cài đặt do người dùng này sở hữu ở dạng nhất định, chỉ dành cho tập lệnh này hoặc tiện ích bổ sung.
getUserTriggers(spreadsheet)Trigger[]Lấy tất cả các điều kiện kích hoạt có thể cài đặt do người dùng này sở hữu trong bảng tính nhất định, chỉ dành cho tập lệnh này hoặc tiện ích bổ sung này.
invalidateAuth()voidVô hiệu hoá lệnh uỷ quyền mà người dùng có hiệu lực 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ể dùng trong API gọi lại (như luồng OAuth).
newTrigger(functionName)TriggerBuilderBắt đầu quá 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á điều kiện kích hoạt nhất định để nó 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ạiNội dung mô tả
triggerTriggerĐiều kiện kích hoạt cần xoá.

Ủy quyền

Tập lệnh sử dụng phương thức này cần được uỷ quyền với 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 cho phép 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 phát hành dưới dạng một tiện ích bổ sung sử dụng điều kiện kích hoạt có thể cài đặt, thì bạn có thể dùng thông tin này để kiểm soát quyền truy cập vào các phần mã mà người dùng thiếu sự cho phép cần thiết. Ngoài ra, tiện ích bổ sung này có thể yêu cầu người dùng mở URL cho hộp thoại uỷ 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ạiNội dung mô tả
authModeAuthModechế độ uỷ quyền mà thông tin uỷ quyền được yêu cầu; 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ế độ uỷ quyền nào khác yêu cầu người dùng cấp quyền

Cầu thủ trả bóng

AuthorizationInfo – đố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 đưa vào 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. Đưa các phạm vi https://www.googleapis.com/auth/userinfo.email hoặc https://www.googleapis.com/auth/userinfo.profile vào để trả về thông tin bổ sung về người dùng trong mã thông báo.

Mã thông báo giá trị 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ừ đó. 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ơ trên Google của người dùng hiệu quả. 

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);
Hãy xem tài liệu về 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ề.

Cầu thủ trả bóng

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

getInstallationSource()

Trả về một 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ó tự cài đặt tập lệnh đó thông qua Cửa hàng Chrome trực tuyến hay không hoặc liệu quản trị viên miền có cài đặt tập lệnh đó cho tất cả người dùng hay không).

Cầu thủ trả bóng

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 đủ để cấp quyền cho một API khác của Google thường yêu cầu luồng OAuth riêng (như Bộ chọn của Google), thì tập lệnh có thể bỏ qua lời nhắc cấp quyền thứ hai bằng cách truyề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 vài phút); tập lệnh sẽ xử lý các lỗi uỷ quyền và gọi phương thức này để nhận mã thông báo mới khi cần.

Mã thông báo mà phương thức này trả về chỉ bao gồm các phạm vi mà tập lệnh hiện cần. Những phạm vi đã được tập lệnh cho phép trước đó nhưng không còn được 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 những phạm vi mà tập lệnh yêu cầu, bạn có thể chỉ định các phạm vi đó trong tệp kê khai của tập lệnh.

Cầu thủ trả bóng

String – Chuỗi đại diện của mã thông báo OAuth 2.0.

getProjectTriggers()

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

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

Cầu thủ trả bóng

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

Ủy quyền

Tập lệnh sử dụng phương thức này cần được uỷ quyền với 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 để lấy 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ã này ở tất cả những nơi trước đây khoá dự án đã được cung cấp.

Cầu thủ trả bóng

String – Mã dự án 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 một ứng dụng web. 

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

Cầu thủ trả bóng

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 một ứng dụng web.

getUserTriggers(document)

Lấy tất cả các điều kiện 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 này hoặc tiện ích bổ sung này. Bạn không thể dùng phương pháp này để xem các trình kích hoạt được đính kèm với các 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ạiNội dung mô 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.

Cầu thủ trả bóng

Trigger[] – Mảng các điều kiện kích hoạt do người dùng này sở hữu trong tài liệu được chỉ định.

Ủy quyền

Tập lệnh sử dụng phương thức này cần được uỷ quyền với 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 điều kiện kích hoạt có thể cài đặt do người dùng này sở hữu ở dạng nhất định, chỉ dành cho tập lệnh này hoặc tiện ích bổ sung. Bạn không thể dùng phương pháp này để xem các trình kích hoạt được đính kèm với các 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ạiNội dung mô 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.

Cầu thủ trả bóng

Trigger[] – Mảng các điều kiện kích hoạt do người dùng này sở hữu ở dạng được chỉ định.

Ủy quyền

Tập lệnh sử dụng phương thức này cần được uỷ quyền với 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 điều kiện kích hoạt có thể cài đặt do người dùng này sở hữu trong bảng tính nhất định, chỉ dành cho tập lệnh này hoặc tiện ích bổ sung này. Bạn không thể dùng phương pháp này để xem các trình kích hoạt được đính kèm với các 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ạiNội dung mô tả
spreadsheetSpreadsheetTệp Google Trang tính có thể chứa các trình kích hoạt có thể cài đặt.

Cầu thủ trả bóng

Trigger[] – Một mảng các điều kiện kích hoạt do người dùng này sở hữu trong bảng tính được cung cấp.

Ủy quyền

Tập lệnh sử dụng phương thức này cần được uỷ quyền với một hoặc nhiều phạm vi sau:

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

invalidateAuth()

Vô hiệu hoá lệnh uỷ quyền mà người dùng có hiệu lực 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 cho các hàm được gắn thẻ là uỷ quyền một lần. Vì 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 đã có được uỷ quyền, nên nếu sau đó bạn muốn thực hiện một hành động, bạn phải thu hồi mọi quyền của tập lệnh để người dùng có thể xem lại hộp thoại uỷ quyền. 

ScriptApp.invalidateAuth();

Gửi

Error – khi vô hiệu hoá không thành công

newStateToken()

Tạo trình tạo cho mã thông báo trạng thái có thể 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 quy trình OAuth2, mã thông báo state được chuyển trực tiếp đến điểm cuối uỷ quyền (không phải là một phần của URL gọi lại), sau đó điểm cuối uỷ quyền sẽ truyền mã này 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 uỷ 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 cho phép và trang uỷ quyền OAuth2 sẽ chuyển hướng người dùng trở 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 gửi tới /usercallback. Lệnh chuyển hướng này sẽ gọi phương thức do StateTokenBuilder.withMethod(method) chỉ định.

Cầu thủ trả bóng

StateTokenBuilder – Một đối tượng dùng để tiếp tục quá trình tạo mã thông báo trạng thái.

newTrigger(functionName)

Bắt đầu quá 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ạiNội dung mô tả
functionNameStringHàm gọi khi trình kích hoạt kích hoạt. Bạn có thể sử dụng hàm trong các thư viện đi kèm, chẳng hạn như Library.libFunction1.

Cầu thủ trả bóng

TriggerBuilder – Một đối tượng dùng để tiếp tục quá trình tạo trình kích hoạt.

Ủy quyền

Tập lệnh sử dụng phương thức này cần được uỷ quyền với 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