Class ScriptApp

ScriptApp

Dostęp do publikowania skryptów i aktywatorów oraz możliwość manipulowania nimi. Ta klasa umożliwia użytkownikom tworzenie wywołań skryptu i kontrolowanie publikowania skryptu jako usługi.

Właściwości

Właściwość	Typ	Opis
AuthMode	AuthMode	Wyliczenie, które określa kategorie autoryzowanych usług, które Apps Script może wykonywać za pomocą funkcji wywoływanej przez wyzwalacz.
AuthorizationStatus	AuthorizationStatus	Wyliczenie określające stan autoryzacji skryptu.
EventType	EventType	Wyliczenie oznaczające typ wywołanego zdarzenia.
InstallationSource	InstallationSource	Wyliczenie określające, w jaki sposób skrypt został zainstalowany u użytkownika jako dodatek.
TriggerSource	TriggerSource	Wyliczenie oznaczające źródło zdarzenia, które powoduje uruchomienie reguły.
WeekDay	Weekday	Wyliczenie reprezentujące dni tygodnia.

Metody

Metoda	Zwracany typ	Krótki opis
deleteTrigger(trigger)	void	Usuwa podany wyzwalacz, aby nie był już uruchamiany.
getAuthorizationInfo(authMode)	AuthorizationInfo	Zwraca obiekt, który sprawdza, czy użytkownik przyznał autoryzację dla wszystkich wymagań skryptu.
getAuthorizationInfo(authMode, oAuthScopes)	AuthorizationInfo	Pobiera obiekt, który sprawdza, czy użytkownik przyznał autoryzację w przypadku żądanych zakresów.
getIdentityToken()	String|null	Pobiera token tożsamości OpenID Connect dla efektywnego użytkownika, jeśli przyznano zakres openid.
getInstallationSource()	InstallationSource	Zwraca wartość wyliczeniową, która wskazuje, w jaki sposób skrypt został zainstalowany jako dodatek dla bieżącego użytkownika (np. czy użytkownik zainstalował go osobiście w Chrome Web Store, czy administrator domeny zainstalował go dla wszystkich użytkowników).
getOAuthToken()	String	Pobiera token dostępu OAuth 2.0 dla użytkownika.
getProjectTriggers()	Trigger[]	Pobiera wszystkie wyzwalacze, które można zainstalować, powiązane z bieżącym projektem i bieżącym użytkownikiem.
getScriptId()	String	Pobiera unikalny identyfikator projektu skryptu.
getService()	Service	Zwraca obiekt używany do kontrolowania publikowania skryptu jako aplikacji internetowej.
getUserTriggers(document)	Trigger[]	Pobiera wszystkie wyzwalacze z możliwością zainstalowania należące do tego użytkownika w danym dokumencie, tylko dla tego skryptu lub dodatku.
getUserTriggers(form)	Trigger[]	Pobiera wszystkie instalowalne wyzwalacze należące do tego użytkownika w danym formularzu, tylko dla tego skryptu lub dodatku.
getUserTriggers(spreadsheet)	Trigger[]	Pobiera wszystkie wyzwalacze z możliwością zainstalowania należące do tego użytkownika w danym arkuszu kalkulacyjnym, tylko dla tego skryptu lub dodatku.
invalidateAuth()	void	Unieważnia autoryzację, którą użytkownik ma do wykonania bieżącego skryptu.
newStateToken()	StateTokenBuilder	Tworzy narzędzie do tworzenia tokena stanu, którego można używać w interfejsie API opartym na wywołaniach zwrotnych (np. w przepływie OAuth).
newTrigger(functionName)	TriggerBuilder	Rozpoczyna proces tworzenia aktywatora, który można zainstalować i który po uruchomieniu wywołuje daną funkcję.
requireAllScopes(authMode)	void	Sprawdza, czy użytkownik wyraził zgodę na wszystkie zakresy, o które prosi skrypt.
requireScopes(authMode, oAuthScopes)	void	Sprawdza, czy użytkownik wyraził zgodę na żądane zakresy.

Wycofane metody

Metoda	Zwracany typ	Krótki opis
getProjectKey()	String	Pobiera klucz projektu bieżącego skryptu.
getScriptTriggers()	Trigger[]	Pobiera wszystkie wyzwalacze, które można zainstalować, powiązane z bieżącym projektem i bieżącym użytkownikiem.

Szczegółowa dokumentacja

deleteTrigger(trigger)

Usuwa podany wyzwalacz, aby nie był już uruchamiany.

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

Parametry

Nazwa	Typ	Opis
trigger	Trigger	Aktywator do usunięcia.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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

---

getAuthorizationInfo(authMode)

