Class ScriptApp

MetinUygulama

Komut dosyası yayınlama ve tetikleyicilere erişme ve bunları değiştirme. Bu sınıf, kullanıcıların komut dosyası tetikleyicileri oluşturmasına ve komut dosyasının hizmet olarak yayınlanmasını kontrol etmesine olanak tanır.

Özellikler

MülkTürAçıklama
AuthModeAuthModeApps Script'in tetiklenmiş bir işlev aracılığıyla hangi yetkili hizmet kategorilerini çalıştırabileceğini tanımlayan bir listeleme.
AuthorizationStatusAuthorizationStatusBir komut dosyasının yetkilendirme durumunu belirten bir listeleme.
EventTypeEventTypeTetiklenen etkinliğin türünü belirten bir liste.
InstallationSourceInstallationSourceKomut dosyasının kullanıcıya eklenti olarak nasıl yüklendiğini belirten bir listeleme.
TriggerSourceTriggerSourceTetikleyicinin etkinleştirilmesine neden olan etkinliğin kaynağını belirten bir listeleme.
WeekDayWeekdayHaftanın günlerini temsil eden bir liste.

Yöntemler

YöntemDönüş türüKısa açıklama
deleteTrigger(trigger)voidBelirtilen tetikleyiciyi kaldırarak artık çalışmasını engeller.
getAuthorizationInfo(authMode)AuthorizationInfoKullanıcının tüm komut dosyası koşulları için yetki verip vermediğini kontrol eden bir nesne alır.
getAuthorizationInfo(authMode, oAuthScopes)AuthorizationInfoKullanıcının istenen kapsamlar için yetki verip vermediğini kontrol eden bir nesne alır.
getIdentityToken()Stringopenid kapsamı verilmişse etkili kullanıcı için bir OpenID Connect kimlik jetonu alır.
getInstallationSource()InstallationSourceKomut dosyasının mevcut kullanıcı için eklenti olarak nasıl yüklendiğini belirten bir enum değeri döndürür (örneğin, kullanıcının Chrome Web Mağazası üzerinden kişisel olarak yükleyip yüklemediğini veya bir alan yöneticisinin tüm kullanıcılar için yükleyip yüklemediğini).
getOAuthToken()StringEtkili kullanıcı için OAuth 2.0 erişim jetonunu alır.
getProjectTriggers()Trigger[]Mevcut proje ve mevcut kullanıcıyla ilişkili tüm yüklenebilir tetikleyicileri alır.
getScriptId()StringKomut dosyası projesinin benzersiz kimliğini alır.
getService()ServiceKomut dosyasının web uygulaması olarak yayınlanmasını kontrol etmek için kullanılan bir nesne alır.
getUserTriggers(document)Trigger[]Yalnızca bu komut dosyası veya eklenti için, belirli bir dokümanda bu kullanıcıya ait tüm yüklenebilir tetikleyicileri alır.
getUserTriggers(form)Trigger[]Yalnızca bu komut dosyası veya eklenti için, belirli bir formda bu kullanıcıya ait tüm yüklenebilir tetikleyicileri alır.
getUserTriggers(spreadsheet)Trigger[]Yalnızca bu komut dosyası veya eklenti için, belirli bir e-tabloda bu kullanıcıya ait tüm yüklenebilir tetikleyicileri alır.
invalidateAuth()voidGeçerli komut dosyasını yürütmek için etkili kullanıcının sahip olduğu yetkiyi geçersiz kılar.
newStateToken()StateTokenBuilderGeri çağırma API'sinde (OAuth akışı gibi) kullanılabilecek bir durum jetonu için bir oluşturucu oluşturur.
newTrigger(functionName)TriggerBuilderTetiklendiğinde belirli bir işlevi çağıran, yüklenebilir bir tetikleyici oluşturma işlemini başlatır.
requireAllScopes(authMode)voidKullanıcının komut dosyası tarafından istenen tüm kapsamlar için izin verip vermediğini doğrular.
requireScopes(authMode, oAuthScopes)voidKullanıcının istenen kapsamlar için izin verip vermediğini doğrular.

Ayrıntılı dokümanlar

deleteTrigger(trigger)

Belirtilen tetikleyiciyi kaldırarak artık çalışmasını engeller. 

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

Parametreler

AdTürAçıklama
triggerTriggerSililecek tetikleyici.

Yetkilendirme

Bu yöntemi kullanan komut dosyalarının aşağıdaki kapsamlardan bir veya daha fazlası için yetkilendirilmesi gerekir:

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

getAuthorizationInfo(authMode)

