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 kali, UI akan menampilkan perintah untuk memulai alur otorisasi.

Selama alur ini, UI akan memberi tahu pengguna tindakan yang ingin dilakukan skrip. Misalnya, skrip mungkin ingin izin untuk membaca pesan email pengguna atau membuat acara di kalendernya. Project skrip menentukan izin individual ini sebagai cakupan OAuth.

Untuk sebagian besar skrip, Apps Script otomatis mendeteksi cakupan yang diperlukan untuk Anda; Anda dapat melihat cakupan yang digunakan skrip kapan saja. Anda juga dapat menetapkan cakupan secara eksplisit di manifes menggunakan string URL. Menetapkan cakupan secara eksplisit terkadang diperlukan untuk aplikasi tertentu seperti add-on, karena aplikasi yang dipublikasikan harus selalu menggunakan cakupan sempit.

Selama alur otorisasi, Apps Script menampilkan deskripsi cakupan yang diperlukan kepada pengguna dalam bentuk yang dapat dibaca manusia. Misalnya, jika skrip Anda memerlukan akses hanya baca ke spreadsheet, manifes mungkin memiliki cakupan https://www.googleapis.com/auth/spreadsheets.readonly. Selama alur otorisasi, skrip dengan cakupan ini meminta pengguna untuk mengizinkan aplikasi ini "Melihat Google Spreadsheet Anda".

Beberapa cakupan mencakup cakupan lainnya. Misalnya, jika diberi otorisasi, cakupan https://www.googleapis.com/auth/spreadsheets akan mengizinkan akses baca dan tulis ke spreadsheet.

Untuk beberapa platform tempat skrip berjalan, seperti menjalankan skrip langsung dari IDE Apps Script, pengguna akan melihat layar izin OAuth terperinci. Hal ini memungkinkan pengguna memilih izin tertentu untuk diberikan, bukan memberikan semua izin sekaligus. Penting untuk mendesain skrip Anda untuk menangani izin OAuth terperinci.

Melihat cakupan

Anda dapat melihat cakupan yang saat ini diperlukan project skrip dengan melakukan langkah-langkah berikut:

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

Menetapkan cakupan eksplisit

Apps Script secara otomatis menentukan cakupan yang diperlukan skrip dengan memindai kodenya untuk menemukan panggilan fungsi yang memerlukannya. Untuk sebagian besar skrip, hal ini cukup dan menghemat waktu Anda, tetapi untuk add-on yang dipublikasikan, aplikasi web, aplikasi Google Chat, dan panggilan ke Google Chat API, Anda harus menggunakan kontrol yang lebih langsung terhadap cakupan.

Terkadang, Apps Script secara otomatis menetapkan cakupan yang sangat permisif ke project. Hal ini dapat berarti skrip Anda meminta lebih banyak dari yang diperlukan pengguna, yang merupakan praktik buruk. Untuk skrip yang dipublikasikan, Anda harus mengganti cakupan luas dengan kumpulan yang lebih terbatas yang mencakup kebutuhan skrip dan tidak lebih.

Peringatan: Selalu gunakan cakupan yang paling sedikit permisif. Untuk melindungi informasi pengguna, add-on dan aplikasi yang dipublikasikan lainnya tidak boleh pernah meminta izin cakupan yang lebih besar dari yang benar-benar diperlukan.

Anda dapat menetapkan cakupan yang digunakan project skrip secara eksplisit dengan mengedit file manifes-nya. Kolom manifes oauthScopes adalah array dari semua cakupan yang digunakan oleh project. Untuk menetapkan cakupan project, lakukan hal berikut:

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. Kolom oauthScopes menentukan array string. Untuk menetapkan cakupan yang digunakan project Anda, ganti konten array ini dengan cakupan yang ingin Anda 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

Catatan: Layar izin OAuth terperinci pertama kali diluncurkan ke IDE Apps Script untuk pengguna yang menjalankan skrip langsung dari Apps Script. Layar izin akan diluncurkan secara bertahap ke platform lainnya, seperti makro, eksekusi 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 yang ingin mereka izinkan. Izin OAuth terperinci memberi pengguna kontrol yang lebih terperinci atas data akun yang mereka pilih untuk dibagikan dengan setiap skrip. Misalnya, bayangkan Anda mengembangkan skrip yang meminta izin untuk cakupan email dan kalender. Pengguna mungkin ingin menggunakan skrip Anda hanya untuk kemampuannya dengan Google Kalender, tetapi bukan Gmail. Dengan izin OAuth terperinci, pengguna dapat memilih untuk hanya memberikan izin Kalender, tetapi tidak Gmail.

