Cakupan Otorisasi

Pengguna harus memberikan otorisasi pada project skrip yang mengakses data mereka atau bertindak atas nama mereka. Saat pengguna menjalankan skrip yang memerlukan otorisasi untuk pertama kalinya, UI akan menampilkan perintah untuk memulai alur otorisasi.

Selama alur ini, UI memberi tahu pengguna izin yang diminta skrip. Misalnya, skrip dapat meminta izin untuk membaca pesan email atau membuat acara kalender. Project skrip menentukan izin individual ini sebagai cakupan OAuth.

Untuk sebagian besar skrip, Apps Script otomatis mendeteksi cakupan yang diperlukan. Anda dapat melihat cakupan yang digunakan skrip kapan saja. Anda juga dapat menetapkan cakupan secara eksplisit dalam manifes menggunakan string URL. Aplikasi yang dipublikasikan, seperti add-on, harus menggunakan cakupan sesempit mungkin.

Selama alur otorisasi, Apps Script menampilkan deskripsi cakupan yang diperlukan yang dapat dibaca manusia. Misalnya, jika skrip Anda memerlukan akses hanya baca ke spreadsheet, manifes dapat menyertakan cakupan https://www.googleapis.com/auth/spreadsheets.readonly. Dialog otorisasi meminta pengguna untuk "Melihat Spreadsheet Google Anda".

Beberapa cakupan mencakup cakupan lainnya. Misalnya, akses yang sah ke https://www.googleapis.com/auth/spreadsheets memungkinkan akses baca dan tulis ke spreadsheet.

Untuk beberapa platform, seperti IDE Apps Script, pengguna akan melihat layar izin OAuth terperinci. Layar ini memungkinkan pengguna memilih izin tertentu yang akan diberikan, bukan memberikan semua izin sekaligus. Rancang skrip Anda untuk menangani izin OAuth terperinci.

Melihat cakupan

Untuk melihat cakupan yang diperlukan project skrip Anda:

1. Buka project skrip.
2. Di sebelah kiri, klik Ringkasan .
3. Lihat cakupan di bagian Project OAuth Scopes.

Menetapkan cakupan eksplisit

Apps Script secara otomatis menentukan cakupan yang diperlukan dengan memindai kode untuk panggilan fungsi. Meskipun hal ini cukup untuk sebagian besar skrip, Anda harus menggunakan kontrol yang lebih langsung untuk add-on yang dipublikasikan, aplikasi web, aplikasi Chat, dan panggilan ke Chat API.

Apps Script terkadang otomatis menetapkan cakupan permisif. Hal ini dapat berarti skrip Anda meminta lebih banyak akses daripada yang diperlukan pengguna. Untuk skrip yang dipublikasikan, ganti cakupan luas dengan kumpulan terbatas yang mencakup kebutuhan skrip.

Peringatan: Selalu gunakan setelan cakupan dengan izin paling rendah yang memungkinkan. Untuk melindungi informasi pengguna, add-on dan aplikasi lain yang dipublikasikan tidak boleh meminta izin cakupan yang lebih banyak dari yang diperlukan.

Anda dapat menetapkan cakupan yang digunakan project skrip secara eksplisit dengan mengedit file manifest-nya. Kolom oauthScopes manifes adalah array cakupan yang digunakan oleh project. Untuk menetapkan cakupan project Anda:

1. Buka project skrip.
2. Di sebelah kiri, klik Project Settings .
3. Pilih kotak centang Tampilkan file manifes "appsscript.json" dalam editor.
4. Di sebelah kiri, klik Editor .
5. Di sebelah kiri, klik file appsscript.json.
6. Temukan kolom tingkat teratas berlabel oauthScopes. Jika tidak ada, Anda dapat menambahkannya.
7. Ganti konten array oauthScopes dengan cakupan yang Anda inginkan agar project gunakan. Contoh:

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

8. Di bagian atas, klik Simpan .

Menangani izin OAuth terperinci

Layar izin OAuth terperinci pertama kali diluncurkan di IDE Apps Script untuk pengguna yang menjalankan skrip secara langsung. Layar izin dirilis secara bertahap ke platform lain, seperti makro, pemicu, dan add-on, dari waktu ke waktu. Untuk mengetahui informasi selengkapnya, lihat Izin OAuth terperinci dalam eksekusi IDE Google Apps Script.

