Yetkilendirme Kapsamları

Kullanıcılar, verilerine erişen veya kendi adlarına işlem yapan komut dosyası projelerini yetkilendirmelidir. Bir kullanıcı, ilk kez yetkilendirme gerektiren bir komut dosyası çalıştırdığında kullanıcı arayüzünde yetkilendirme akışını başlatmak için bir istem gösterilir.

Bu akış sırasında kullanıcı arayüzü, komut dosyasının ne yapmak için izin istediğini kullanıcıya bildirir. Örneğin, bir komut dosyası kullanıcının e-posta mesajlarını okumak veya takviminde etkinlik oluşturmak için izin isteyebilir. Komut dosyası projesi, bu izinleri OAuth kapsamları olarak tanımlar.

Apps Komut Dosyası, çoğu komut dosyası için hangi kapsamların gerekli olduğunu otomatik olarak algılar. Bir komut dosyasının kullandığı kapsamları istediğiniz zaman görüntüleyebilirsiniz. URL dizelerini kullanarak manifestinizde kapsamları açıkça da ayarlayabilirsiniz. Yayınlanan uygulamalar her zaman mümkün olan en dar kapsamları kullanmalıdır. Bu nedenle, eklentiler gibi belirli uygulamalar için kapsamların açıkça ayarlanması bazen gereklidir.

Apps Komut Dosyası, yetkilendirme akışı sırasında gerekli kapsamların okunabilir açıklamalarını kullanıcıya sunar. Örneğin, komut dosyanızın elektronik tablolarınıza salt okuma erişimi olması gerekiyorsa manifest dosyasında https://www.googleapis.com/auth/spreadsheets.readonly kapsamı olabilir. Yetkilendirme akışı sırasında, bu kapsama sahip bir komut dosyası kullanıcıdan bu uygulamanın "Google E-Tablolarınızı görüntülemesine" izin vermesini ister.

Bazı kapsamlar diğer kapsamları içerir. Örneğin, kapsam yetkilendirildiğinde https://www.googleapis.com/auth/spreadsheets, elektronik tablolara okuma ve yazma erişimine izin verir.

