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şlatma istemi gösterilir.

Bu akış sırasında kullanıcı arayüzü, komut dosyasının hangi izinleri istediğini kullanıcılara bildirir. Örneğin, bir komut dosyası e-posta iletilerini okuma veya takvim etkinlikleri oluşturma izni isteyebilir. Komut dosyası projesi, bu izinleri ayrı ayrı OAuth kapsamları olarak tanımlar.

Apps Komut Dosyası, çoğu komut dosyası için gerekli kapsamları otomatik olarak algılar. Bir komut dosyasının kullandığı kapsamları istediğiniz zaman görüntüleyebilirsiniz. URL dizelerini kullanarak kapsamları açıkça da ayarlayabilirsiniz. Bu işlem için manifest dosyanızı kullanın. Eklentiler gibi yayınlanmış uygulamalar, mümkün olan en dar kapsamları kullanmalıdır.

Yetkilendirme akışı sırasında Apps Komut Dosyası, gerekli kapsamların okunabilir açıklamalarını sunar. Örneğin, komut dosyanızın elektronik tablolara salt okuma erişimi olması gerekiyorsa manifest, https://www.googleapis.com/auth/spreadsheets.readonly kapsamını içerebilir. Yetkilendirme isteminde kullanıcıdan "Google E-Tablolarınızı görüntüleme" izni istenir.

Bazı kapsamlar diğerlerini içerir. Örneğin, https://www.googleapis.com/auth/spreadsheets için yetkili erişim, elektronik tablolara okuma ve yazma erişimi sağlar.

Apps Komut Dosyası IDE gibi bazı yüzeylerde kullanıcılar ayrıntılı OAuth kullanıcı rızası ekranını görür. Bu ekran, kullanıcıların tüm izinleri aynı anda vermek yerine belirli izinleri seçmesine olanak tanır. Komut dosyanızı ayrıntılı OAuth izinlerini işleyecek şekilde tasarlayın.

Kapsamları görüntüleme

Komut dosyası projenizin gerektirdiği kapsamları görmek için:

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

Açık kapsamlar ayarlama

Apps Komut Dosyası, işlev çağrıları için kodu tarayarak gerekli kapsamları otomatik olarak belirler. Bu, çoğu komut dosyası için yeterli olsa da yayınlanmış eklentiler, web uygulamaları, Chat uygulamaları ve Chat API'ye yapılan çağrılar için daha doğrudan kontrol uygulamanız gerekir.

Apps Komut Dosyası bazen otomatik olarak izinli kapsamlar atar. Bu durum, komut dosyanızın kullanıcılardan gerekenden daha fazla erişim izni istediği anlamına gelebilir. Yayınlanmış komut dosyalarında, geniş kapsamları komut dosyasının ihtiyaçlarını karşılayan sınırlı bir kümeyle değiştirin.

Uyarı: Her zaman mümkün olan en az izin verici kapsamı kullanın. Kullanıcı bilgilerini korumak için eklentiler ve yayınlanan diğer uygulamalar, ihtiyaç duyduklarından daha fazla kapsam izni istememelidir.

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

1. Senaryo projesini açın.
2. Sol tarafta Proje Ayarları'nı tıklayın.
3. "appsscript.json" manifest dosyasını düzenleyicide göster onay kutusunu işaretleyin.
4. Sol tarafta Düzenleyici'yi 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 dizisinin 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 tıklayın.

Ayrıntılı OAuth izinlerini işleme

Ayrıntılı OAuth kullanıcı rızası ekranı ilk olarak komut dosyalarını doğrudan çalıştıran kullanıcılar için Apps Komut Dosyası IDE'sinde kullanıma sunuldu. Kullanıcı rızası ekranı, zaman içinde makrolar, tetikleyiciler ve eklentiler gibi diğer yüzeylerde kademeli olarak kullanıma sunulur. Daha fazla bilgi için Google Apps Komut Dosyası IDE yürütmelerinde ayrıntılı OAuth izni başlıklı makaleyi inceleyin.

Ayrıntılı OAuth kullanıcı rızası ekranı, kullanıcıların hangi OAuth kapsamlarını yetkilendireceklerini belirtmelerine olanak tanır. Bu sayede kullanıcılar, her bir komut dosyasıyla hangi hesap verilerini paylaşacakları konusunda ayrıntılı kontrol sahibi olur. Örneğin, bir komut dosyası e-posta ve takvim kapsamları istediğinde kullanıcılar Takvim izni verebilir ancak Gmail izni vermeyebilir.

Aşağıdaki bölümlerde ayrıntılı OAuth izinlerinin nasıl işleneceği açıklanmaktadır.

Gerekli kapsamlar için otomatik olarak izin isteme

Bir yürütme akışı belirli kapsamlar gerektiriyorsa kullanıcıların bu izinleri vermesini zorunlu kılabilirsiniz. Komut dosyanız izinleri kontrol edebilir ve eksikse otomatik olarak isteyebilir.

ScriptApp sınıfındaki aşağıdaki yöntemler, izinleri doğrular ve yetkilendirme istemini oluşturur:

• requireScopes(authMode, oAuthScopes): Belirli kapsamları kullanan akışlar için bu yöntemi kullanın.
• requireAllScopes(authMode): Bir yürütme akışı tüm proje kapsamlarına bağlıysa bu yöntemi kullanın.

Örnek

Aşağıdaki örnekte requireScopes() ve requireAllScopes() işlevlerinin nasıl çağrılacağı gösterilmektedir. Komut dosyası, Gmail, E-Tablolar ve Takvim için kapsamlar kullanır. sendEmail() işlevi için yalnızca Gmail ve E-Tablolar kapsamları gerekirken createEventSendEmail() işlevi için komut dosyasının kullandığı tüm kapsamlar gerekir.

// 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("[e-mail]", "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("[e-mail]", "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

Kullanıcıların izin durumunu alabilir ve özel deneyimler tasarlayabilirsiniz. Örneğin, eksik izinler gerektiren özellikleri devre dışı bırakabilir veya bu gerekliliği açıklayan bir iletişim kutusu gösterebilirsiniz. Aşağıdaki yöntemler, kullanıcının yetkilendirdiği kapsamları ve eksik kapsamları istemek için kullanılan 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 eder.
• getAuthorizationInfo(authMode): Tüm proje kapsamları için izin durumunu kontrol eder.

Yetkilendirme bilgisi nesnesinden izin ayrıntılarını (ör. yetkilendirilmiş kapsamların listesi ve eksik izinler için istekte bulunulacak URL) almak için AuthorizationInfo sınıfındaki yöntemleri kullanın.

Örnek

Aşağıdaki örnekte, kullanıcıların gerekli kapsamları vermediği özelliklerin atlanması için getAuthorizationInfo()'nın nasıl kullanı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("[e-mail]", "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 izinlere sahip olduğundan emin olun

Tetikleyicilerle ilişkili işlevler otomatik olarak çalışır ve kullanıcılar 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şime izin verdikleri 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çmesi gerekir. Daha fazla bilgi için aşağıdaki kılavuzlara bakın:

• Apps Komut Dosyası 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 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 uygulama yayınlarsanız bu uygulama tüm spesifikasyonlara uymalıdır.

Yayınlamadan önce kısıtlanmış kapsamların tam listesini inceleyin. Uygun uygulamalar, Belirli API Kapsamları İçin Ek Gereksinimler'e uymalıdır.

İnceleme sürecini basitleştirmek için mümkünse kısıtlanmış kapsamları kullanmaktan kaçının. Herkese açık olmayan uygulamalarda kısıtlanmış kapsamları serbestçe kullanabilirsiniz.