Düzenleyici Eklenti yetkilendirmesi

Birisi uygulamayı kullanmaya çalıştığında komut dosyası projesi ihtiyaç duyduğu eksik izinleri ister. Bu nedenle, Apps Komut Dosyası tabanlı pek çok uygulama için yetkilendirme basittir.

Düzenleyici Eklentileri için yetkilendirme modeli, çeşitli nedenlerden dolayı daha karmaşıktır:

• Kullanıcı bir dosya oluşturduğunda, bu eklentiler için henüz yetki vermemiş olsa bile kullanıcının yüklediği tüm eklentiler Uzantılar menüsünde listelenir.

• Bu eklentiler, ortak çalışanlarla paylaşılabilecek Google Drive dosyalarında çalışır. Düzenleyici Eklentisi'ni yüklememiş olan ortak çalışanlar, eklentiyi dosyayı oluşturan kişinin kullandığı dokümanlarda görür.

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

Kullanıcı verilerini korumak için bazı hizmetleri onOpen() tarafından kullanılamayan yetkilendirme modları uygulanır. Bu kılavuz, kodunuzun neyi ne zaman yapabileceğini anlamanıza yardımcı olabilir.

Yetkilendirme modeli

Düzenleyici Eklentisi'nin yetkilendirme modu, eklentiyi kimin kullandığına (eklentiyi yükleyen kullanıcı veya ortak çalışan) bağlı olan durumuna bağlıdır.

Düzenleyici eklentisi durumları

Uzantılar menüsündeki Düzenleyici Eklentileri yüklenir, etkinleştirilir veya her ikisi birden yüklenir.

• Belirli bir kullanıcı veya yöneticisi eklentiyi Google Workspace Marketplace'ten alıp Google verilerine erişmesi için yetkilendirdikten sonra ilgili kullanıcı için eklenti yüklenir.
• Bir eklenti, dokümanda, formda, sunuda veya e-tabloda başkaları tarafından kullanılıyorsa etkinleştirilir.
• Kullanıcılar bir dosya üzerinde ortak çalıştığında ve onlardan biri bir eklenti kullandığında, eklenti tek kullanıcı için yüklenir ve dosya için etkinleştirilir.

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

	Yüklendi	Etkin
Uygulandığı yer	Kullanıcı	Doküman, form, sunu veya e-tablo
Yol açan neden:	Eklentiyi mağazadan alma	Söz konusu dokümanı, formu, sunuyu veya e-tabloyu kullanırken mağazadan eklenti alma ya da Söz konusu doküman, form, sunu veya e-tabloya daha önce yüklenmiş bir eklentiyi kullanarak
Menüyü şu kişiler görebilir:	Yalnızca bu kullanıcı (açtığı veya oluşturduğu tüm dokümanlar, formlar, sunular ya da e-tablolarda)	Söz konusu doküman, form, sunu veya e-tablodaki tüm ortak çalışanlar
onOpen() için yetkilendirme modu	AuthMode.NONE (etkin değilse. Bu durumda AuthMode.LIMITED)	AuthMode.LIMITED

Yetkilendirme modları

Kullanıcı bir dokümanı, formu, sunuyu veya e-tabloyu açtığında, Düzenleyici Eklentisinin onOpen() işlevi otomatik olarak çalışır. Apps Komut Dosyası, 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 içinde çalışır. Eklenti etkin değilse ve yalnızca yüklüyse onOpen(), AuthMode.NONE üzerinde çalışır.

AuthMode.NONE ürününde bir eklenti, kullanıcı özel işlevleri tıklayarak veya çalıştırarak eklentiyle etkileşimde bulunana kadar 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 durdurulur. Yardım, desteklenen tek seçenektir.

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.

Not: Yalnızca yayınlanan Düzenleyici Eklentileri AuthMode.NONE içinde bulunabilir. Yayından kaldırılan Düzenleyici Eklentileri, AuthMode.LIMITED içinde onOpen() çalışır. Ancak, geliştirme aşamasındaki bir eklentinin her iki yetkilendirme modunda da istenen şekilde davrandığını doğrulamak için bir Düzenleyici Eklentisini test edebilirsiniz.

