Düzenleyici eklentisi yetkilendirmesi

Birçok Google Apps Komut Dosyası uygulamasının yetkilendirilmesi kolaydır. Komut dosyası projesi, bir kullanıcı komut dosyasını kullanmaya çalıştığında ihtiyaç duyduğu eksik izinleri ister.

Düzenleyici eklentileri için yetkilendirme modeli çeşitli nedenlerle daha karmaşıktır:

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

• Bu eklentiler, Google Drive'da ortak çalışanlarla paylaşılabilen dosyalar üzerinde çalışır. Düzenleyici eklentisi yüklü olmayan ortak çalışanlar, dosyayı oluşturan kişinin kullandığı dokümanlarda eklentiyi görür.

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

Kullanıcı verilerini korumak için bazı hizmetleri onOpen için kullanılamaz hale getiren yetkilendirme modları uygulanır. Bu kılavuzda, kodunuzun ne zaman neler yapabileceği açıklanmaktadır.

Yetkilendirme modeli

Bir Düzenleyici eklentisinin yetkilendirme modu, eklentinin durumuna bağlıdır. Eklentinin durumu ise eklentiyi kimin kullandığına (eklentiyi yükleyen kullanıcı veya bir ortak çalışan) bağlıdır.

Düzenleyici eklentisi durumları

Uzantılar menüsündeki Düzenleyici Eklentileri yüklenir, etkinleştirilir veya her ikisi de yapılır:

• Bir eklenti, Google Workspace Marketplace'ten alınarak veya yönetici tarafından alınarak Google verilerine erişim yetkisi verildikten sonra belirli bir kullanıcı için yüklenir.
• Bir eklenti, doküman, form, sunu veya e-tabloda kullanıldığında etkinleştirilir.
• Bir dosya üzerinde ortak çalışan kullanıcılardan biri eklenti kullandığında eklenti, bu kullanıcı için yüklenir ve dosya için etkinleştirilir.

Aşağıdaki tabloda, yüklü ve etkin arasındaki farklar özetlenmektedir. Bir komut dosyasını eklenti olarak test ederken, testi bu durumlardan birinde veya her ikisinde de çalıştırabilirsiniz.

Yetkilendirme modları

Bir düzenleyici eklentisinin onOpen işlevi, kullanıcı bir dokümanı, formu, sunuyu veya e-tabloyu açtığında otomatik olarak çalışır. Apps Komut Dosyası, kullanıcı verilerini korumak için onOpen işlevinin yapabileceklerini kısıtlar. onOpen işlevinin hangi yetkilendirme modunda çalışacağını, Düzenleyici eklentisinin durumu belirler.

Dosyada, formda, sunuda veya e-tabloda bir Düzenleyici eklentisi etkinleştirilmişse onOpen, AuthMode.LIMITED içinde çalışır. Eklenti etkinleştirilmemişse ve yalnızca yüklenmişse, onOpen, AuthMode.NONE içinde çalışır.

AuthMode.NONE'da, kullanıcı eklentiyle etkileşime girip özel işlevleri tıklayana veya çalıştırana kadar eklenti belirli hizmetleri çalıştıramaz. Eklentiniz bu hizmetleri onOpen, onInstall veya genel kapsamda kullanmaya çalışırsa izinler başarısız olur ve menüleri doldurma gibi diğer çağrılar durur. Yalnızca yardım seçeneği desteklenir.

Kısıtlanmış hizmet çağrılarını ç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, yetkilendirilmiş tüm kapsamları kullanabilir.

Yalnızca yayınlanmış düzenleyici eklentileri AuthMode.NONE içinde olabilir; yayınlanmamış düzenleyici eklentileri AuthMode.LIMITED içinde onOpen olarak çalışır. Ancak, her iki yetkilendirme modunda da amaçlanmıştır. Bunu yapmak için bir Düzenleyici eklentisini test edin.

Apps Komut Dosyası, yetkilendirme modunu Apps Komut Dosyası authMode etkinlik parametresinin e özelliği olarak iletir. e.authMode değeri, Apps Komut Dosyası ScriptApp.AuthMode enum'ındaki bir sabite karşılık gelir.

