Düzenleyici eklentisi yetkilendirmesi

Komut dosyası projesi, kullanıcılar uygulamayı kullanmaya çalıştığında ihtiyaç duyduğu eksik izinleri istediği için birçok Apps Script tabanlı uygulamanın yetkilendirmesi kolaydır.

Düzenleyici eklentileri için yetkilendirme modeli, birkaç nedenden dolayı daha karmaşıktır:

• Bir kullanıcı dosya oluşturduğunda, yüklediği tüm eklentiler henüz yetkilendirilmemiş olsa bile Uzantılar menüsünde listelenir.

• Bu eklentiler, Google Drive'daki ortak çalışanlarla paylaşılabilen dosyalarda çalışır. Düzenleyen eklentisi yüklü olmayan ortak çalışanlar, dosyayı oluşturan kullanıcının kullandığı dokümanlarda bu eklentiyi görür.

• Düzenleyici eklentileri, bir doküman açıldığında işlevlerini otomatik olarak çalıştırır.onOpen()

Kullanıcı verilerini korumak için, bazı hizmetlerin onOpen() tarafından kullanılamamasını sağlayan yetkilendirme modları uygulanır. Bu kılavuz, kodunuzun neleri ne zaman yapabileceğini anlamanıza yardımcı olabilir.

Yetkilendirme modeli

Düzenleyici eklentisinin yetkilendirme modu, eklentiyi kimin kullandığına (eklentiyi yükleyen kullanıcı veya ortak çalışan) bağlı olarak değişen durumuna bağlıdır.

Düzenleyici eklentisi durumları

Uzantılar menüsündeki düzenleyici eklentileri yüklenmiş, etkinleştirilmiş veya her ikisi olmalıdır.

• Bir eklenti, belirli bir kullanıcı veya yöneticisi tarafından Google Workspace Marketplace'ten alındıktan ve Google verilerine erişmesi için yetkilendirildikten sonra yüklenir.
• Bir eklenti, doküman, form, sunu veya e-tabloda herhangi bir kullanıcı tarafından kullanıldığında etkinleştirilir.
• Bir dosyada ortak çalışan kullanıcılardan biri eklenti kullandığında eklenti, ilgili kullanıcı için yüklenir ve dosya için etkinleştirilir.

Aşağıdaki tabloda, yüklü ve etkinleştirilmiş arasındaki farklar özetlenmektedir. Bir komut dosyasını eklenti olarak test ettiğinizde testi bu iki durumdan birinde veya her ikisinde de çalıştırabileceğinizi unutmayın.

Yetkilendirme modları

Düzenleyici eklentisinin onOpen() işlevi, kullanıcı bir doküman, form, sunu veya e-tablo açtığında otomatik olarak çalışır. Apps Script, kullanıcı verilerini korumak için onOpen() işlevinin yapabileceklerini kısıtlar. Düzenleyici eklentisi durumu, onOpen() işlevinin hangi yetkilendirme modunda çalışacağını belirler.

Dosya, form, sunu veya e-tabloda bir Düzenleyici eklentisi etkinleştirildiyse onOpen(), AuthMode.LIMITED'te çalışır. Eklenti etkin değilse ve yalnızca yüklüyse onOpen(), AuthMode.NONE'te çalışır.

AuthMode.NONE'te, kullanıcı özel işlevleri tıklayarak veya çalıştırarak eklentiyle etkileşime girene kadar eklenti belirli hizmetleri çalıştıramaz. Eklentiniz bu hizmetleri onOpen(), onInstall() veya genel kapsamda kullanmaya çalışırsa izinler geçersiz olur ve menü doldurma gibi diğer çağrılar durdurulur. Yalnızca yardım seçeneği desteklenir.

Kısıtlanmış hizmet çağrıları çalıştırmak için AuthMode.FULL yetkilendirme modunu kullanmanız gerekir. Menü seçeneğini tıklama gibi kullanıcı etkileşimi işlevleri yalnızca bu modda çalışır. Kod AuthMode.FULL modunda çalıştırıldıktan sonra eklenti, kullanıcının yetkilendirdiği tüm kapsamları kullanabilir.

Apps Komut Dosyası, yetkilendirme modunu Apps Komut Dosyası etkinlik parametresinin authMode mülkü olarak e ile iletir; e.authMode değerinin Apps Komut Dosyası ScriptApp.AuthMode enum'unda bir sabit değere karşılık gelir.

Yetkilendirme modları, komut dosyası düzenleyicisinden, menü öğesinden veya Apps Komut Dosyası google.script.run çağrısından çalıştırma dahil olmak üzere tüm Apps Komut Dosyası yürütme yöntemleri için geçerlidir. Ancak e.authMode özelliği yalnızca komut dosyası onOpen(), onEdit() veya onInstall() gibi bir tetikleyici sonucunda çalıştırılıyorsa denetlenir. Google E-Tablolar'daki özel işlevler, LIMITED'a benzer ancak biraz farklı kısıtlamalara sahip olan kendi yetkilendirme modlarını (AuthMode.CUSTOM_FUNCTION) kullanır. Diğer tüm durumlarda, komut dosyaları aşağıdaki tabloda açıklandığı gibi AuthMode.FULL olarak çalışır.

Düzenleyici eklentisinin yetkilendirme yaşam döngüsü

