Bu sayfa, Cloud Translation API ile çevrilmiştir.

HTML Hizmeti: Sunucu İşlevleri ile İletişim

google.script.run eşzamansız bir HTML hizmeti sayfalarının sunucu tarafında çağrı yapmasına olanak tanıyan istemci taraflı JavaScript API Apps Komut Dosyası işlevleri. Aşağıdaki örnekte, projenizin en temel işlevi / google.script.run — sunucuda bir işlev çağırma JavaScript'ten Search Ads 360'a aktarılır.

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 içerir, ancak günlükleri görüntülerseniz sunucu işlevinin doSomething() arandı.

Sunucu tarafı işlevlere yapılan istemci tarafı çağrılar eşzamansızdır: tarayıcıdan sunucunun doSomething() işlevini çalıştırmasını istediğinde tarayıcı çalışmaya devam eder kodda hemen sonraki satıra geçer. Bu, sunucu işlevi çağrılarının beklediğiniz sırada yürütülemeyeceği anlamına gelir. Bir iki fonksiyon çağrısını aynı anda çalıştırmazsanız, hangi işlevin koşmaya başlayın; sonuç, sayfayı her yükleyişinizde farklılık gösterebilir. Böyle bir durumda başarı işleyiciler ve başarısızlık işleyiciler kodunuzun akışını kontrol etmenize yardımcı olur.

google.script.run API, sunucu işlevlerine 10 eşzamanlı çağrıya izin verir. 10 çağrı devam ederken 11. çağrıyı yaparsanız sunucu işlevi, 10 yerden biri boşalana kadar ertelenir. Pratikte ise çok seyrek çoğu tarayıcı zaten sınırlı olduğundan, bu kısıtlamayı aynı sunucuya 10'dan küçük bir sayıda eşzamanlı gönderilen isteklerin sayısı. Örneğin, Firefox'ta bu sınır 6'dır. Çoğu tarayıcı da benzer şekilde aşırı miktarda gecikme sunucu isteklerinden biri mevcut isteklerden biri tamamlanana kadar bekletilir.

Parametreler ve döndürülen değerler

İstemciden parametrelerle bir sunucu işlevi çağırabilirsiniz. Benzer şekilde, bir sunucu işlevi, başarı işleyicisine iletilen bir parametre olarak istemciye bir değer döndürebilir.

Yasal parametreler ve döndürülen değerler Number gibi temel JavaScript öğeleridir Boolean, String veya null öğelerinin yanı sıra ilkel öğelerden, nesnelerden ve dizilerden oluşur. Sayfa içinde bir form öğesi parametre olarak da geçerlidir, ancak işlevin tek parametresi olmalıdır ve değer döndürülmesi açısından yasal değildir. Bir Date, Function, form veya yasaklı başka bir türe ek olarak DOM öğesi, dahil değildir. Oluşturulan nesneler döngüsel başvurular da başarısız olur ve dizilerdeki tanımlanmamış alanlar null

Sunucuya iletilen bir nesnenin, orijinalin bir kopyası haline geleceğini unutmayın. sunucu işlevi bir nesneyi alır ve özelliklerini değiştirir. müşteri bu durumdan etkilenmez.

Başarı işleyiciler

İstemci taraflı kod, sunucu beklemeden sonraki satıra devam ettiği için tamamlamak için withSuccessHandler(function) sunucu bir kullanıcı tarafından çalıştırıldığında çalıştırılacak bir istemci tarafı geri çağırma işlevi belirtmenize olanak tanır. yanıt verir. Sunucu işlevi bir değer döndürürse API, bu değeri parametre olarak yeni işleve dönelim.

Aşağıdaki örnekte, sunucu yanıt verdiğinde bir tarayıcı uyarısı gösterilmektedir. Sunucu tarafı işlevi Gmail hesabınıza eriştiği için bu kod örneğinin yetkilendirme gerektirdiğini unutmayın. Komut dosyasını yetkilendirmenin en basit yolu işlemi yapmadan önce komut dosyası düzenleyiciden getUnreadEmails() işlevini manuel olarak bir kez kullanın. sayfayı yükleyin. Alternatif olarak, web uygulamasını dağıtırken "web uygulamasına erişen kullanıcı" olarak çalıştırmayı 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>

Başarısızlık işleyicileri

Sunucunun yanıt vermemesi veya bir hata vermesi durumunda withFailureHandler(function) bir başarı işleyici yerine bir hata işleyici belirtmenize olanak tanır. Error nesne (varsa) bağımsız değişken olarak iletildi.

Varsayılan olarak, hata işleyici belirtmezseniz hatalar JavaScript konsoluna kaydedilir. Bunu geçersiz kılmak için withFailureHandler(null) numaralı telefonu arayın veya hiçbir şey yapmayan bir hata işleyici.