Kullanıcının tüm komut dosyası koşulları için yetki verip vermediğini kontrol eden bir nesne alır. Nesne, komut dosyası koşullarından herhangi birinin yetkilendirilmemesi durumunda kullanıcıların bu izinleri vermesi için bir yetkilendirme URL'si de sağlar.

Bazı komut dosyası yürütmeleri, komut dosyası tarafından kullanılan tüm gerekli kapsamlar için kullanıcının izni olmadan başlayabilir. Bu nesnedeki bilgiler, belirli kapsamlar gerektiren kod bölümlerine erişimi kontrol etmenize ve sonraki yürütmeler için bu kapsamların yetkilendirmesini istemenize olanak tanır. 

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

Parametreler

AdTürAçıklama
authModeAuthModeYetkilendirme bilgilerinin istendiği yetkilendirme modu. Başka hiçbir yetkilendirme modu kullanıcıların yetki vermesini gerektirmediğinden, neredeyse tüm durumlarda authMode için değer ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL) olmalıdır.

Return

AuthorizationInfo: Kullanıcının yetkilendirme durumu hakkında bilgi sağlayabilen bir nesne.

getAuthorizationInfo(authMode, oAuthScopes)

Kullanıcının istenen kapsamlar için yetki verip vermediğini kontrol eden bir nesne alır. Nesne, istenen kapsamlardan herhangi biri yetkilendirilmemişse kullanıcıların bu izinleri vermesi için bir yetkilendirme URL'si de sağlar.

Bazı komut dosyası yürütmeleri, komut dosyası tarafından kullanılan tüm gerekli kapsamlar için kullanıcının izni olmadan başlayabilir. Bu nesnedeki bilgiler, belirli kapsamlar gerektiren kod bölümlerine erişimi kontrol etmenize ve sonraki yürütmeler için bu kapsamların yetkilendirilmesini istemenize olanak tanır. Geçersiz olan veya komut dosyası tarafından zorunludur olmayan kapsamlar hataya neden olur. 

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();

Parametreler

AdTürAçıklama
authModeAuthModeYetkilendirme bilgilerinin istendiği yetkilendirme modu. Diğer hiçbir yetkilendirme modu kullanıcıların yetki vermesini gerektirmediğinden, neredeyse tüm durumlarda authMode için değer ScriptApp.AuthMode.FULL olmalıdır.
oAuthScopesString[]Yetkilendirme bilgilerinin istendiği OAuth kapsamları.

Return

AuthorizationInfo: Kullanıcının yetkilendirme durumu ve bazı izinlerin eksik olması durumunda bir yetkilendirme URL'si hakkında bilgi sağlayan bir nesne.

getIdentityToken()

openid kapsamı verilmişse etkili kullanıcı için bir OpenID Connect kimlik jetonu alır. Bu kapsam varsayılan olarak dahil edilmez ve isteğinde bulunmak için manifest dosyasına açık kapsam olarak eklemeniz gerekir. Jetonda ek kullanıcı bilgileri döndürmek için https://www.googleapis.com/auth/userinfo.email veya https://www.googleapis.com/auth/userinfo.profile kapsamlarını ekleyin.

