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'nın en temel işlevi olan 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 işlevi çalıştırmasını istedikten sonra doSomething() 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ı bilemezsiniz. 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ıtlamayı nadiren düşünmeniz gerekir.
Örneğin, Firefox'ta bu 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ğırabilirsiniz. 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ışındaki bir DOM öğesini 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
İstemci tarafı kod, sunucu çağrısının tamamlanmasını beklemeden bir sonraki satıra geçtiğinden withSuccessHandler(function), sunucu yanıt verdiğinde çalıştırılacak bir istemci tarafı geri çağırma işlevi belirtmenize olanak tanır. Sunucu işlevi bir değer döndürürse API, değeri yeni işlevin parametresi olarak iletir.
Aşağıdaki örnekte, sunucu yanıt verdiğinde bir tarayıcı uyarısı gösterilmektedir. Bu kod örneğinin, sunucu tarafı işlevi Gmail hesabınıza eriştiği için yetkilendirme gerektirdiğini unutmayın. Komut dosyasını yetkilendirmenin en basit yolu, sayfayı yüklemeden önce getUnreadEmails() işlevini komut dosyası düzenleyicisinden bir kez manuel olarak çalıştırmaktır. Alternatif olarak, web uygulamasını dağıtırken "web uygulamasına erişen kullanıcı" olarak yürütmeyi seçebilirsiniz. Bu durumda, uygulamayı yüklediğinizde 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 bir hata işleyicisi belirtmenize olanak tanır. Bu durumda, varsa Error nesnesi bağımsız değişken olarak iletilir.
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' will throw 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 kullanabilirsiniz. Bunun için withUserObject(object) çağrısı yaparak işleyiciye ikinci parametre olarak iletilecek bir nesne belirtebilirsiniz.
User sınıfıyla karıştırılmaması gereken bu "kullanıcı nesnesi", istemcinin sunucuyla iletişim kurduğu 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, DOM öğeleri vb. dahil olmak üzere neredeyse her şey olabilirler. Ancak kullanıcı nesneleri, new operatörüyle oluşturulan nesneler olamaz.
Bu örnekte, iki düğmeden birini tıkladığınızda, bir başarı işleyicisi paylaşmalarına rağmen diğer düğme değişmeden kalırken tıklanan düğme sunucudan alınan bir değerle güncellenir. 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'ı "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 kullanabilirsiniz. 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 de çağırabilirsiniz. Yeni değer, önceki değerin üzerine yazılır.
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. Bu nedenle, sunucuda gizli tutulması gereken uygulama ayrıntılarını gizlemek için bunları kullanabilirsiniz. google.script, kitaplıklardaki işlevleri ve 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ı keşfedebilir. 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>Uygulamalardaki iletişim kutularını yeniden boyutlandırma Google Workspace
Google Dokümanlar, E-Tablolar veya Formlar'daki özel iletişim kutularının boyutu, istemci tarafı kodunda google.script.host yöntemleri setWidth(width) veya setHeight(height) çağrılarak değiştirilebilir. (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'da 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() çağırarak arayüzü kapatamazsınız. Bunun yerine google.script.host.close() numaralı telefonu aramanız gerekir.
Örnek için HTML'yi kullanıcı arayüzü olarak sunma bölümüne bakın. Google Workspace
Tarayıcı odağını taşıma Google Workspace
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ğırmanız yeterlidir.
Bu yöntem, özellikle Document service yöntemleri
Document.setCursor(position)
ve
Document.setSelection(range) ile birlikte kullanıldığında faydalıdır.