Hata işleyicilerin söz dizimi, başarılı işleyicilerin söz dizimiyle neredeyse aynıdır, çünkü yardımcı olur.

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

withUserObject(object) işlevini çağırarak, ikinci parametre olarak işleyiciye iletilecek bir nesne belirterek aynı başarı veya başarısızlık işleyicisini sunucuya yapılan birden fazla çağrı için yeniden kullanabilirsiniz. Bu “kullanıcı nesnesi”, User sınıfı — şuraya yanıt vermenize olanak tanır: istemcinin sunucuyla iletişim kurduğu bağlam. Kullanıcı nesneleri genellikle bunlar; işlevler, DOM öğeler, vb., parametrelere ve dönüş değerlerine ilişkin kısıtlamalar olmadan kullanır. Bununla birlikte, kullanıcı nesneleri new operatörü.

Bu örnekte, iki düğmeden birini tıkladığınızda o düğme değerini sunucudan alır ve diğer düğmeyi değiştirmeden bırakır, bir başarı işleyiciyi paylaşın. onclick işleyicisinde this anahtar kelimesi button'nin kendisi anlamına gelir.

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

Parametre olarak form öğesi içeren bir sunucu işlevini çağırırsanız form olarak alan adlarını anahtar, alan değerlerini değer olarak içeren tek bir nesne haline gelir. Dosya girişi alanlarının içeriği hariç tüm değerler dize olarak dönüştürülür. Dosya girişi alanlarının içeriği Blob nesnesi olur.

Bu örnekte, dosya giriş alanı da dahil olmak üzere bir form yeniden yüklenmeden işlenir. Sayfa; dosyayı Google Drive'a yükler ve ardından dosyanın dosyası olarak ekleyebilirsiniz. onsubmit işleyicisinde this anahtar kelimesi biçimin kendisini ifade eder. Sayfadaki tüm formları yüklediğinizde, preventFormSubmit tarafından devre dışı bırakılan varsayılan gönderme işlemi. Bu, istisna durumunda sayfanın 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. Şu durumda: veya komut dosyası çalıştırıcısına başarı işleyici, hata işleyici veya kullanıcı nesnesi ekleyebilir. mevcut koşucuyu değiştirmediğinden emin olun. bunun yerine yeni bir komut dosyası çalıştırıcısı yardımcı olabilir.

withSuccessHandler(), withFailureHandler() ve withUserObject() öğelerini dilediğiniz şekilde ve sırada kullanabilirsiniz. Ayrıca, Ayarlanmış değere sahip bir komut dosyası çalıştırıcısındaki işlevlerde değişiklik yapma. Yeni değeri, ö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şleyiciler:

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

Adları alt çizgiyle biten sunucu işlevleri gizli olarak kabul edilir. Bu işlevler google.script tarafından çağrılamaz ve adları hiçbir zaman gönderir. Bu nedenle, sunucuda gizli tutulması gereken uygulama ayrıntılarını gizlemek için bunları kullanabilirsiniz. google.script adlı kullanıcı da şu anda şunları göremiyor: kitaplıklar içindeki işlevler ve en üst düzeyinde belirtilen değerlerdir.

Bu örnekte, getBankBalance() işlevi istemcide kullanılabilir kod; kaynak kodunuzu inceleyen bir kullanıcı, onu arama. Ancak deepSecret_() ve obj.objectMethod() işlevleri istemci tarafından tamamen görünmez.

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ı Google Workspace yeniden boyutlandırılıyor

Google Dokümanlar, 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 öğesini kullanın. yöntemler setWidth(width) ve setHeight(height)). İletişim kutuları yeniden boyutlandırıldığında üst pencerede yeniden ortalanmaz ve kenar çubukları yeniden boyutlandırılamaz.

Google Workspaceiçindeki iletişim kutuları ve kenar çubukları kapatılıyor

Bir Google Dokümanlar, E-Tablolar veya Google Dokümanlar'da iletişim kutusu ya da kenar çubuğu Formlar, window.close() öğesini çağırarak arayüzü kapatamazsınız. Bunun yerine aramalı google.script.host.close(). Örnek için HTML'yi kullanıcı arayüzü olarak sunma Google Workspace başlıklı bölüme bakın.

Google Workspaceiçinde tarayıcı odağı taşınıyor

Kullanıcının tarayıcısında odağı bir iletişim kutusundan veya kenar çubuğundan tekrar eski ana ekrana taşımak için Google Dokümanlar, E-Tablolar veya Formlar düzenleyicisini kullanmak için google.script.host.editor.focus(). Bu yöntem özellikle Belge hizmeti yöntemleri Document.setCursor(position) ve Document.setSelection(range).