Layar izin OAuth terperinci memungkinkan pengguna menentukan cakupan OAuth individual mana yang akan diizinkan. Hal ini memberi pengguna kontrol terperinci atas data akun yang mereka bagikan dengan setiap skrip. Misalnya, jika skrip meminta cakupan email dan kalender, pengguna dapat memilih untuk memberikan izin Kalender, tetapi tidak memberikan izin Gmail.

Bagian berikut menjelaskan cara menangani izin OAuth terperinci.

Otomatis meminta izin untuk cakupan yang diperlukan

Jika alur eksekusi memerlukan cakupan tertentu, Anda dapat mewajibkan pengguna untuk memberikan izin tersebut. Skrip Anda dapat memeriksa izin dan otomatis memintanya jika tidak ada.

Metode berikut dari class ScriptApp memvalidasi izin dan merender dialog otorisasi:

• requireScopes(authMode, oAuthScopes): Gunakan metode ini untuk alur yang mengandalkan cakupan tertentu.
• requireAllScopes(authMode): Gunakan metode ini jika alur eksekusi mengandalkan semua cakupan project.

Contoh

Contoh berikut menunjukkan cara memanggil requireScopes() dan requireAllScopes(). Skrip menggunakan cakupan untuk Gmail, Spreadsheet, dan Kalender. Fungsi sendEmail() hanya memerlukan cakupan untuk Gmail dan Spreadsheet, sedangkan fungsi createEventSendEmail() memerlukan semua cakupan yang digunakan oleh skrip.

// 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!");
}

Membuat pengalaman kustom untuk cakupan yang tidak ada

Anda dapat mengambil status izin pengguna dan mendesain pengalaman kustom. Misalnya, Anda dapat menonaktifkan fitur yang memerlukan izin yang tidak ada atau menampilkan dialog yang menjelaskan persyaratan tersebut. Metode berikut mengambil objek dengan informasi izin pengguna yang mencakup cakupan yang telah diizinkan pengguna dan URL untuk meminta cakupan yang tidak ada:

• getAuthorizationInfo(authMode, oAuthScopes): Memeriksa status izin untuk cakupan tertentu.
• getAuthorizationInfo(authMode): Memeriksa status izin untuk semua cakupan project.

Untuk mendapatkan detail izin dari objek info otorisasi, seperti daftar cakupan yang diizinkan dan URL untuk meminta izin yang tidak ada, gunakan metode dari class AuthorizationInfo.

Contoh

Contoh berikut menunjukkan cara menggunakan getAuthorizationInfo() untuk melewati fitur yang belum diberikan cakupannya oleh pengguna. Hal ini memungkinkan alur eksekusi lainnya berlanjut tanpa meminta otorisasi cakupan yang tidak ada.

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

Pastikan eksekusi pemicu memiliki izin

Fungsi yang terkait dengan pemicu berjalan secara otomatis, dan pengguna mungkin tidak ada untuk memberikan izin. Sebaiknya gunakan requireScopes(authMode, oAuthScopes) sebelum menginstal pemicu. Hal ini akan meminta izin yang tidak ada kepada pengguna dan tidak mengizinkan penginstalan pemicu tanpa izin tersebut.

Contoh

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

Verifikasi OAuth

Cakupan OAuth tertentu bersifat sensitif karena memungkinkan akses ke Data Pengguna Google. Jika project skrip Anda menggunakan cakupan yang memungkinkan akses ke data pengguna, project tersebut harus melalui verifikasi klien OAuth sebelum Anda dapat memublikasikannya secara publik sebagai aplikasi web atau add-on. Untuk informasi selengkapnya, lihat panduan berikut:

• Verifikasi klien OAuth untuk Apps Script
• Aplikasi yang belum diverifikasi
• FAQ verifikasi OAuth
• Layanan Google API: Kebijakan Data Pengguna

Cakupan yang dibatasi

Selain cakupan sensitif, cakupan tertentu diklasifikasikan sebagai dibatasi dan tunduk pada aturan tambahan yang membantu melindungi data pengguna. Jika Anda memublikasikan aplikasi yang menggunakan cakupan terbatas, aplikasi tersebut harus mematuhi semua spesifikasi.

Tinjau daftar lengkap cakupan yang dibatasi sebelum memublikasikan. Aplikasi yang mematuhi kebijakan harus mengikuti Persyaratan Tambahan untuk cakupan API Tertentu.

Sebisa mungkin hindari penggunaan cakupan terbatas untuk menyederhanakan proses peninjauan. Anda dapat menggunakan cakupan terbatas secara bebas untuk aplikasi non-publik.