Zwraca obiekt, który sprawdza, czy użytkownik przyznał autoryzację dla wszystkich wymagań skryptu. Obiekt zawiera też adres URL autoryzacji, który umożliwia użytkownikom przyznanie tych uprawnień, jeśli któreś z wymagań skryptu nie są autoryzowane.

Niektóre skrypty mogą być uruchamiane bez zgody użytkownika na wszystkie wymagane zakresy używane przez skrypt. Informacje w tym obiekcie umożliwiają kontrolowanie dostępu do sekcji kodu, które wymagają określonych zakresów, oraz żądanie autoryzacji tych zakresów w przypadku kolejnych wykonań.

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

Parametry

Nazwa	Typ	Opis
authMode	AuthMode	Tryb autoryzacji, dla którego wymagane są informacje o autoryzacji. W prawie wszystkich przypadkach wartość authMode powinna wynosić ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL), ponieważ żaden inny tryb autoryzacji nie wymaga od użytkowników przyznania autoryzacji.

Powrót

AuthorizationInfo – obiekt, który może zawierać informacje o stanie autoryzacji użytkownika.

---

getAuthorizationInfo(authMode, oAuthScopes)

Pobiera obiekt, który sprawdza, czy użytkownik przyznał autoryzację w przypadku żądanych zakresów. Obiekt zawiera też adres URL autoryzacji, który umożliwia użytkownikom przyznanie tych uprawnień, jeśli którykolwiek z żądanych zakresów nie jest autoryzowany.

Niektóre skrypty mogą być uruchamiane bez zgody użytkownika na wszystkie wymagane zakresy używane przez skrypt. Informacje w tym obiekcie umożliwiają kontrolowanie dostępu do sekcji kodu, które wymagają określonych zakresów, oraz żądanie autoryzacji tych zakresów w przypadku kolejnych wykonań. Zakresy, które są nieprawidłowe lub nie są wymagane przez skrypt, powodują błąd.

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

Parametry

Nazwa	Typ	Opis
authMode	AuthMode	Tryb autoryzacji, dla którego wymagane są informacje o autoryzacji. W prawie wszystkich przypadkach wartość parametru authMode powinna wynosić ScriptApp.AuthMode.FULL, ponieważ żaden inny tryb autoryzacji nie wymaga od użytkowników przyznania autoryzacji.
oAuthScopes	String[]	Zakresy OAuth, dla których żądane są informacje o autoryzacji.

Powrót

AuthorizationInfo – obiekt, który zawiera informacje o stanie autoryzacji użytkownika i adres URL autoryzacji w przypadku braku niektórych zgód.

---

getIdentityToken()

Pobiera token tożsamości OpenID Connect dla efektywnego użytkownika, jeśli przyznano zakres openid. Ten zakres nie jest domyślnie uwzględniany. Aby go zażądać, musisz dodać go jako jawny zakres w pliku manifestu. Aby zwrócić w tokenie dodatkowe informacje o użytkowniku, uwzględnij zakresy https://www.googleapis.com/auth/userinfo.email lub https://www.googleapis.com/auth/userinfo.profile.

Zwrócony token identyfikatora to zakodowany token sieciowy JSON (JWT), który należy zdekodować, aby wyodrębnić z niego informacje. Poniższy przykład pokazuje, jak zdekodować token i wyodrębnić identyfikator profilu Google użytkownika.

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);

Pełną listę zwracanych pól (deklaracji) znajdziesz w dokumentacji OpenID Connect.

Powrót

String|null – token tożsamości, jeśli jest dostępny; w przeciwnym razie null.

---

getInstallationSource()

Zwraca wartość wyliczeniową, która wskazuje, w jaki sposób skrypt został zainstalowany jako dodatek dla bieżącego użytkownika (np. czy użytkownik zainstalował go osobiście w Chrome Web Store, czy administrator domeny zainstalował go dla wszystkich użytkowników).

Powrót

InstallationSource – źródło instalacji.

---

getOAuthToken()

Pobiera token dostępu OAuth 2.0 dla użytkownika. Jeśli zakresy protokołu OAuth skryptu są wystarczające do autoryzacji innego interfejsu API Google, który zwykle wymaga własnego przepływu protokołu OAuth (np. Google Picker), skrypty mogą pominąć drugi monit o autoryzację, przekazując zamiast niego ten token. Token wygasa po pewnym czasie (co najmniej po kilku minutach). Skrypty powinny obsługiwać błędy autoryzacji i w razie potrzeby wywoływać tę metodę, aby uzyskać nowy token.

Token zwracany przez tę metodę zawiera tylko zakresy, których skrypt obecnie potrzebuje. Zakresy, które były wcześniej autoryzowane, ale nie są już używane przez skrypt, nie są uwzględniane w zwracanym tokenie. Jeśli potrzebne są dodatkowe zakresy OAuth poza tymi, których wymaga sam skrypt, można je określić w pliku manifestu skryptu.

