Nişan dürbünleri

Kullanıcılar, verilerine erişen veya kendileri adına hareket eden eklentileri ve diğer uygulamaları yetkilendirmelidir. Kullanıcı bir eklentiyi ilk kez çalıştırdığında eklenti kullanıcı arayüzü, yetkilendirme akışını başlatmak için bir yetkilendirme istemi gösterir.

Bu akış sırasında istem, kullanıcıya uygulamanın ne tür izinler istediğini bildirir. Örneğin, bir eklenti kullanıcının e-posta mesajını okumak veya takviminde etkinlik oluşturmak için izin isteyebilir. Eklentinin komut dosyası projesi, bu izinleri OAuth kapsamları olarak tanımlar.

URL dizeleri kullanarak manifest dosyanızda kapsamları beyan edersiniz. Apps Script, yetkilendirme akışı sırasında kullanıcıya kapsamın kullanıcı tarafından okunabilir bir açıklamasını sunar. Örneğin, Google Workspace eklentiniz "Mevcut mesajı oku" kapsamını kullanabilir. Bu kapsam, manifest dosyanızda https://www.googleapis.com/auth/gmail.addons.current.message.readonly olarak yazılır. Yetkilendirme akışında, bu kapsama sahip bir eklenti kullanıcıdan eklentinin Eklenti çalışırken e-posta iletilerinizi görüntülemesine izin vermesini ister.

Not: Apps Script'in çeşitli hizmetleri için kullandığı kapsamlar, ilgili API tarafından kullanılan kapsamlarla örtüşür. Örneğin, Apps Komut Dosyası'nın Takvim hizmeti, Calendar API ile aynı kapsamların çoğunu kullanır. Belirli Apps Komut Dosyası hizmet yöntemlerinin gerektirdiği kapsamları Apps Komut Dosyası referans dokümanlarında bulabilirsiniz.

Kapsamları görüntüleme

Aşağıdakileri yaparak komut dosyası projenizin şu anda ihtiyaç duyduğu kapsamları görebilirsiniz:

1. Komut dosyası projesini açın.
2. Sol tarafta Genel bakış'ı tıklayın.
3. "Proje OAuth Kapsamları" bölümündeki kapsamları görüntüleyin.

Komut dosyası projesinin mevcut kapsamlarını, proje manifestinde oauthScopes alanının altında da görüntüleyebilirsiniz. Ancak bu kapsamları açıkça ayarlamanız gerekir.

Açık kapsamlar belirleme

Apps Komut Dosyası, bir komut dosyasının ihtiyaç duyduğu kapsamları, kodunu bu kapsamları gerektiren işlev çağrıları açısından tarayarak otomatik olarak belirler. Çoğu komut dosyası için bu yeterlidir ve size zaman kazandırır ancak yayınlanan eklentiler için kapsamlar üzerinde daha doğrudan kontrol sahibi olmanız gerekir.

Örneğin, Apps Komut Dosyası bir eklenti komut dosyası projesine varsayılan olarak çok izin verici bir kapsam https://mail.google.com verebilir. Bir kullanıcı bu kapsama sahip bir komut dosyası projesine yetki verdiğinde projeye kullanıcının Gmail hesabına tam erişim izni verilir. Yayınlanan eklentiler için bu kapsamı, eklentilerin ihtiyaçlarını karşılayan ve daha fazlasını kapsamayan daha sınırlı bir grupla değiştirmeniz gerekir.

Uyarı: Her zaman mümkün olan en az izin verilen kapsam grubunu kullanın. Kullanıcı bilgilerini korumak için eklentiler ve diğer yayınlanan uygulamalar, kesinlikle ihtiyaç duydukları kapsam izinlerinden daha fazlasını asla istememelidir. Eklentinizin gerektirdiği kapsamlar, yayınlanma eklenti incelemesi sürecinde incelenir. Eklenti çok geniş kapsamlar kullanıyorsa incelemeden geçemez.

Komut dosyası projenizin kullandığı kapsamları, manifest dosyasını düzenleyerek açıkça belirleyebilirsiniz. Manifest alanı oauthScopes, eklenti tarafından kullanılan tüm kapsamların bir dizisidir. Projenizin kapsamlarını ayarlamak için aşağıdakileri yapın:

1. Eklentinizin şu anda kullandığı kapsamları görüntüleyin. Daha dar bir kapsam kullanmak gibi yapılması gereken değişiklikleri belirleyin.
2. Eklentinizin manifest dosyasını açın.
3. oauthScopes etiketli üst düzey alanı bulun. Bu seçenek yoksa ekleyebilirsiniz.

