Reguły dla dodatków do edytora

Reguły Apps Script powodują, że określona funkcja skryptu (funkcja reguły) jest wykonywana za każdym razem, gdy wystąpi określone zdarzenie. Wyzwalacze mogą być aktywowane tylko przez określone zdarzenia, a każda aplikacja Google Workspace obsługuje inny zestaw zdarzeń.

Gdy reguła zostanie uruchomiona, zostanie utworzony obiekt zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o wydarzeniach. Informacje w strukturze obiektu zdarzenia są uporządkowane inaczej w zależności od typu reguły.

Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do funkcji trigger. Funkcja wyzwalająca to funkcja wywołania zwrotnego, którą musisz zaimplementować samodzielnie, aby wykonać odpowiednie działania w odpowiedzi na zdarzenie. Na przykład w dodatku do edytora użyjesz reguły, aby utworzyć elementy menu dodatku po otwarciu dokumentu. W takim przypadku możesz zaimplementować funkcję onOpen(e), aby utworzyć elementy menu, których potrzebuje dodatek, używając ewentualnie danych z obiektu zdarzenia.

Na tej stronie znajdziesz wskazówki dotyczące korzystania z reguł w projektach rozszerzeń w Edytorze.

Typy reguł dodatku do edytora

W dodatkach do edytora możesz używać większości typów ogólnych aktywatorów dostępnych w projektach Apps Script, w tym prostych aktywatorów i większości aktywowanych za pomocą instalacji. Dokładny zestaw dostępnych typów zdarzeń zależy od rozszerzanej aplikacji.

W tabeli poniżej znajdziesz typy prostych i instalowalnych reguł, których mogą używać dodatki do edytora, oraz linki do odpowiednich obiektów zdarzeń:

Zdarzenie Obiekt zdarzenia Proste reguły Wyzwalacze do zainstalowania
Otwórz
Otwiera plik edytora.		 Docs onOpen event object
Forms onOpen event object
Sheets onOpen event object
Slides onOpen event object 		Dokumenty
Formularze*
Arkusze
Prezentacje

function onOpen(e)

 Dokumenty
Formularze
Arkusze
Zainstaluj
Dodatek jest zainstalowany.		 Obiekt zdarzenia onInstall Dokumenty
Formularze
Arkusze
Prezentacje

function onInstall(e)
Edytuj
Zmienia się zawartość komórki arkusza kalkulacyjnego.		 Sheets onEdit event object Arkusze

function onEdit(e)

 Arkusze
Zmiana
treści w arkuszu lub ich formatowania.		 Zdarzenie onChange obiektu Sheets Arkusze
Form-submit
Formularz Google został przesłany.		 Objects of the Forms submit form event
Objects of the Sheets submit form event 		Formularze
Arkusze
Czasowy (zegar)
Wyzwalacz uruchamia się w określonym czasie lub w określonych odstępach czasu.		 Obiekt zdarzenia oparte na czasie Dokumenty
Formularze
Arkusze
Prezentacje

* Zdarzenie otwarcia formularza Google nie występuje, gdy użytkownik otwiera formularz, aby na niego odpowiedzieć, ale gdy edytor otwiera formularz, aby go zmodyfikować.

Proste aktywatory w dodatkach

Proste wyzwalacze korzystają z zestawu zarezerwowanych nazw funkcji, nie mogą korzystać z usług wymagających autoryzacji i są automatycznie włączone do użycia. W niektórych przypadkach proste zdarzenie aktywatora może być obsługiwane przez aktywator z możliwością zainstalowania.