Możesz użyć tej metody do wywoływania interfejsów API Google, których Apps Script nie obsługuje bezpośrednio. Przekaż zwrócony token w nagłówku „Authorization” żądania HTTP za pomocą UrlFetchApp.fetch(url, params).

const url = 'https://www.googleapis.com/drive/v3/files';
const method = 'GET';
const headers = {
  Authorization: 'Bearer ' + ScriptApp.getOAuthToken(),
};
const response = UrlFetchApp.fetch(url, {
  method,
  headers,
});

Powrót

String – ciąg znaków reprezentujący token OAuth 2.0.

---

getProjectTriggers()

Pobiera wszystkie wyzwalacze, które można zainstalować, powiązane z bieżącym projektem i bieżącym użytkownikiem.

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

Powrót

Trigger[] – tablica wyzwalaczy bieżącego użytkownika powiązanych z tym projektem.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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

---

getScriptId()

Pobiera unikalny identyfikator projektu skryptu. Jest to preferowana metoda uzyskiwania unikalnego identyfikatora projektu skryptu w porównaniu z getProjectKey(). Ten identyfikator można używać we wszystkich miejscach, w których wcześniej podawano klucz projektu.

Powrót

String – identyfikator projektu skryptu.

---

getService()

Zwraca obiekt używany do kontrolowania publikowania skryptu jako aplikacji internetowej.

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

Powrót

Service – obiekt używany do obserwowania i kontrolowania publikowania skryptu jako aplikacji internetowej.

---

getUserTriggers(document)

Pobiera wszystkie wyzwalacze z możliwością zainstalowania należące do tego użytkownika w danym dokumencie, tylko dla tego skryptu lub dodatku. Tej metody nie można używać do wyświetlania wyzwalaczy dołączonych do innych skryptów.

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

Parametry

Nazwa	Typ	Opis
document	Document	Plik Dokumentów Google, który może zawierać wywoływacze instalowane.

Powrót

Trigger[] – tablica wyzwalaczy należących do tego użytkownika w danym dokumencie.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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

---

getUserTriggers(form)

Pobiera wszystkie instalowalne wyzwalacze należące do tego użytkownika w danym formularzu, tylko dla tego skryptu lub dodatku. Nie można jej użyć do wyświetlania wyzwalaczy dołączonych do innych skryptów.

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

Parametry

Nazwa	Typ	Opis
form	Form	Plik Formularzy Google, który może zawierać wywoływacze instalowane.

Powrót

Trigger[] – tablica aktywatorów należących do tego użytkownika w danym formularzu.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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

---

getUserTriggers(spreadsheet)

Pobiera wszystkie wyzwalacze z możliwością zainstalowania należące do tego użytkownika w danym arkuszu kalkulacyjnym, tylko dla tego skryptu lub dodatku. Nie można jej użyć do wyświetlania wyzwalaczy dołączonych do innych skryptów.

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

Parametry

Nazwa	Typ	Opis
spreadsheet	Spreadsheet	Plik Arkuszy Google, który może zawierać instalowane wyzwalacze.

Powrót

Trigger[] – tablica wyzwalaczy należących do tego użytkownika w danym arkuszu kalkulacyjnym.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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

---

invalidateAuth()

Unieważnia autoryzację, którą użytkownik ma do wykonania bieżącego skryptu. Służy do unieważniania uprawnień bieżącego skryptu. Jest to szczególnie przydatne w przypadku funkcji oznaczonych jako autoryzacja jednorazowa. Funkcje jednorazowej autoryzacji można wywołać tylko podczas pierwszego uruchomienia skryptu po uzyskaniu autoryzacji. Jeśli chcesz wykonać działanie później, musisz cofnąć wszelkie uprawnienia skryptu, aby użytkownik mógł ponownie zobaczyć okno autoryzacji.

ScriptApp.invalidateAuth();

Rzuty

Error – gdy unieważnienie się nie powiedzie

---

newStateToken()