Bagian berikut menjelaskan cara utama untuk menangani izin OAuth granular.

Otomatis mewajibkan izin untuk cakupan yang diperlukan

Jika alur eksekusi memerlukan izin untuk cakupan agar dapat berfungsi, Anda dapat mewajibkan pengguna untuk memberikan izin tersebut sebelum dapat menggunakannya. Skrip Anda dapat memeriksa apakah pengguna telah memberikan izin dan, jika belum, akan otomatis memintanya.

Metode berikut dari class ScriptApp memungkinkan Anda memvalidasi izin untuk cakupan yang diperlukan dan otomatis merender perintah otorisasi untuk meminta izin yang tidak ada:

• requireScopes(authMode, oAuthScopes): Gunakan metode ini untuk alur eksekusi yang mengandalkan satu atau beberapa cakupan, tetapi tidak semua cakupan yang digunakan oleh skrip Anda.
• requireAllScopes(authMode): Gunakan metode ini jika alur eksekusi mengandalkan semua cakupan yang digunakan oleh skrip Anda.

Contoh

Contoh berikut menunjukkan cara memanggil metode requireScopes(authMode, oAuthScopes) dan requireAllScopes(authMode). Skrip menggunakan cakupan untuk Gmail, Spreadsheet, dan Kalender. Fungsi sendEmail() hanya memerlukan cakupan untuk Gmail dan Sheet, 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 bisa mendapatkan detail izin pengguna yang menjalankan skrip dan mendesain pengalaman kustom berdasarkan status izin mereka. Misalnya, Anda dapat memutuskan untuk menonaktifkan fitur tertentu dari skrip yang memerlukan izin yang belum diberikan pengguna, atau menampilkan dialog kustom yang menjelaskan izin yang tidak ada. Metode berikut mendapatkan objek dengan informasi izin pengguna yang mencakup cakupan yang telah diizinkan pengguna dan URL untuk memungkinkan Anda meminta cakupan yang tidak ada:

• getAuthorizationInfo(authMode, oAuthScopes): Gunakan metode ini untuk memeriksa status izin untuk cakupan tertentu.
• getAuthorizationInfo(authMode): Gunakan metode ini untuk memeriksa status izin untuk semua cakupan yang digunakan oleh skrip Anda.

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

Contoh

Contoh berikut menunjukkan cara memanggil metode getAuthorizationInfo(authMode, oAuthScopes) untuk melewati fitur tertentu dalam alur eksekusi jika cakupan yang diperlukan belum diberikan. Hal ini memungkinkan alur eksekusi lainnya berlanjut tanpa harus 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...
}

Memastikan eksekusi pemicu memiliki izin

Fungsi yang terkait dengan pemicu dapat berjalan secara otomatis pada peristiwa tertentu, dan pengguna mungkin tidak ada untuk memberikan lebih banyak izin. Sebaiknya gunakan requireScopes(authMode, oAuthScopes) sebelum menginstal pemicu. Tindakan ini akan meminta pengguna untuk memberikan izin yang tidak ada 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 ingin memublikasikan aplikasi web atau add-on yang menggunakan satu atau beberapa cakupan yang dibatasi, aplikasi tersebut harus mematuhi semua batasan yang ditentukan sebelum dapat dipublikasikan.

Tinjau daftar lengkap cakupan yang dibatasi sebelum Anda mencoba memublikasikan. Jika aplikasi Anda menggunakan salah satunya, Anda harus mematuhi Persyaratan Tambahan untuk Cakupan API Tertentu sebelum memublikasikan.

Catatan: Hindari penggunaan cakupan terbatas di aplikasi Anda jika memungkinkan—akan lebih mudah untuk lulus peninjauan untuk publikasi publik jika Anda tidak menggunakannya. Anda dapat menggunakan cakupan terbatas secara bebas untuk aplikasi dan skrip non-publik.