Yetkilendirme Kapsamları

Kullanıcılar, verilerine erişen veya kendi adlarına işlem yapan komut dosyası projelerini yetkilendirmelidir. Kullanıcı, yetkilendirme gerektiren bir komut dosyasını ilk kez çalıştırdığında kullanıcı arayüzünde yetkilendirme akışını başlatma istemi 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 ihtiyacınız olan kapsamları otomatik olarak algılar. Bir komut dosyasının kullandığı kapsamları dilediğiniz zaman görüntüleyebilirsiniz. URL dizeleri kullanarak manifest kapsamları açıkça da ayarlayabilirsiniz. Yayınlanan uygulamalar her zaman mümkün olan en dar kapsamları kullanması gerektiğinden, eklentiler gibi belirli uygulamalar için bazen kapsamları açıkça ayarlamak gerekir.

Apps Script, yetkilendirme akışı sırasında kullanıcıya gerekli kapsamların kullanıcı tarafından okunabilir açıklamalarını sunar. Örneğin, komut dosyanızın e-tablonuz için salt okuma erişimine ihtiyacı varsa manifest'in kapsamı https://www.googleapis.com/auth/spreadsheets.readonly 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ğerlerini kapsar. Örneğin, yetkilendirildiğinde https://www.googleapis.com/auth/spreadsheets kapsamı e-tablolara okuma ve yazma erişimi sağlar.

Komut dosyalarının çalıştırıldığı bazı yüzeylerde (ör. doğrudan Apps Script IDE'den 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 bir kerede vermek yerine belirli izinleri verebilir. Komut dosyanızı ayrıntılı OAuth izinlerini işleyecek şekilde tasarlamanız önemlidir.

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ıninfo_outline.
3. Kapsamları Proje OAuth Kapsamları bölümünde görüntüleyin.

Açık kapsamlar ayarlama

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, web uygulamaları, Google Chat uygulamaları ve Google Chat API çağrıları için kapsamları daha doğrudan kontrol etmeniz gerekir.

Apps Komut Dosyası bazen projelere otomatik olarak çok izin verici kapsamlar atar. Bu, komut dosyanızın kullanıcıdan ihtiyaç duyduğundan daha fazla bilgi istediği anlamına gelebilir. Bu, kötü bir uygulamadır. Yayınlanan komut dosyalarında, geniş kapsamları komut dosyasının ihtiyaçlarını karşılayan ve daha fazlasını kapsamayan daha sınırlı bir kümeyle değiştirmeniz gerekir.

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

1. Komut dosyası 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. Sol tarafta appsscript.json dosyasını tıklayın.
6. oauthScopes etiketli üst düzey alanı bulun. Bu seçenek yoksa ekleyebilirsiniz.
7. 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:

         {
           ...
           "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 yönetme

Ayrıntılı OAuth izin ekranı, kullanıcıların yetkilendirmek istedikleri OAuth kapsamlarını tek tek belirtmesine olanak tanır. Ayrıntılı OAuth izinleri, kullanıcılara her komut dosyasıyla paylaşmayı seçtikleri hesap verileri üzerinde daha ayrıntılı kontrol sağlar. Örneğin, hem e-posta hem de takvim kapsamları için izin isteyen bir komut dosyası geliştirdiğinizi varsayalım. Kullanıcılarınız, komut dosyanızı yalnızca Google Takvim'deki özellikleri için kullanmak isteyebilir ancak Gmail'de kullanmak istemeyebilir. Ayrıntılı OAuth izinleriyle kullanıcılar, Gmail için değil yalnızca Takvim için izin vermeyi seçebilir.

Aşağıdaki bölümlerde, ayrıntılı OAuth izinlerini kullanmanın başlıca yolları açıklanmaktadır.

Gerekli kapsamlar için otomatik olarak izin isteme

Bir yürütme akışının çalışması için kapsam izinlerine ihtiyacı varsa kullanıcıların bu akışı kullanabilmeleri için önce bu izinleri vermeleri gerekebilir. Komut dosyanız, kullanıcının izin verip vermediğini kontrol edebilir ve izin vermemişse 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, komut dosyanız tarafından kullanılan tüm kapsamlar değil, bir veya daha fazla kapsama dayanan 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 kapsamlara dayanı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 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, komut dosyanızın kullanıcının vermediği izinleri gerektiren belirli özelliklerini devre dışı bırakmaya karar verebilir veya eksik izinleri açıklayan özel bir iletişim kutusu gösterebilirsiniz. Aşağıdaki yöntemler, kullanıcının izin bilgilerini içeren bir nesne alır. Bu bilgiler arasında kullanıcının yetkilendirdiği kapsamlar ve eksik kapsamları istemenize olanak tanıyan bir URL bulunur:

• getAuthorizationInfo(authMode, oAuthScopes): Belirli kapsamların izin durumunu kontrol etmek için bu yöntemi kullanın.
• getAuthorizationInfo(authMode): Kodunuzun kullandığı tüm kapsamların izin durumunu kontrol etmek için bu yöntemi kullanın.

Yetkilendirme bilgileri nesnesinden izin ayrıntılarını (ör. hangi kapsamların yetkilendirildiğine dair bir liste ve eksik izinleri isteyecek bir 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, eksik kapsamlar için yetkilendirme isteğinde bulunmadan yürütme akışının geri kalanının devam etmesine olanak tanır.

// 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...
}

OAuth doğrulaması

Belirli OAuth kapsamları, Google Kullanıcı Verilerine erişim sağladığı için hassas olarak kabul edilir. Komut dosyası projenizde kullanıcı verilerine erişime izin veren kapsamlar kullanılıyorsa projeyi web uygulaması veya eklenti olarak herkese açık olarak yayınlayabilmeniz için OAuth istemci doğrulamasından geçmesi gerekir. 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

Hassas kapsamlara ek olarak belirli kapsamlar kısıtlanmış olarak sınıflandırılır ve kullanıcı verilerinin korunmasına yardımcı olan ek kurallara tabidir. Bir veya daha fazla kısıtlanmış kapsam kullanan bir web uygulaması ya da 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ızda bunlardan herhangi biri kullanılıyorsa yayınlamadan önce Belirli API Kapsamları İçin Ek Gereksinimler'e uymanız gerekir.