Yetkilendirme modları, komut dosyası düzenleyiciden, 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ırsa incelenebilir. Google E-Tablolar'daki özel işlevler, AuthMode.CUSTOM_FUNCTION olan kendi yetkilendirme modunu kullanır. Bu mod, LIMITED ile benzerdir ancak biraz farklı kısıtlamalara sahiptir. Diğer tüm durumlarda komut dosyaları, aşağıdaki tabloda açıklandığı gibi AuthMode.FULL içinde çalışır.

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

Eklenti, mevcut kullanıcı için yüklendiğinde veya mevcut dosyada etkinleştirildiğinde, dosya açıldığında doküman, form, sunu ya da e-tablo için yüklenir. Eklenti, Uzantılar menüsünde listelenir ve basit tetikleyicileri (onInstall, onOpen ve onEdit) dinlemeye başlar. Kullanıcı bir Uzantılar menü öğesini tıkladığında çalışır.

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

Mağazadan bir Düzenleyici eklentisi 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 de onInstall kullanmanız gerekir. Aşağıdaki örnekte, onOpen işlevinin onInstall işlevinden 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 ya da herhangi bir ortak çalışanın dosyada etkinleştirdiği her Düzenleyici eklentisi yüklenir ve her birinin onOpen işlevi çağrılır. onOpen çalıştığı yetkilendirme modu, eklentinin yüklü veya etkin olup olmaması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();
}

Kayıtlı Apps Komut Dosyası özelliklerine göre 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 ele almanız gerekir.

Aşağıdaki örnekte, yetkilendirme moduna göre işlemini 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();
}

onOpen işlevi çalıştırıldığında komut dosyasının tamamı yüklenir ve genel ifadeler onOpen ile aynı yetkilendirme modunda çalışır. Yetkilendirme modu genel ifadeleri yasaklıyorsa hem genel ifadeler hem de onOpen çalıştırılamaz. Yayınlanan eklenti, menü öğelerini ekleyemezse hata döndürülüp döndürülmediğini görmek için tarayıcı konsolunu inceleyin. Ardından, onOpen işlevinin veya genel değişkenlerin AuthMode.NONE'te izin verilmeyen hizmetleri çağırıp çağırmadığını görmek için komut dosyanızı inceleyin.

Eklentiler, AuthMode.LIMITED içinde yürütülürken kenar çubuklarını veya iletişim kutularını açamaz. AuthMode.FULL içinde çalıştıkları için kenar çubuklarını ve iletişim kutularını açmak için menü öğelerini kullanabilirsiniz.

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

Kullanıcı bir Uzantılar menü öğesini tıkladığında Apps Komut Dosyası, 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 içindeki menü öğesine karşılık gelen işlevi çalıştırır. Eklenti, dokümanda, formda, sunuda veya e-tabloda etkinleştirilir.

Eklenti menülerinin 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ı hizmeti çalıştırmaya çalışıyor.

• Bir eklenti, kullanıcı etkileşimde bulunmadan önce bir hizmet çağrısı çalıştırmaya çalışır.

AuthMode.NONE'da izin hatalarına neden olan bir servis ç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çın ve onOpen işlevini bulun.
2. onOpen işlevinde Apps Komut Dosyası hizmetlerinden veya bunlarla ilişkili nesnelerden (ör. PropertiesService, SpreadsheetApp veya GmailApp) bahsedilip bahsedilmediğini arayın.
3. Bir hizmet, kullanıcı arayüzü öğeleri oluşturmak dışında bir amaçla kullanılıyorsa hizmeti kaldırın veya yorum bloğuna sarın. Yalnızca şu yöntemleri bırakın: .getUi, .createMenu, .addItem ve .addToUi. Ayrıca, bir işlevin dışında kalan hizmetleri bulup kaldırın.
4. Özellikle oluşturdukları bilgileri kullanan, önceki adımda yorum eklenen veya kaldırılan kod satırlarını içerebilecek işlevleri belirleyin ve hizmet çağrılarını, ihtiyaç duyulan işlevlere taşıyın. Kod tabanınızı, önceki adımlarda yapılan değişikliklere uyacak şekilde yeniden düzenleyin veya yeniden yazın.
5. Kodu kaydedin ve bir test dağıtımı oluşturun. Test dağıtımı oluşturduğunuzda Yapılandırma alanının Mevcut kullanıcı için yüklendi olarak ayarlandığından ve Yapılandırma kutusunun altındaki metinde AuthMode.NONE içinde test et yazdığından 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. Servis çağrısını kaçırmış olabilirsiniz.

İlgili konular

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