Apps Komut Dosyası, yetkilendirme modunu Apps Komut Dosyası etkinlik parametresinin authMode özelliği (e) olarak iletir. e.authMode değeri, Apps Komut Dosyası ScriptApp.AuthMode sıralaması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. Bununla birlikte, e.authMode özelliği yalnızca komut dosyası onOpen(), onEdit() veya onInstall() gibi bir tetikleyicinin sonucu olarak çalışıyorsa incelenebilir. Google E-Tablolar'daki özel işlevler, kendi yetkilendirme modunu (AuthMode.CUSTOM_FUNCTION) kullanır. Bu mod, LIMITED uygulamasına benzer ancak kısıtlamalardan biraz farklıdır. Diğer tüm durumlarda komut dosyaları, aşağıdaki tabloda açıklandığı gibi AuthMode.FULL sisteminde çalışır.

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
Geçtiği yer:	onOpen() (kullanıcı bir eklenti yüklemiş ancak dokümanda, formda, sunuda veya e-tabloda etkinleştirmemişse)	onOpen() (diğer tüm zamanlar) onEdit() (yalnızca E-Tablolar'da)	Özel işlevler	Aşağıdakiler dahil olmak üzere diğer tüm zamanlar: yüklenebilir tetikleyiciler onInstall() google.script.run
Kullanıcı verilerine erişim	Yalnızca yerel ayar	Yalnızca yerel ayar	Yalnızca yerel ayar	Evet
Dokümana, forma, sunuya veya e-tabloya erişim	Hayır	Evet	Evet - salt okunur	Evet
Kullanıcı arayüzüne erişim	Menü öğeleri ekleme	Menü öğeleri ekleme	Hayır	Evet
Properties ürününe erişim	Hayır	Evet	Evet	Evet
Erişim: Jdbc, UrlFetch	Hayır	Hayır	Evet	Evet
Diğer hizmetler	Logger Utilities	Kullanıcı verilerine erişmeyen hizmetler	Kullanıcı verilerine erişmeyen hizmetler	Tüm hizmetler

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

Geçerli kullanıcı için bir eklenti yüklendiğinde veya geçerli dosyada etkinleştirildiğinde, söz konusu dosya açıldığında eklenti doküman, form, sunu veya 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ıklarsa uzantı çalıştırılır.

Düzenleyici eklentisi yüklendi

Mağazadan bir Düzenleyici Eklentisi yüklendiğinde, onInstall() işlevi AuthMode.FULL içinde çalışır. Eklenti bu yetkilendirme modunda 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 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çıldı

Bir doküman, form, sunu veya e-tablo açıldığında, geçerli kullanıcının yüklediği veya herhangi bir ortak çalışanın dosyada etkinleştirdiği tüm Düzenleyici Eklentisi yüklenir ve onOpen() işlevlerinden her birini çağırır. onOpen() tarafından çalışacağı yetkilendirme modu, bir eklentinin yüklü veya etkinleştirilmemiş olmasına bağlıdır.

Bir eklenti yalnızca temel bir menü oluşturursa mod önemli değildir. 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 Komut Dosyası özelliklerine göre dinamik menü öğeleri eklemek, geçerli 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 işlemeniz gerekir.

Aşağıdaki örnek, işlemini yetkilendirme moduna göre değiştiren gelişmiş bir onOpen() işlevini göstermektedir:

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();
}

Uyarı: onOpen() işlevi çalıştığında, komut dosyasının tamamı yüklenir ve tüm genel ifadeler onOpen() ile aynı yetkilendirme modunda çalıştırılır. Yetkilendirme modu genel ifadeleri yasaklıyorsa hem global 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ının JavaScript konsolunu inceleyin. Ardından, onOpen() işlevinin veya genel değişkenlerin AuthMode.NONE içinde izin verilmeyen hizmetleri çağırıp çağırmadığını görmek için komut dosyanızı inceleyin.

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

Kullanıcı Düzenleyici Eklentisi'ni çalıştırır

Kullanıcı bir Uzantılar menü öğesini tıkladığında Apps Komut Dosyası ilk olarak kullanıcının eklentiyi yükleyip yüklemediğini kontrol eder, yüklü değilse de eklentiyi yükleyip yüklemediğini ister. Kullanıcı eklentiyi yetkilendirdiyse komut dosyası, AuthMode.FULL içindeki menü öğesine karşılık gelen işlevi çalıştırır. Eklenti, önceden etkinleştirilmemişse 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önetmezse 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ışır.

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

AuthMode.NONE içinde 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. Eklentiniz için 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) bahsedilenleri arayın.
3. Bir hizmet, kullanıcı arayüzü öğeleri oluşturmaktan başka bir amaçla kullanılıyorsa hizmeti kaldırın veya bir yorum bloğuna sarmalayın. Yalnızca şu yöntemleri bırakın: .getUi(), .createMenu(), .addItem() ve .addToUi(). Bir işlevin dışında kalan hizmetleri de bulun ve kaldırın.
4. Önceki adımda yorumlanan veya kaldırılan kod satırlarını (özellikle de ürettikleri bilgileri kullananları) içerebilen işlevleri tanımlayın ve hizmet çağrılarını bunlara ihtiyaç duyan işlevlere taşıyın. Kod tabanınızı önceki adımlarda yapılan değişiklikleri yansıtacak ş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 Geçerli kullanıcı için yüklü olduğundan ve Yapılandırma kutusunun altındaki metinde AuthMode.None uygulamasında 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örüntüleniyorsa sorun çözülmüştür. Yalnızca Yardım menüsünü görüyorsanız 1. adıma geri dönün. Bir servis aramasını cevaplamamış olabilirsiniz.

İlgili konular

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