4. oauthScopes alanı bir dize dizisi belirtir. Projenizin kullanacağı kapsamları ayarlamak için bu dizinin içeriğini, kullanmak istediğiniz kapsamlarla değiştirin. Örneğin, Gmail'i genişleten bir Google Workspace eklentisi için aşağıdakilere sahip olabilirsiniz:

   {
     ...
     "oauthScopes": [
       "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
       "https://www.googleapis.com/auth/userinfo.email"
     ],
     ...
   }
   

5. Manifest dosyasındaki değişiklikleri kaydedin.

OAuth doğrulaması

Belirli hassas OAuth kapsamlarını kullandığınızda, eklentinizi yayınlayabilmeniz için OAuth istemci doğrulamasından geçmesi gerekebilir. Daha fazla bilgi için aşağıdaki kılavuzları inceleyin:

• Apps Script için OAuth istemci doğrulaması
• Doğrulanmamış uygulamalar
• OAuth doğrulaması ile ilgili SSS
• Google API'leri Hizmeti: Kullanıcı Verileri Politikası

Kısıtlanmış kapsamlar

Belirli kapsamlar kısıtlanmış olup kullanıcı verilerini korumaya yardımcı olan ek kurallara tabidir. Bir veya daha fazla kısıtlanmış kapsam kullanan bir Gmail ya da Düzenleyici eklentisi yayınlamak istiyorsanız eklentinin yayınlanabilmesi için belirtilen tüm kısıtlamalara uyması gerekir.

Yayınlamayı denemeden önce kısıtlanmış kapsamların tam listesini inceleyin. Eklentinizde bunlardan herhangi biri kullanılıyorsa yayınlamadan önce Belirli API kapsamları için ek şartlar'a uymanız gerekir.

Not: Mümkünse eklentinizde kısıtlanmış kapsamlar kullanmaktan kaçının. Bu kapsamları kullanmazsanız herkese açık olarak yayınlanmak üzere eklenti incelemesini geçmek daha kolaydır. Kısıtlanmış kapsamları, herkese açık olmayan eklentiler için özgürce kullanabilirsiniz.

Google Workspace eklentileri için kapsam seçme

Aşağıdaki bölümlerde, Google Workspace eklentileri için yaygın olarak kullanılan kapsamlar sağlanmaktadır.

Düzenleyici kapsamları

Dokümanlar, E-Tablolar ve Slaytlar'ı genişleten Google Workspace eklentilerinde sık kullanılan kapsamlar aşağıda verilmiştir.

Not: currentonly kapsamı yalnızca Apps Script Hizmetleri'nde kullanılabilir. Buna Apps Komut Dosyası Gelişmiş Hizmetleri veya Google Workspace API'lerine doğrudan çağrılar dahil değildir.

Kapsam
Mevcut Dokümanlar dosyalarına erişim	https://www.googleapis.com/auth/documents.currentonly Eklentinin Apps Script Dokümanlar API'sine erişmesi gerekiyorsa gereklidir. Açık dokümanın içeriğine geçici erişim izni verir.
Geçerli E-Tablolar dosyasına erişim	https://www.googleapis.com/auth/spreadsheets.currentonly Eklenti, Apps Script Sheets API'ye erişiyorsa gereklidir. Açık e-tablonun içeriğine geçici erişim izni verir.
Geçerli Slaytlar dosyasına erişim	https://www.googleapis.com/auth/presentations.currentonly Eklenti, Apps Script Slaytlar API'sine erişiyorsa gereklidir. Açık sununun içeriğine geçici erişim izni verir.
Dosya başına erişim	https://www.googleapis.com/auth/drive.file Eklentinin onFileScopeGrantedTrigger kullanması için gereklidir ve eklenti Dokümanlar, E-Tablolar, Slaytlar veya Drive API'ye erişiyorsa. Apps Komut Dosyası Gelişmiş Drive Hizmeti'ni kullanarak uygulama tarafından oluşturulan veya açılan dosyalara dosya başına erişim izni verir. Ancak bu, temel Drive hizmeti kullanılarak benzer işlemlerin yapılmasına izin vermez. Dosya yetkilendirmesi dosya bazında verilir ve kullanıcı uygulamanın yetkisini kaldırdığında iptal edilir.

Gmail

Kullanıcı Gmail verilerini korumaya yardımcı olmak için Google Workspace eklentileri için özel olarak oluşturulmuş birkaç kapsam vardır. Eklenti kodunuzun gerektirdiği diğerlerinin yanı sıra bu kapsamları eklenti manifestinize açıkça eklemeniz gerekir.

Gmail'i genişleten Google Workspace eklentileri için sık kullanılan kapsamlar aşağıda verilmiştir. Eklentiniz Gmail'i genişletiyorsa Zorunlu olarak etiketlenenler Google Workspace eklentisi manifestinize eklenmelidir.