Możesz dodać do dodatku prosty wyzwalacz, po prostu implementując funkcję o jednym z tych nazwanych rezerwatów:

  • onOpen(e) wykonuje się, gdy użytkownik otworzy dokument, arkusz kalkulacyjny lub prezentację. onOpen(e) może się też wykonywać, gdy otworzysz formularz w edytorze (ale nie wtedy, gdy odpowiadasz na formularz). Jest wykonywane tylko wtedy, gdy użytkownik ma uprawnienia do edycji danego pliku. Jest ono najczęściej używane do tworzenia pozycji menu.
  • onInstall(e) jest wykonywane, gdy użytkownik zainstaluje dodatek. Zwykle onInstall(e) służy tylko do wywołania onOpen(e). Dzięki temu menu dodatku pojawiają się natychmiast po zainstalowaniu bez konieczności odświeżania strony przez użytkownika.
  • onEdit(e) jest wykonywane, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten reguła nie jest uruchamiany w odpowiedzi na przenoszenie komórek, formatowanie ani inne zmiany, które nie zmieniają wartości komórek.

Ograniczenia

Proste wyzwalacze w dodatkach podlegają tym samym ograniczeniami, które obowiązują w przypadku prostych wyzwalaczy w innych projektach Apps Script. Podczas projektowania dodatków należy zwrócić szczególną uwagę na te ograniczenia:

  • Proste reguły nie są wykonywane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). Zapobiega to wypełnianiu menu dodatków.
  • W pewnych okolicznościach rozszerzenia edytora uruchamiają proste reguły onOpen(e) i onEdit(e) w trybie bez autoryzacji. W tym trybie występują pewne dodatkowe komplikacje, opisane w modelu autoryzacji dodatku.
  • Proste reguły nie mogą korzystać z usług ani wykonywać innych działań, które wymagają autoryzacji, z wyjątkiem przypadków opisanych w modelu autoryzacji dodatku.
  • Proste reguły nie mogą działać dłużej niż 30 sekund. Pamiętaj, aby zminimalizować ilość przetwarzania wykonywanego w ramach prostej funkcji wyzwalacza.
  • Proste aktywatory podlegają limitom aktywatorów Apps Script.

Instalowane reguły w dodatkach

Dodatki mogą programowo tworzyć i modyfikować instalowane reguły za pomocą usługi Apps Script Script. Instalowane reguły dodatków nie mogą być tworzone ręcznie. W przeciwieństwie do prostych reguł reguły instalowane mogą korzystać z usług wymagających autoryzacji.

Instalowane w dodatkach wyzwalacze nie wysyłają e-maili z informacją o błędach, ponieważ w większości przypadków użytkownik nie jest w stanie rozwiązać problemu. Dlatego w miarę możliwości należy zaprojektować dodatek tak, aby w sytuacji błędu umiarkowanie reagował na błędy w imieniu użytkownika.

Dodatki mogą używać tych instalowanych wyzwalaczy:

  • Otwieranie – instalowalne wyzwalacze są wykonywane, gdy użytkownik otworzy dokument, arkusz kalkulacyjny lub formularz w edytorze (ale nie podczas wypełniania formularza).
  • Edytuj – instalowane wyzwalacze są wykonywane, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten reguła nie jest uruchamiana w odpowiedzi na formatowanie ani inne zmiany, które nie zmieniają wartości komórek.
  • Zmiany – uruchamiane, gdy użytkownik wprowadzi jakąkolwiek zmianę w arkuszu kalkulacyjnym, w tym zmiany formatowania i modyfikacje samego arkusza (np. dodanie wiersza).

  • Przekazanie formularza – uruchamiane są one, gdy odpowiedź w formularzu Google zostanie przesłana.

  • Wyzwalacze czasowe (nazywane też wyzwalaczami zegara) działają w określonym czasie lub wielokrotnie w regularnych odstępach czasu.

Autoryzowanie aktywatorów instalowanych

Jeśli deweloper zaktualizuje dodatek, aby używać nowych usług wymagających dodatkowej autoryzacji, użytkownicy zostaną poproszeni o ponowne autoryzowanie dodatku przy następnym jego użyciu.

