google.script.run, HTML hizmeti sayfalarının sunucu tarafındaki Apps Komut Dosyası işlevlerini çağıırmasına olanak tanıyan eşzamansız bir istemci tarafı JavaScript API'sidir. Aşağıdaki örnekte, google.script.run öğesinin en temel işlevi (istemci tarafı JavaScript'ten sunucuda bir işlevi çağırma) gösterilmektedir.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function doSomething() {
Logger.log('I was called!');
}Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
google.script.run.doSomething();
</script>
</head>
</html>Bu komut dosyasını bir web uygulaması olarak dağıtıp URL'sini ziyaret ederseniz herhangi bir şey görmezsiniz. Ancak günlükleri görüntülerseniz doSomething sunucu işlevinin çağrıldığını görürsünüz.
Sunucu tarafı işlevlerine yapılan istemci tarafı çağrıları eşzamansızdır: Tarayıcı, sunucudan doSomething işlevini çalıştırmasını istedikten sonra yanıt beklemeden hemen bir sonraki kod satırına geçer. Bu, sunucu işlevi çağrılarının beklediğiniz sırada yürütülmeyebileceği anlamına gelir. Aynı anda iki işlev çağrısı yaparsanız hangi işlevin önce çalışacağını bilmenin bir yolu yoktur. Sonuç, sayfayı her yüklediğinizde farklı olabilir. Bu durumda, başarı işleyicileri ve başarısızlık işleyicileri kodunuzun akışını kontrol etmenize yardımcı olur.
google.script.run API, sunucu işlevlerine 10 eşzamanlı çağrıya izin verir. 10 görüşme devam ederken 11. görüşmeyi yaparsanız 10 görüşmeden biri sona erene kadar sunucu işlevi gecikir. Uygulamada, özellikle çoğu tarayıcı aynı sunucuya yapılan eşzamanlı isteklerin sayısını 10'dan daha düşük bir sayıyla sınırlandırdığı için bu kısıtlama hakkında nadiren düşünmeniz gerekir.
Örneğin, Firefox'ta sınır 6'dır. Çoğu tarayıcı da benzer şekilde, mevcut isteklerden biri tamamlanana kadar fazla sunucu isteklerini geciktirir.
Parametreler ve dönüş değerleri
İstemciden gelen parametrelerle bir sunucu işlevini çağırma. Benzer şekilde, bir sunucu işlevi, başarı işleyicisine iletilen bir parametre olarak istemciye değer döndürebilir.
Geçerli parametreler ve dönüş değerleri; Number, Boolean, String veya null gibi JavaScript temel öğelerinin yanı sıra temel öğeler, nesneler ve dizilerden oluşan JavaScript nesneleri ve dizileridir. Sayfadaki bir form öğesi de parametre olarak geçerlidir ancak işlevin tek parametresi olmalıdır ve dönüş değeri olarak geçerli değildir. Date, Function, form dışında bir DOM öğesi veya nesneler ya da diziler içindeki yasaklanmış türler de dahil olmak üzere yasaklanmış başka bir türü iletmeye çalışırsanız istekler başarısız olur. Dairesel referans oluşturan nesneler de başarısız olur ve dizilerdeki tanımlanmamış alanlar null olur.
Sunucuya iletilen bir nesnenin, orijinal nesnenin kopyası haline geldiğini unutmayın. Bir sunucu işlevi bir nesne alır ve özelliklerini değiştirirse istemcideki özellikler etkilenmez.
Başarı işleyicileri
google.script.run çağrıları eşzamansız olduğundan istemci tarafı kodu, yanıt beklemeksizin bir sonraki satıra geçer. Sunucu yanıt verdiğinde çalışacak bir geri çağırma işlevi belirtmek için withSuccessHandler(function) işlevini kullanın.
Sunucu işlevi bir değer döndürürse API, bu değeri parametre olarak geri çağırma işlevine iletir.
Aşağıdaki örnekte, sunucu yanıt verdiğinde bir tarayıcı uyarısı gösterilmektedir. Bu kod örneği, sunucu tarafı işlevi Gmail hesabınıza eriştiği için yetkilendirme gerektirir. Komut dosyasını yetkilendirmek için sayfayı yüklemeden önce getUnreadEmails işlevini komut dosyası düzenleyicisinden bir kez manuel olarak çalıştırın. Alternatif olarak, web uygulamasını "web uygulamasına erişen kullanıcı" olarak çalışacak şekilde dağıttığınızda, uygulama yüklenirken yetkilendirme istenir.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getUnreadEmails() {
return GmailApp.getInboxUnreadCount();
}Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onSuccess(numUnread) {
var div = document.getElementById('output');
div.innerHTML = 'You have ' + numUnread
+ ' unread messages in your Gmail inbox.';
}
google.script.run.withSuccessHandler(onSuccess)
.getUnreadEmails();
</script>
</head>
<body>
<div id="output"></div>
</body>
</html>Hata işleyiciler
Sunucu yanıt vermezse veya hata verirse,
withFailureHandler(function)
başarı işleyicisi yerine çalıştırılacak bir hata işleyicisi belirtmenize olanak tanır.
Bir hata oluşursa API, Error nesnesini hata işleyiciye bağımsız değişken olarak iletir.
Varsayılan olarak, bir hata işleyici belirtmezseniz hatalar JavaScript konsoluna kaydedilir. Bunu geçersiz kılmak için withFailureHandler(null) işlevini çağırın veya hiçbir şey yapmayan bir hata işleyici sağlayın.
Bu örnekte gösterildiği gibi, hata işleyicilerin söz dizimi başarı işleyicilerle neredeyse aynıdır.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getUnreadEmails() {
// 'got' instead of 'get' throws an error.
return GmailApp.gotInboxUnreadCount();
}Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onFailure(error) {
var div = document.getElementById('output');
div.innerHTML = "ERROR: " + error.message;
}
google.script.run.withFailureHandler(onFailure)
.getUnreadEmails();
</script>
</head>
<body>
<div id="output"></div>
</body>
</html>Kullanıcı nesneleri
Sunucuya yapılan birden fazla çağrı için aynı başarı veya hata işleyicisini yeniden kullanmak üzere, işleyiciye ikinci parametre olarak iletilen bir nesne belirtmek için withUserObject(object) işlevini çağırın.
User sınıfıyla karıştırılmaması gereken bu "kullanıcı nesnesi", istemcinin sunucuyla iletişime geçtiği bağlama yanıt vermenizi sağlar. Kullanıcı nesneleri sunucuya gönderilmediğinden, sunucu çağrıları için parametreler ve dönüş değerleriyle ilgili kısıtlamalar olmadan işlevler ve DOM öğeleri de dahil olmak üzere birçok şey olabilirler. Kullanıcı nesneleri, new operatörüyle oluşturulan nesneler olamaz.
Bu örnekte, iki düğmeden birinin tıklanması, bir başarı işleyicisi paylaşmalarına rağmen diğer düğmeyi değiştirmeden bırakırken bu düğmeyi sunucudan alınan bir değerle günceller. onclick işleyicisinde this anahtar kelimesi button öğesini ifade eder.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getEmail() {
return Session.getActiveUser().getEmail();
}Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function updateButton(email, button) {
button.value = 'Clicked by ' + email;
}
</script>
</head>
<body>
<input type="button" value="Not Clicked"
onclick="google.script.run
.withSuccessHandler(updateButton)
.withUserObject(this)
.getEmail()" />
<input type="button" value="Not Clicked"
onclick="google.script.run
.withSuccessHandler(updateButton)
.withUserObject(this)
.getEmail()" />
</body>
</html>Formlar
Bir sunucu işlevini parametre olarak form öğesiyle çağırırsanız form, alan adları anahtar, alan değerleri ise değer olarak tek bir nesneye dönüşür. Değerler, dosya girişi alanlarının içeriği hariç olmak üzere tümü dizelere dönüştürülür. Dosya girişi alanlarının içeriği Blob nesneleri haline gelir.
Bu örnek, sayfa yeniden yüklenmeden dosya girişi alanı da dahil olmak üzere bir formu işler. Dosyayı Google Drive'a yükler ve ardından istemci tarafı sayfasında dosyanın URL'sini yazdırır. onsubmit işleyicisinde, this anahtar kelimesi formun kendisini ifade eder. Sayfadaki tüm formlar yüklendiğinde varsayılan gönderme işleminin preventFormSubmit tarafından devre dışı bırakıldığını unutmayın. Bu, sayfanın bir istisna durumunda yanlış bir URL'ye yönlendirilmesini önler.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function processForm(formObject) {
var formBlob = formObject.myFile;
var driveFile = DriveApp.createFile(formBlob);
return driveFile.getUrl();
}Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
// Prevent forms from submitting.
function preventFormSubmit() {
var forms = document.querySelectorAll('form');
for (var i = 0; i < forms.length; i++) {
forms[i].addEventListener('submit', function(event) {
event.preventDefault();
});
}
}
window.addEventListener('load', preventFormSubmit);
function handleFormSubmit(formObject) {
google.script.run.withSuccessHandler(updateUrl).processForm(formObject);
}
function updateUrl(url) {
var div = document.getElementById('output');
div.innerHTML = '<a href="' + url + '">Got it!</a>';
}
</script>
</head>
<body>
<form id="myForm" onsubmit="handleFormSubmit(this)">
<input name="myFile" type="file" />
<input type="submit" value="Submit" />
</form>
<div id="output"></div>
</body>
</html>Komut dosyası çalıştırıcıları
google.script.run'yı "komut dosyası çalıştırıcı" için bir oluşturucu olarak düşünebilirsiniz. Bir komut dosyası çalıştırıcıya başarı işleyici, hata işleyici veya kullanıcı nesnesi eklerseniz mevcut çalıştırıcıyı değiştirmezsiniz. Bunun yerine, yeni davranışa sahip yeni bir komut dosyası çalıştırıcı elde edersiniz.
withSuccessHandler, withFailureHandler ve withUserObject öğelerini herhangi bir kombinasyon ve sırada kullanın. Ayrıca, halihazırda bir değer ayarlanmış olan bir komut dosyası çalıştırıcısında değiştirme işlevlerinden herhangi birini çağırın. Yeni değer, önceki değeri geçersiz kılar.
Bu örnek, üç sunucu çağrısının tümü için ortak bir hata işleyici, ancak iki ayrı başarı işleyici ayarlar:
var myRunner = google.script.run.withFailureHandler(onFailure);
var myRunner1 = myRunner.withSuccessHandler(onSuccess);
var myRunner2 = myRunner.withSuccessHandler(onDifferentSuccess);
myRunner1.doSomething();
myRunner1.doSomethingElse();
myRunner2.doSomething();
Özel işlevler
Adı alt çizgiyle biten sunucu işlevleri özel olarak kabul edilir.
Bu işlevler google.script tarafından çağrılamaz ve adları hiçbir zaman istemciye gönderilmez. Bunları, sunucuda gizli tutulması gereken uygulama ayrıntılarını gizlemek için kullanabilirsiniz. google.script ayrıca kitaplıklardaki işlevleri veya komut dosyasının en üst düzeyinde tanımlanmamış işlevleri de göremez.
Bu örnekte, getBankBalance işlevi istemci kodunda kullanılabilir. Kaynak kodunuzu inceleyen bir kullanıcı, siz işlevi çağırmasanız bile adını öğrenebilir. Ancak deepSecret_ ve obj.objectMethod işlevleri istemci için tamamen görünmezdir.
Code.gs
function doGet() {
return HtmlService.createHtmlOutputFromFile('Index');
}
function getBankBalance() {
var email = Session.getActiveUser().getEmail()
return deepSecret_(email);
}
function deepSecret_(email) {
// Do some secret calculations
return email + ' has $1,000,000 in the bank.';
}
var obj = {
objectMethod: function() {
// More secret calculations
}
};Index.html
<!DOCTYPE html>
<html>
<head>
<base target="_top">
<script>
function onSuccess(balance) {
var div = document.getElementById('output');
div.innerHTML = balance;
}
google.script.run.withSuccessHandler(onSuccess)
.getBankBalance();
</script>
</head>
<body>
<div id="output">No result yet...</div>
</body>
</html>Google Workspace uygulamalarındaki iletişim kutularını yeniden boyutlandırma
Google Dokümanlar, Google E-Tablolar veya Formlar'daki özel iletişim kutuları, istemci tarafı kodunda google.script.host yöntemleri setWidth(width) veya setHeight(height) çağrılarak yeniden boyutlandırılabilir. (Bir iletişim kutusunun ilk boyutunu ayarlamak için HtmlOutput
yöntemlerini
setWidth(width)
ve
setHeight(height) kullanın.)
İletişim kutularının yeniden boyutlandırıldığında üst pencerede yeniden ortalanmadığını ve kenar çubuklarının yeniden boyutlandırılamadığını unutmayın.
Google Workspace'te iletişim kutularını ve kenar çubuklarını kapatma
Google Dokümanlar, E-Tablolar veya Formlar'da iletişim kutusu ya da kenar çubuğu göstermek için HTML hizmetini kullanıyorsanız window.close işlevini çağırarak arayüzü kapatamazsınız. Bunun yerine google.script.host.close yöntemini çağırmanız gerekir.
Örnek için HTML'yi Google Workspace kullanıcı arayüzü olarak sunma bölümüne bakın.
Google Workspace'te tarayıcı odağını taşıma
Kullanıcının tarayıcısında odağı bir iletişim kutusundan veya kenar çubuğundan Google Dokümanlar, E-Tablolar ya da Formlar düzenleyicisine geri çevirmek için google.script.host.editor.focus yöntemini çağırın.
Bu yöntem, özellikle Document
service yöntemleri Document.setCursor(position)
ve
Document.setSelection(range) ile birlikte kullanıldığında faydalıdır.