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 tentang izin yang ingin diminta oleh skrip. Misalnya, skrip mungkin ingin meminta 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 dalam manifes menggunakan string URL. Menetapkan cakupan secara eksplisit terkadang diperlukan untuk aplikasi tertentu seperti add-on, karena aplikasi yang dipublikasikan harus selalu menggunakan cakupan sesempit mungkin.

Selama alur otorisasi, Apps Script menampilkan deskripsi cakupan yang diperlukan yang mudah dibaca oleh pengguna. Misalnya, jika skrip Anda memerlukan akses hanya baca ke spreadsheet Anda, 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 Spreadsheet Google Anda".

Beberapa cakupan mencakup cakupan lainnya. Misalnya, saat diberi otorisasi, cakupan https://www.googleapis.com/auth/spreadsheets memungkinkan 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 yang akan diberikan, bukan memberikan semua izin sekaligus. Penting untuk mendesain skrip Anda agar menangani izin OAuth terperinci.

Melihat cakupan

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

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

Menetapkan cakupan eksplisit

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

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

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

1. Buka project skrip.
2. Di sebelah kiri, klik Setelan Project settings.
3. Pilih kotak centang Tampilkan file manifes "appsscript.json" dalam editor.
4. Di sebelah kiri, klik Editor code.
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 save.

Menangani izin OAuth terperinci

Layar izin OAuth terperinci memungkinkan pengguna menentukan cakupan OAuth individu mana yang ingin mereka beri otorisasi. Izin OAuth terperinci memberi pengguna kontrol yang lebih cermat 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 Anda mungkin ingin menggunakan skrip Anda hanya untuk kemampuannya dengan Google Kalender, tetapi tidak dengan Gmail. Dengan izin OAuth terperinci, pengguna dapat memilih untuk hanya memberikan izin Kalender, tetapi tidak untuk Gmail.

Bagian berikut menjelaskan cara utama untuk menangani izin OAuth terperinci.

Otomatis meminta izin untuk cakupan yang diperlukan

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

Metode berikut dari class ScriptApp memungkinkan Anda memvalidasi izin untuk cakupan yang diperlukan dan otomatis merender dialog 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 bergantung pada semua cakupan yang digunakan oleh skrip Anda.

Contoh

Contoh berikut menunjukkan cara memanggil metode requireScopes(authMode, oAuthScopes) dan requireAllScopes(authMode). Skrip ini 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("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!");
}

Membuat pengalaman kustom untuk cakupan yang tidak ada

Anda bisa mendapatkan detail izin pengguna yang menjalankan skrip dan mendesain pengalaman kustom berdasarkan status izinnya. 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 diberi otorisasi 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 yang 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("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...
}

Pastikan eksekusi pemicu memiliki izin

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

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