Ayrıca, eklentinizdeki çok geniş https://mail.google.com kapsamını, eklentinizin ihtiyaç duyduğu etkileşimlere izin veren ve daha fazlasına izin vermeyen daha dar bir kapsam grubuyla değiştirdiğinizden emin olun.

Kapsam
Yeni taslak oluştur	https://www.googleapis.com/auth/gmail.addons.current.action.compose Eklenti, oluşturma işlemi tetikleyicileri kullanıyorsa gereklidir. Eklentinin geçici olarak yeni taslak iletiler ve yanıtlar oluşturmasına olanak tanır. Ayrıntılar için Taslak mesaj oluşturma bölümünü inceleyin. Bu kapsam genellikle oluşturma işlemleri ile birlikte de kullanılır. Erişim jetonu gerektirir.
Açık mesaj meta verilerini okuma	https://www.googleapis.com/auth/gmail.addons.current.message.metadata Açık mesajın meta verilerine (ör. konu veya alıcılar) geçici erişim izni verir. İleti içeriğinin okunmasına izin vermez ve erişim jetonu gerektirir. Eklenti, oluşturma işlemi tetikleyicilerinde meta veriler kullanıyorsa gereklidir. Teklif oluşturma işlemleri için, bir teklif oluşturma tetikleyicisinin meta verilere erişmesi gerekiyorsa bu kapsam gereklidir. Uygulamada bu kapsam, bir yanıt e-postası taslağının alıcı listelerine (to:, cc: ve bcc:) erişim izni veren bir oluşturma tetikleyicisine izin verir.
Açık ileti içeriğini okuma	https://www.googleapis.com/auth/gmail.addons.current.message.action Kullanıcı etkileşimi (ör. eklenti menüsü öğesi seçildiğinde) sonrasında açık ileti içeriğine erişim izni verir. Erişim jetonu gerektirir.
Açık mesaj dizisi içeriğini okuma	https://www.googleapis.com/auth/gmail.addons.current.message.readonly Açık mesajın meta verilerine ve içeriğine geçici erişim izni verir. Ayrıca, açık mesaj dizisindeki diğer mesajların içeriğine de erişim izni verir. Erişim jetonu gerektirir.
Tüm mesaj içeriklerini ve meta verilerini okuma	https://www.googleapis.com/auth/gmail.readonly Açık mesaj da dahil olmak üzere tüm e-posta meta verilerini ve içeriklerini okuma Arama sorgusu gerçekleştirirken veya bir posta ileti dizisinin tamamını okurken diğer iletilerle ilgili bilgileri okumanız gerekiyorsa gereklidir. Uyarı: Bu, çok geniş ve kısıtlanmış bir kapsamdır. Yalnızca kesinlikle gerekli olduğunda kullanın.

Google Takvim kapsamları

Google Takvim'i genişleten Google Workspace eklentileri için sık kullanılan kapsamlar aşağıda verilmiştir.

Kapsam
Etkinlik meta verilerine erişme	https://www.googleapis.com/auth/calendar.addons.execute Eklenti, Takvim etkinlik meta verilerine erişiyorsa gereklidir. Eklentinin etkinlik meta verilerine erişmesine izin verir.
Kullanıcı tarafından oluşturulan etkinlik verilerini okuma	https://www.googleapis.com/auth/calendar.addons.current.event.read Eklentinin kullanıcı tarafından oluşturulan etkinlik verilerini okuması gerekiyorsa gereklidir. Eklentinin, kullanıcı tarafından oluşturulan etkinlik verilerine erişmesine izin verir. Bu veriler yalnızca addOns.calendar.eventAccess manifest alanı READ veya READ_WRITE olarak ayarlandıysa kullanılabilir.
Kullanıcı tarafından oluşturulan etkinlik verilerini yazma	https://www.googleapis.com/auth/calendar.addons.current.event.write Eklentinin kullanıcı tarafından oluşturulan etkinlik verileri yazması gerekiyorsa gereklidir. Eklentinin, kullanıcı tarafından oluşturulan etkinlik verilerini düzenlemesine izin verir. Bu veriler yalnızca addOns.calendar.eventAccess manifest alanı WRITE veya READ_WRITE olarak ayarlandıysa kullanılabilir.

Google Drive kapsamları

Google Drive'ı genişleten Google Workspace eklentileri için sık kullanılan kapsamlar aşağıda verilmiştir.