Jednak dodatki, które korzystają z wyzwalaczy, napotykają na specjalne problemy z autoryzacją. Wyobraź sobie dodatek, który używającego elementu wyzwalającego do monitorowania przesyłań formularzy. Twórca formularza może autoryzować dodatek przy pierwszym użyciu, a potem pozwolić mu działać przez miesiące lub lata bez ponownego otwierania formularza. Jeśli deweloper dodatku zaktualizuje go, aby używać nowych usług, które wymagają dodatkowego upoważnienia, twórca formularza nigdy nie zobaczy okna dialogowego ponownego upoważnienia, ponieważ nigdy nie otworzy ponownie formularza, a dodatek przestanie działać.

W przeciwieństwie do wyzwalaczy w zwykłych projektach Apps Script wyzwalacze w dodatkach nadal działają, nawet jeśli wymagają ponownego autoryzowania. Skrypt nadal się jednak nie powiedzie, jeśli napotka wiersz kodu, który wymaga autoryzacji, której nie ma. Aby uniknąć takiej sytuacji, deweloperzy mogą używać metody ScriptApp.getAuthorizationInfo(), aby ograniczać dostęp do części kodu, które uległy zmianie między opublikowanymi wersjami dodatku.

Poniżej znajdziesz przykład zalecanej struktury do użycia w funkcjach reguł, aby uniknąć problemów z autoryzacją. Przykładowa funkcja reguły reaguje na zdarzenie przesłania formularza w dodatku do Arkuszy Google i w razie potrzeby ponownego autoryzowania wysyła użytkownikowi dodatku e-maila z alertem, korzystając z szablonu HTML.

Code.gs

triggers/form/Code.gs
/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html
<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Ograniczenia

Instalowalne wyzwalacze w dodatkach podlegają tym samym ograniczeniami, które obowiązują w przypadku instalowanych wyzwalaczy w innych projektach Apps Script.

Oprócz tych ograniczeń w przypadku instalowanych w dodatkach wyzwalaczy obowiązują też inne ograniczenia:

  • Każde rozszerzenie może mieć tylko jeden wyzwalacz każdego typu na użytkownika i dokument. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko jeden wyzwalacz edycji, ale w tym samym arkuszu może też mieć wyzwalacz przesyłania formularza lub wyzwalacz czasowy. Inny użytkownik, który ma dostęp do tego samego arkusza kalkulacyjnego, może mieć własny zestaw reguł.
  • Dodatki mogą tworzyć wyzwalacze tylko w pliku, w którym są używane. Oznacza to, że dodatek używany w dokumencie Google A nie może utworzyć czynnika uruchamiającego, który będzie monitorował otwieranie dokumentu Google B.
  • Wyzwalacze czasowe nie mogą działać częściej niż raz na godzinę.
  • Dodatki nie wysyłają automatycznie e-maila do użytkownika, gdy kod uruchamiany przez instalowany przez niego wyzwalacz powoduje wyjątek. Odpowiedzialny za to jest programista, który musi sprawdzić i odpowiednio obsłużyć przypadki niepowodzenia.
  • Reguły w dodatku przestają działać w tych sytuacjach:
    • Jeśli użytkownik odinstaluje dodatek,
    • jeśli dodatek jest wyłączony w dokumencie (jeśli zostanie ponownie włączony, wyzwalacz zacznie działać ponownie);
    • Jeśli deweloper wycofa dodatek lub prześle do sklepu z dodatkami uszkodzoną wersję.
  • Funkcje aktywatora dodatku są wykonywane do momentu, gdy dotrą do kodu, który korzysta z nieautoryzowanej usługi. W tym momencie przestają działać. Jest to możliwe tylko wtedy, gdy dodatek jest opublikowany. Ten sam wyzwalacz w zwykłym projekcie Apps Script lub w nieopublikowanym dodatku nie zostanie w ogóle wykonany, jeśli jakakolwiek część skryptu wymaga autoryzacji.
  • Wyzwalacze do zainstalowania podlegają limitom limitom kvoty w Apps Script.