Mevcut kullanıcı için yüklenen veya mevcut dosyada etkinleştirilen eklentiler, ilgili dosya, form, sunu veya e-tablo açıldığında yüklenir. Eklenti, Uzantılar menüsünde listelenir ve onInstall(), onOpen() ve onEdit() basit tetikleyicilerini dinlemeye başlar. Kullanıcı bir Uzantılar menüsü öğesini tıklarsa ilgili uzantı çalıştırılır.

Düzenleyici eklentisi yüklü olmalıdır.

Düzenleyici eklentisi mağazadan yüklendiğinde onInstall() işlevi AuthMode.FULL içinde çalışır. Bu yetkilendirme modunda eklenti, karmaşık bir kurulum rutini çalıştırabilir. Doküman, form, sunu veya e-tablo zaten açık olduğundan ve onOpen() işleviniz çalışmadığından menü öğeleri oluşturmak için onInstall() işlevini de kullanmanız gerekir. Aşağıdaki örnekte, onInstall() işlevinden onOpen() işlevinin nasıl çağrılacağı gösterilmektedir:

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

Düzenleyici eklentisi açılır

Bir doküman, form, sunu veya e-tablo açıldığında, mevcut kullanıcının yüklediği veya ortak çalışanın dosyada etkinleştirdiği tüm Düzenleyici eklentileri yüklenir ve bu eklentilerin her birinin onOpen() işlevleri çağrılır. onOpen()'ın çalıştığı yetkilendirme modu, eklentinin yüklü veya etkin olup olmadığına bağlıdır.

Bir eklenti yalnızca temel bir menü oluşturuyorsa modun önemi yoktur. Aşağıdaki örnekte temel bir onOpen() işlevi gösterilmektedir:

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

Depolanan Apps Script mülklerine dayalı dinamik menü öğeleri eklemek, mevcut dosyanın içeriğini okumak veya diğer gelişmiş görevleri gerçekleştirmek için yetkilendirme modunu tanımlamanız ve uygun şekilde kullanmanız gerekir.

Aşağıdaki örnekte, işlemini yetkilendirme moduna göre değiştiren gelişmiş bir onOpen() işlevi gösterilmektedir:

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

Eklentilerin AuthMode.LIMITED içinde çalışırken kenar çubukları veya iletişim kutuları açamayacağını unutmayın. Yan panelleri ve iletişim kutularını açmak için menü öğelerini kullanabilirsiniz. Bunlar AuthMode.FULL'da çalışır.

Kullanıcı Düzenleyici eklentisini çalıştırdığında

Kullanıcı bir Uzantılar menü öğesini tıkladığında Apps Script öncelikle kullanıcının eklentiyi yükleyip yüklemediğini kontrol eder ve yüklemediyse yüklemesini ister. Kullanıcı eklentiye yetki verdiyse komut dosyası, AuthMode.FULL'teki menü öğesine karşılık gelen işlevi çalıştırır. Eklenti, daha önce etkinleştirilmediyse dokümanda, formda, sunu veya e-tabloda etkinleştirilir.

Eklenti menüsünün oluşturulmamasıyla ilgili sorunları giderme

Kodunuz yetkilendirme modlarını doğru şekilde yönetmiyorsa eklenti menünüz oluşturulmayabilir. Örneğin:

• Bir eklenti, mevcut yetkilendirme modu tarafından desteklenmeyen bir Apps Komut Dosyası hizmetini çalıştırmaya çalışıyor.

• Bir eklenti, kullanıcı onunla etkileşime geçmeden önce bir hizmet çağrısı çalıştırmaya çalışır.

AuthMode.NONE'te izin hatalarına neden olan bir hizmet çağrısını kaldırmak veya yeniden düzenlemek için aşağıdaki işlemleri deneyin:

1. Eklentinizin Apps Komut Dosyası projesini açıp onOpen() işlevini bulun.
2. onOpen() işlevinde, Apps Komut Dosyası hizmetlerine veya bunlarla ilişkili nesnelere (ör. PropertiesService, SpreadsheetApp veya GmailApp) dair bahsedilme olup olmadığını arayın.
3. Bir hizmet, kullanıcı arayüzü öğeleri oluşturmak dışında bir şey için kullanılıyorsa kaldırın veya yorum bloğuna alın. Yalnızca şu yöntemleri bırakın: .getUi(), .createMenu(), .addItem() ve .addToUi(). Ayrıca, bir işlevin dışındaki tüm hizmetleri bulup kaldırın.
4. Önceki adımda yorumlanmış veya kaldırılmış kod satırlarını içerebilecek işlevleri (özellikle de ürettikleri bilgileri kullanan işlevleri) belirleyin ve hizmet çağrılarını bunlara ihtiyaç duyan işlevlere taşıyın. Önceki adımlarda yapılan değişikliklere uyum sağlamak için kod tabanınızı yeniden düzenleyin veya yeniden yazın.

5. Kodu kaydedin ve test dağıtımı oluşturun.

   Test dağıtımı oluştururken Yapılandırma alanının Mevcut kullanıcı için yüklü olduğundan ve Yapılandırma kutusunun altındaki metinde AuthMode.None'de test et ifadesinin bulunduğundan emin olun.

6. Test dağıtımını başlatın ve Uzantılar menüsünü açın.

7. Tüm menü öğeleri gösteriliyorsa sorun düzeltilmiştir. Yalnızca Yardım menüsünü görüyorsanız 1. adıma geri dönün. Bir servis aramasını kaçırmış olabilirsiniz.

İlgili konular

• Web Uygulamaları
• Eklenti türleri
• Düzenleyici eklentisini test etme