Komut dosyalarının çalıştırıldığı bazı yüzeylerde (ör. doğrudan Apps Komut Dosyası IDE'sinden komut dosyası çalıştırma) kullanıcılara ayrıntılı OAuth kullanıcı rızası ekranı gösterilir. Bu sayede kullanıcılar, tüm izinleri aynı anda vermek yerine verilecek belirli izinleri seçebilir. Komut dosyanızı ayrıntılı OAuth izinlerini işleyecek şekilde tasarlamanız önemlidir.

Kapsamları görüntüleme

Aşağıdaki adımları uygulayarak komut dosyası projenizin şu anda gerektirdiği kapsamları görebilirsiniz:

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

Açık kapsamlar ayarlama

Apps Komut Dosyası, kodunu tarayarak bir komut dosyasının hangi kapsamlara ihtiyacı olduğunu otomatik olarak belirler. Bu, çoğu komut dosyası için yeterlidir ve zamandan tasarruf etmenizi sağlar. Ancak yayınlanmış eklentiler, web uygulamaları, Google Chat uygulamaları ve Google Chat API'ye yapılan çağrılar için kapsamlar üzerinde daha doğrudan kontrol uygulamanız gerekir.

Apps Komut Dosyası bazen projelere otomatik olarak çok izinli kapsamlar atar. Bu durum, komut dosyanızın kullanıcıdan gerekenden daha fazla bilgi istediği anlamına gelebilir. Bu da kötü bir uygulamadır. Yayınlanmış komut dosyalarında, geniş kapsamları komut dosyasının ihtiyaçlarını karşılayan ancak daha fazlasını karşılamayan daha sınırlı bir kapsam grubuyla değiştirmeniz gerekir.

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

1. Senaryo projesini açın.
2. Sol tarafta Proje Ayarları'nı settings tıklayın.
3. "appsscript.json" manifest dosyasını düzenleyicide göster onay kutusunu işaretleyin.
4. Sol tarafta Düzenleyici'yi code tıklayın.
5. Solda, appsscript.json dosyasını tıklayın.
6. oauthScopes etiketli üst düzey alanı bulun. Bu seçenek yoksa ekleyebilirsiniz.
7. oauthScopes alanı, bir dizeler dizisini belirtir. Projenizin kullandığı kapsamları ayarlamak için bu dizinin içeriğini, projenin kullanmasını istediğiniz kapsamlarla değiştirin. Örneğin:

         {
           ...
           "oauthScopes": [
             "https://www.googleapis.com/auth/spreadsheets.readonly",
             "https://www.googleapis.com/auth/userinfo.email"
           ],
          ...
         }

8. Üstte Kaydet'i save tıklayın.

Ayrıntılı OAuth izinlerini işleme

Ayrıntılı OAuth izin ekranı, kullanıcıların hangi OAuth kapsamlarını yetkilendirmek istediklerini belirtmelerine olanak tanır. Ayrıntılı OAuth izinleri, kullanıcılara her bir komut dosyasıyla hangi hesap verilerini paylaşacakları konusunda daha ayrıntılı kontrol imkanı sunar. Örneğin, hem e-posta hem de takvim kapsamları için izin isteyen bir komut dosyası geliştirdiğinizi düşünün. Kullanıcılarınız, komut dosyanızı yalnızca Google Takvim ile ilgili özellikleri için kullanmak isteyebilir ancak Gmail ile ilgili özellikleri için kullanmak istemeyebilir. Ayrıntılı OAuth izinleri sayesinde kullanıcılar yalnızca Takvim izni vermeyi, Gmail izni vermemeyi seçebilir.

Aşağıdaki bölümlerde, ayrıntılı OAuth izinlerini yönetmenin temel yolları açıklanmaktadır.

Gerekli kapsamlar için otomatik olarak izin isteme

Bir yürütme akışının çalışması için kapsamlarla ilgili izinlere ihtiyacı varsa kullanıcıların bu izinleri vermesini zorunlu tutabilirsiniz. Komut dosyanız, kullanıcının izni verip vermediğini kontrol edebilir ve vermediyse otomatik olarak izin isteyebilir.

ScriptApp sınıfındaki aşağıdaki yöntemler, gerekli kapsamlar için izni doğrulamanıza ve eksik izinleri istemek üzere yetkilendirme istemini otomatik olarak oluşturmanıza olanak tanır:

• requireScopes(authMode, oAuthScopes): Bu yöntemi, bir veya daha fazla kapsama bağlı olan ancak komut dosyanız tarafından kullanılan tüm kapsamlara bağlı olmayan yürütme akışları için kullanın.
• requireAllScopes(authMode): Bir yürütme akışı, komut dosyanız tarafından kullanılan tüm kapsamları temel alıyorsa bu yöntemi kullanın.

Örnek

Aşağıdaki örnekte, requireScopes(authMode, oAuthScopes) ve requireAllScopes(authMode) yöntemlerinin nasıl çağrılacağı gösterilmektedir. Komut dosyası, Gmail, E-Tablolar ve Takvim için kapsamlar kullanır. sendEmail() işlevi yalnızca Gmail ve E-Tablolar'ın kapsamlarını gerektirirken createEventSendEmail() işlevi, komut dosyası tarafından kullanılan tüm kapsamları gerektirir.

// This function requires the Gmail and Sheets scopes.
function sendEmail() {
  // Validates that the user has granted permission for the Gmail and Sheets scopes.
  // If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://mail.google.com/',
    'https://www.googleapis.com/auth/spreadsheets'
  ]);

  // Sends an email.
  GmailApp.sendEmail("dana@example.com", "Subject", "Body");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue("Sent");
  Logger.log("Sheet updated successfully!");
}

// This function requires all scopes used by the script (Gmail,
// Calendar, and Sheets).
function createEventSendEmail() {
  // Validates that the user has granted permission for all scopes used by the
  // script. If not, the execution ends and prompts the user for authorization.
  ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

  // Creates an event.
  CalendarApp.getDefaultCalendar().createEvent(
    "Meeting",
    new Date("November 28, 2024 10:00:00"),
    new Date("November 28, 2024 11:00:00")
  );
  Logger.log("Calendar event created successfully!");

  // Sends an email.
  GmailApp.sendEmail("dana@example.com", "Subject 2", "Body 2");
  Logger.log("Email sent successfully!");

  // Opens a spreadsheet and sheet to track the created meeting and sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Email and Meeting Tracker")
  // Gets the last row
  const lastRow = sheet.getLastRow();

  // Adds "Sent" to column E of the last row
  sheet.getRange(lastRow, 5).setValue("Sent");
  // Adds "Meeting created" to column F of the last row
  sheet.getRange(lastRow, 6).setValue("Meeting created");
  Logger.log("Sheet updated successfully!");
}

Eksik kapsamlar için özel deneyim oluşturma

Komut dosyanızı çalıştıran kullanıcının izin ayrıntılarını alabilir ve izin durumuna göre özel bir deneyim tasarlayabilirsiniz. Örneğin, kullanıcının vermediği izinleri gerektiren komut dosyanızın belirli özelliklerini devre dışı bırakabilir veya eksik izinleri açıklayan özel bir iletişim kutusu gösterebilirsiniz. Aşağıdaki yöntemler, kullanıcının yetkilendirdiği kapsamları ve eksik kapsamları istemenize olanak tanıyan bir URL'yi içeren, kullanıcının izin bilgilerini içeren bir nesne alır:

• getAuthorizationInfo(authMode, oAuthScopes): Belirli kapsamlar için izin durumunu kontrol etmek üzere bu yöntemi kullanın.
• getAuthorizationInfo(authMode): Komut dosyanız tarafından kullanılan tüm kapsamların izin durumunu kontrol etmek için bu yöntemi kullanın.

Yetkilendirme bilgisi nesnesinden izin ayrıntılarını (ör. hangi kapsamların yetkilendirildiğinin listesi ve eksik izinleri istemek için kullanılan URL) almak için AuthorizationInfo sınıfındaki yöntemleri kullanın.

Örnek

Aşağıdaki örnekte, gerekli kapsamların verilmediği bir yürütme akışında belirli özellikleri atlamak için getAuthorizationInfo(authMode, oAuthScopes) yönteminin nasıl çağrılacağı gösterilmektedir. Bu sayede, yürütme akışının geri kalanı, eksik kapsamların yetkilendirilmesi istenmeden devam edebilir.

// This function uses the Gmail scope and skips the email
// capabilities if the scope for Gmail hasn't been granted.
function myFunction() {
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, ['https://mail.google.com/']);
  if (authInfo.getAuthorizationStatus() === ScriptApp.AuthorizationStatus.NOT_REQUIRED) {
    GmailApp.sendEmail("dana@example.com", "Subject", "Body");
    Logger.log("Email sent successfully!");
  } else {
    const scopesGranted = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL).getAuthorizedScopes();
    console.warn(`Authorized scopes: ${scopesGranted} not enough to send mail, skipping.`);
  }
  // Continue the rest of the execution flow...
}

Tetikleyici yürütmelerinin izinleri olduğundan emin olun

Tetikleyicilerle ilişkili işlevler belirli etkinliklerde otomatik olarak çalışabilir ve kullanıcı, daha fazla izin vermek için orada olmayabilir. Bir tetikleyici yüklemeden önce requireScopes(authMode, oAuthScopes) kullanmanızı öneririz. Bu işlem, kullanıcıdan eksik izinleri ister ve izinler olmadan tetikleyicinin yüklenmesine izin vermez.

Örnek

// This function requires scope Sheets.
function trackFormSubmissions(e){
  // Opens a spreadsheet to track the sent email.
  const ss = SpreadsheetApp.openById("abc1234567");
  const sheet = ss.getSheetByName("Submission Tracker")

  // Gets the last row of the sheet.
  const lastRow = sheet.getLastRow();

  // Adds email address of user that submitted the form
  // to column E of the last row of the spreadsheet.
  sheet.getRange(lastRow, 5).setValue(e.name);
  Logger.log("Sheet updated successfully!");
}


function installTrigger(){
  // Validates that the user has granted permissions for trigger
  // installation and execution. If not, trigger doesn't get
  // installed and prompts the user for authorization.
  ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
    'https://www.googleapis.com/auth/script.scriptapp',
    'https://www.googleapis.com/auth/spreadsheets',
    'https://www.googleapis.com/auth/forms.currentonly'
  ]);
  ScriptApp.newTrigger('trackFormSubmission')
    .forForm(FormApp.getActiveForm())
    .onFormSubmit()
    .create();
}

OAuth doğrulaması

Belirli OAuth kapsamları, Google Kullanıcı Verilerine erişim sağladıkları için hassastır. Komut dosyası projeniz, kullanıcı verilerine erişime izin veren kapsamlar kullanıyorsa projeyi web uygulaması veya eklenti olarak herkese açık bir şekilde yayınlamadan önce OAuth istemci doğrulamasından geçirmeniz gerekir. Daha fazla bilgi için aşağıdaki kılavuzlara bakın:

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

Kısıtlanmış kapsamlar

Hassas kapsamların yanı sıra belirli kapsamlar kısıtlanmış olarak sınıflandırılır ve kullanıcı verilerinin korunmasına yardımcı olan ek kurallara tabidir. Kısıtlanmış kapsamlar kullanan bir web uygulaması veya eklenti yayınlamayı planlıyorsanız uygulamanın yayınlanabilmesi için belirtilen tüm kısıtlamalara uyması gerekir.

Yayınlamayı denemeden önce kısıtlanmış kapsamların tam listesini inceleyin. Uygulamanız bunlardan herhangi birini kullanıyorsa yayınlamadan önce Belirli API Kapsamları İçin Ek Gereksinimler'e uymanız gerekir.