Kapsam
Seçilen öğe meta verilerini okuma	https://www.googleapis.com/auth/drive.addons.metadata.readonly Eklenti, kullanıcı Drive'da öğe seçtiğinde tetiklenen bağlama dayalı bir arayüz kullanıyorsa gereklidir. Eklentinin, kullanıcının Google Drive'da seçtiği öğelerle ilgili sınırlı meta verileri okumasına izin verir. Meta veriler, öğenin kimliği, başlığı, MIME türü, simge URL'si ve eklentinin öğeye erişme iznine sahip olup olmadığıyla sınırlıdır.
Dosya başına erişim	https://www.googleapis.com/auth/drive.file Eklentinin tek tek Drive dosyalarına erişmesi gerekiyorsa önerilir. Apps Komut Dosyası Gelişmiş Drive Hizmeti'ni kullanarak uygulama tarafından oluşturulan veya açılan dosyalara dosya başına erişim izni verir. Ancak bu, temel Drive hizmeti kullanılarak benzer işlemlerin yapılmasına izin vermez. Dosya yetkilendirmesi dosya başına verilir ve kullanıcı uygulamanın yetkisini kaldırdığında iptal edilir. Seçilen dosyalar için dosya erişimi isteğinde bulunma örneğine göz atın.

Erişim jetonları

Google Workspace eklentilerinde kullanılan Gmail kapsamları, kullanıcı verilerini korumak için yalnızca kullanıcı verilerine geçici erişim izni verir. Geçici erişimi etkinleştirmek için bağımsız değişken olarak bir erişim jetonu kullanarak GmailApp.setCurrentMessageAccessToken(accessToken) işlevini çağırmanız gerekir. İşlem etkinliği nesnesinden erişim jetonu almanız gerekir.

Not: Gmail kapsamlarını etkinleştiren erişim jetonu, ScriptApp.getOAuthToken() tarafından döndürülen erişim jetonuyla aynı değildir. İşlem etkinliği nesnesinde sağlanan jetonu kullanmanız gerekir.

Aşağıda, bir mesajın meta verilerine erişime izin vermek için erişim jetonu ayarlama örneği gösterilmektedir. Bu örnek için gereken tek kapsam https://www.googleapis.com/auth/gmail.addons.current.message.metadata'tır.

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

Diğer Google Workspace kapsamları

Eklentiniz diğer Google Workspace veya Apps Komut Dosyası hizmetlerini kullanıyorsa ek kapsamlar gerekebilir. Çoğu durumda Apps Script'in bu kapsamları algılamasına ve manifest dosyasını otomatik olarak güncellemesine izin verebilirsiniz. Manifest'inizin kapsam listesini düzenlerken, daha dar bir kapsam gibi daha uygun bir alternatifle değiştirmediğiniz sürece hiçbir kapsamı kaldırmayın.

Aşağıdaki tabloda, Google Workspace eklentilerinin sıklıkla kullandığı kapsamların listesi gösterilmektedir:

Kapsam
Kullanıcının e-posta adresini okuma	https://www.googleapis.com/auth/userinfo.email Projenin mevcut kullanıcının e-posta adresini okumasına izin verir.
Kuruluş dışı hizmetlere yapılan aramalara izin verme	https://www.googleapis.com/auth/script.external_request Projenin UrlFetch istek göndermesine izin verir. Projede Apps Script için OAuth2 kitaplığı kullanılıyorsa da bu gereklidir.
Kullanıcının yerel ayarlarını ve saat dilimini okuma	https://www.googleapis.com/auth/script.locale Projenin mevcut kullanıcının yerel ayarını ve saat dilimini öğrenmesine olanak tanır. Ayrıntılar için Kullanıcı yerel ayarına ve saat dilimine erişme başlıklı makaleyi inceleyin.
Tetikleyiciler oluşturma	https://www.googleapis.com/auth/script.scriptapp Projenin tetikleyici oluşturmasına izin verir.
Üçüncü taraf bağlantılarını önizleme	https://www.googleapis.com/auth/workspace.linkpreview Eklentinin üçüncü taraf hizmetindeki bağlantıları önizlemesi gerekiyorsa gereklidir. Kullanıcı bir Google Workspace uygulamasıyla etkileşimde bulunurken projenin bu uygulamadaki bir bağlantıyı görmesine olanak tanır. Daha fazla bilgi için Akıllı çiplerle bağlantıları önizleme başlıklı makaleyi inceleyin.
Üçüncü taraf kaynakları oluşturma	https://www.googleapis.com/auth/workspace.linkcreate Eklentinin üçüncü taraf hizmetinde kaynak oluşturması durumunda gereklidir. Projenin, kullanıcıların kaynak oluşturma formuna gönderdiği bilgileri okumasına ve bir Google Workspace uygulamasına kaynağın bağlantı eklemesine olanak tanır. Daha fazla bilgi edinmek için @ menüsünden üçüncü taraf kaynakları oluşturma başlıklı makaleyi inceleyin.