Tworzy narzędzie do tworzenia tokena stanu, którego można używać w interfejsie API opartym na wywołaniach zwrotnych (np. w przepływie 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.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const stateToken = ScriptApp.newStateToken()
                         .withMethod(callbackFunction)
                         .withTimeout(120)
                         .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

W większości procesów OAuth2 token state jest przekazywany bezpośrednio do punktu końcowego autoryzacji (nie jako część adresu URL wywołania zwrotnego), a punkt końcowy autoryzacji przekazuje go następnie jako część adresu URL wywołania zwrotnego.

Na przykład:

• Skrypt przekierowuje użytkownika na adres URL autoryzacji 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
• Użytkownik klika „Autoryzuj”, a strona autoryzacji OAuth2 przekierowuje go z powrotem do https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
• Powyższe przekierowanie (z powrotem do http://script.google.com/...) powoduje, że przeglądarka wysyła żądanie do /usercallback, co wywołuje metodę określoną przez StateTokenBuilder.withMethod(method).

Powrót

StateTokenBuilder – obiekt używany do kontynuowania procesu tworzenia tokena stanu.

---

newTrigger(functionName)

Rozpoczyna proces tworzenia aktywatora, który można zainstalować i który po uruchomieniu wywołuje daną funkcję.

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

Zanim utworzysz wyzwalacz, sprawdź, czy powiązana z nim funkcja ma wszystkie niezbędne uprawnienia OAuth.

Parametry

Nazwa	Typ	Opis
functionName	String	Funkcja, która ma być wywoływana po uruchomieniu aktywatora. Możesz używać funkcji z dołączonych bibliotek, np. Library.libFunction1.

Powrót

TriggerBuilder – obiekt używany do kontynuowania procesu tworzenia reguły.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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

---

requireAllScopes(authMode)

Sprawdza, czy użytkownik wyraził zgodę na wszystkie zakresy, o które prosi skrypt. Użyj tej metody, jeśli przepływ wykonania zależy od wszystkich zakresów, o które prosi skrypt. Jeśli brakuje jakichkolwiek zgód, ta metoda kończy bieżące wykonanie i wyświetla prośbę o autoryzację, aby poprosić o brakujące zgody.

Ta metoda działa tylko wtedy, gdy użytkownicy uruchamiają skrypt z platformy, która obsługuje szczegółową zgodę, np. z IDE Apps Script. Gdy skrypt jest uruchamiany bez zgody użytkownika w nieobsługiwanym interfejsie, np. w dodatku do Google Workspace, na początku wykonywania skryptu wyświetla się prośba o autoryzację, która obejmuje wszystkie zakresy.

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

Parametry

Nazwa	Typ	Opis
authMode	AuthMode	Tryb autoryzacji, w przypadku którego należy ocenić zakresy skryptu. W większości przypadków wartość authMode powinna wynosić ScriptApp.AuthMode.FULL, ponieważ żaden inny tryb autoryzacji nie wymaga od użytkowników przyznania autoryzacji.

---

requireScopes(authMode, oAuthScopes)

Sprawdza, czy użytkownik wyraził zgodę na żądane zakresy. Użyj tej metody, jeśli przepływ wykonania zależy od co najmniej jednej usługi. Jeśli brakuje którejkolwiek z określonych zgód, ta metoda kończy bieżące wykonanie i wyświetla prośbę o autoryzację, aby uzyskać brakujące zgody. Zakresy, które są nieprawidłowe lub nie są wymagane przez skrypt, powodują błąd.

Ta metoda działa tylko wtedy, gdy użytkownicy uruchamiają skrypt z platformy, która obsługuje szczegółową zgodę, np. z IDE Apps Script. Gdy skrypt jest uruchamiany bez zgody użytkownika w nieobsługiwanym interfejsie, np. w dodatku do Google Workspace, na początku wykonywania skryptu wyświetla się prośba o autoryzację, która obejmuje wszystkie zakresy.

ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);

Parametry

Nazwa	Typ	Opis
authMode	AuthMode	Tryb autoryzacji, w którym należy ocenić zakresy, o które prosisz. W prawie wszystkich przypadkach wartość authMode powinna wynosić ScriptApp.AuthMode.FULL, ponieważ żaden inny tryb autoryzacji nie wymaga od użytkowników przyznania autoryzacji.
oAuthScopes	String[]	Zakresy OAuth wymagane do ukończenia danego procesu wykonania.

Wycofane metody

getProjectKey()

Wycofano. Zamiast niej używaj zasady getScriptId().

Pobiera klucz projektu bieżącego skryptu. Klucz projektu to unikalny identyfikator skryptów, który służy do tworzenia adresu URL wywołania zwrotnego używanego w połączeniu z newStateToken().

Jeśli funkcja jest wywoływana w bibliotece, zwraca klucz projektu najbardziej zewnętrznego skryptu, który jest wykonywany.

Powrót

String – klucz projektu bieżącego skryptu.

---

getScriptTriggers()

Wycofano. Ta funkcja została wycofana i nie należy jej używać w nowych skryptach.

Pobiera wszystkie wyzwalacze, które można zainstalować, powiązane z bieżącym projektem i bieżącym użytkownikiem.

Logger.log(
    `Current script has ${ScriptApp.getScriptTriggers().length} triggers.`,
);

Powrót

Trigger[] – tablica wyzwalaczy bieżącego użytkownika powiązanych z tym projektem.

Autoryzacja

Skrypty korzystające z tej metody wymagają autoryzacji z użyciem co najmniej jednego z tych zakresów:

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