Döndürülen kimlik jetonu, kodlanmış bir JSON Web Jetonu (JWT)'dur ve bu jetondan bilgi alabilmek için kodu çözülmelidir. Aşağıdaki örneklerde, jetonun kodunu çözme ve etkin kullanıcının Google profil kimliğini ayıklama işlemleri gösterilmektedir. 

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}`);
 İade edilen alanların (iddiaların) tam listesi için OpenID Connect dokümanlarına bakın.

Return

String: Varsa kimlik jetonu, aksi takdirde null.

getInstallationSource()

Komut dosyasının mevcut kullanıcı için eklenti olarak nasıl yüklendiğini belirten bir enum değeri döndürür (örneğin, kullanıcının Chrome Web Mağazası üzerinden kişisel olarak yükleyip yüklemediğini veya bir alan yöneticisinin tüm kullanıcılar için yükleyip yüklemediğini).

Return

InstallationSource: Yüklemenin kaynağı.

getOAuthToken()

Etkili kullanıcı için OAuth 2.0 erişim jetonunu alır. Komut dosyasının OAuth kapsamları, normalde kendi OAuth akışı gerektiren başka bir Google API'sini (ör. Google Seçici) yetkilendirmek için yeterliyse komut dosyaları, bu jetonu aktararak ikinci yetkilendirme isteminden geçebilir. Jetonun süresi bir süre sonra (en az birkaç dakika) dolar. Komut dosyaları, yetkilendirme hatalarını ele almalı ve gerektiğinde yeni bir jeton almak için bu yöntemi çağırmalıdır.

Bu yöntem tarafından döndürülen jeton yalnızca komut dosyasının şu anda ihtiyaç duyduğu kapsamları içerir. Daha önce yetkilendirilmiş ancak artık komut dosyası tarafından kullanılmayan kapsamlar döndürülen jetona dahil edilmez. Komut dosyasının gerektirdiğinin dışında ek OAuth kapsamları gerekiyorsa bunlar komut dosyasının manifest dosyasında belirtilebilir.

Return

String: OAuth 2.0 jetonunun dize gösterimi.

getProjectTriggers()

Mevcut proje ve mevcut kullanıcıyla ilişkili tüm yüklenebilir tetikleyicileri alır. 

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

Return

Trigger[]: Geçerli kullanıcının bu projeyle ilişkili tetikleyicilerinin dizisi.

Yetkilendirme

Bu yöntemi kullanan komut dosyalarının aşağıdaki kapsamlardan bir veya daha fazlası için yetkilendirilmesi gerekir:

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

getScriptId()

Komut dosyası projesinin benzersiz kimliğini alır. Bu, getProjectKey() yerine komut dosyası projesinin benzersiz tanımlayıcısını almak için tercih edilen yöntemdir. Bu kimlik, daha önce proje anahtarının sağlandığı tüm yerlerde kullanılabilir.

Return

String: Komut dosyası projesinin kimliği.

getService()

Komut dosyasının web uygulaması olarak yayınlanmasını kontrol etmek için kullanılan bir nesne alır. 

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

Return

Service: Komut dosyasının web uygulaması olarak yayınlanmasını gözlemlemek ve kontrol etmek için kullanılan bir nesnedir.

getUserTriggers(document)

Yalnızca bu komut dosyası veya eklenti için, belirli bir dokümanda bu kullanıcıya ait tüm yüklenebilir tetikleyicileri alır. Bu yöntem, diğer komut dosyalarına eklenmiş tetikleyicileri görmek için kullanılamaz. 

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());

Parametreler

AdTürAçıklama
documentDocumentYüklenebilir tetikleyiciler içerebilecek bir Google Dokümanlar dosyası.

Return

Trigger[]: Belirtilen dokümanda bu kullanıcıya ait tetikleyici dizisi.

Yetkilendirme

Bu yöntemi kullanan komut dosyalarının aşağıdaki kapsamlardan bir veya daha fazlası için yetkilendirilmesi gerekir:

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

getUserTriggers(form)

Yalnızca bu komut dosyası veya eklenti için, belirli bir formda bu kullanıcıya ait tüm yüklenebilir tetikleyicileri alır. Bu yöntem, diğer komut dosyalarına eklenmiş tetikleyicileri görmek için kullanılamaz. 

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());

Parametreler

AdTürAçıklama
formFormYüklenebilir tetikleyiciler içerebilecek bir Google Formlar dosyası.

Return

Trigger[]: Belirtilen formda bu kullanıcıya ait tetikleyiciler dizisi.

Yetkilendirme

Bu yöntemi kullanan komut dosyalarının aşağıdaki kapsamlardan bir veya daha fazlası için yetkilendirilmesi gerekir:

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

getUserTriggers(spreadsheet)

Yalnızca bu komut dosyası veya eklenti için, belirli bir e-tabloda bu kullanıcıya ait tüm yüklenebilir tetikleyicileri alır. Bu yöntem, diğer komut dosyalarına eklenmiş tetikleyicileri görmek için kullanılamaz. 

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());

Parametreler

AdTürAçıklama
spreadsheetSpreadsheetYüklenebilir tetikleyiciler içerebilen bir Google E-Tablolar dosyası.

Return

Trigger[]: Belirtilen e-tabloda bu kullanıcıya ait tetikleyici dizisi.

Yetkilendirme

Bu yöntemi kullanan komut dosyalarının aşağıdaki kapsamlardan bir veya daha fazlası için yetkilendirilmesi gerekir:

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

invalidateAuth()

Geçerli komut dosyasını yürütmek için etkili kullanıcının sahip olduğu yetkiyi geçersiz kılar. Mevcut komut dosyasının tüm izinlerini geçersiz kılmak için kullanılır. Bu, özellikle tek seferlik yetkilendirme olarak etiketlenen işlevler için yararlıdır. Tek seferlik yetkilendirme işlevleri yalnızca komut dosyası yetki aldıktan sonra ilk çalıştırma sırasında çağrılabildiğinden, daha sonra bir işlem yapmak isterseniz kullanıcının yetkilendirme iletişim kutusunu tekrar görebilmesi için komut dosyasının sahip olduğu tüm yetkileri iptal etmeniz gerekir. 

ScriptApp.invalidateAuth();

Atışlar

Error: Geçersiz kılma işlemi başarısız olduğunda

newStateToken()

Geri çağırma API'sinde (OAuth akışı gibi) kullanılabilecek bir durum jetonu için bir oluşturucu oluşturur. 

// 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;
}

Çoğu OAuth2 akışında, state jetonu doğrudan yetkilendirme uç noktasına (geri çağırma URL'sinin parçası olarak değil) iletilir ve yetkilendirme uç noktası da jetonu geri çağırma URL'sinin parçası olarak iletir.

Örneğin:

  • Komut dosyası, kullanıcıyı OAuth2 yetkilendirme URL'sine yönlendirir: 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
  • Kullanıcı yetkilendir'i tıkladığında OAuth2 yetkilendirme sayfası kullanıcıyı tekrar şu sayfaya yönlendirir: https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • Yukarıdaki yönlendirme (http://script.google.com/... adresine geri dönme), /usercallback adresine tarayıcı isteğinin gönderilmesine neden olur. Bu istek, StateTokenBuilder.withMethod(method) tarafından belirtilen yöntemi çağırır.

Return

StateTokenBuilder: Durum jetonu oluşturma sürecine devam etmek için kullanılan bir nesne.

newTrigger(functionName)

Tetiklendiğinde belirli bir işlevi çağıran, yüklenebilir bir tetikleyici oluşturma işlemini başlatır. 

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

Parametreler

AdTürAçıklama
functionNameStringTetikleyici etkinleştirildiğinde çağrılacak işlev. Library.libFunction1 gibi dahil edilen kitaplıklardaki işlevleri kullanabilirsiniz.

Return

TriggerBuilder: Tetikleyici oluşturma sürecine devam etmek için kullanılan bir nesne.

Yetkilendirme

Bu yöntemi kullanan komut dosyalarının aşağıdaki kapsamlardan bir veya daha fazlası için yetkilendirilmesi gerekir:

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

requireAllScopes(authMode)

Kullanıcının komut dosyası tarafından istenen tüm kapsamlar için izin verip vermediğini doğrular. Bir yürütme akışı, komut dosyasının istediği tüm kapsamlara dayanıyorsa bu yöntemi kullanın. Herhangi bir izin eksikse bu yöntem mevcut yürütmeyi sonlandırır ve eksik izinleri istemek için bir yetkilendirme istemi gösterir.

Bu yöntem yalnızca kullanıcılar komut dosyasını ayrıntılı izinleri destekleyen bir yüzeyden (ör. Apps Komut Dosyası IDE'sinden) çalıştırdığında çalışır. Komut dosyası, Google Workspace eklentisi gibi desteklenmeyen bir yüzeyden eksik izinlerle çalıştırıldığında, tüm kapsamları istemek için yürütmenin başında bir yetkilendirme istemi oluşturur. 

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

Parametreler

AdTürAçıklama
authModeAuthModeKomut dosyası kapsamlarının değerlendirilmesi gereken yetkilendirme modu. Başka hiçbir yetkilendirme modu kullanıcıların yetki vermesini gerektirmediğinden, neredeyse tüm durumlarda authMode değeri ScriptApp.AuthMode.FULL olmalıdır.

requireScopes(authMode, oAuthScopes)

Kullanıcının istenen kapsamlar için izin verip vermediğini doğrular. Bir yürütme akışı bir veya daha fazla hizmete dayanıyorsa bu yöntemi kullanın. Belirtilen izinlerden herhangi biri eksikse bu yöntem mevcut yürütmeyi sonlandırır ve eksik izinleri istemek için bir yetkilendirme istemi gösterir. Geçersiz olan veya komut dosyası tarafından zorunludur olmayan kapsamlar hataya neden olur.

Bu yöntem yalnızca kullanıcılar komut dosyasını ayrıntılı izinleri destekleyen bir yüzeyden (ör. Apps Komut Dosyası IDE'sinden) çalıştırdığında çalışır. Komut dosyası, Google Workspace eklentisi gibi desteklenmeyen bir yüzeyden eksik izinlerle çalıştırıldığında, tüm kapsamları istemek için yürütmenin başında bir yetkilendirme istemi oluşturur. 

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

Parametreler

AdTürAçıklama
authModeAuthModeİstenen kapsamların değerlendirilmesi gereken yetkilendirme modu. Diğer hiçbir yetkilendirme modu kullanıcıların yetki vermesini gerektirmediğinden, neredeyse tüm durumlarda authMode için değer ScriptApp.AuthMode.FULL olmalıdır.
oAuthScopesString[]Belirtilen yürütme akışını tamamlamak için gereken OAuth kapsamları.

Kullanımdan kaldırılan yöntemler