認証スコープ

ユーザーは、データにアクセスしたり、ユーザーに代わって操作したりするスクリプト プロジェクトを承認する必要があります。このプロセスの概要については、 Google サービスの承認をご覧ください。 ユーザーが初めて承認が必要なスクリプトを実行すると、承認フローを開始するためのプロンプトが UI に表示されます。

このフローでは、スクリプトがリクエストする権限が UI に表示されます。たとえば、スクリプトがメール メッセージの読み取りやカレンダーの予定の作成の権限をリクエストすることがあります。スクリプト プロジェクトでは、これらの個々の権限が OAuth スコープとして定義されます。

ほとんどのスクリプトでは、Apps Script が必要なスコープを自動的に検出します。スクリプトで使用されるスコープはいつでも確認できます。URL 文字列を使用して、マニフェストでスコープを明示的に設定することもできます。アドオンなどの公開済み アプリケーションでは、可能な限り 狭いスコープを使用する必要があります。

承認フローでは、Apps Script は必要なスコープの説明を人間が読める形式で提示します。たとえば、スクリプトでスプレッドシートへの読み取り専用アクセスが必要な場合、マニフェストには https://www.googleapis.com/auth/spreadsheets.readonly のスコープが含まれていることがあります。承認プロンプトでは、ユーザーに「Google スプレッドシートの閲覧」を許可するよう求めます。

一部のスコープには他のスコープが含まれています。たとえば、https://www.googleapis.com/auth/spreadsheets への承認済みアクセスでは、スプレッドシートへの読み取りと書き込みのアクセスが許可されます。

Apps Script IDE などの一部のサーフェスでは、ユーザーにきめ細かな OAuth 同意画面が表示されます。この画面では、ユーザーはすべての権限を一度に付与するのではなく、付与する特定の権限を選択できます。きめ細かな OAuth 権限を処理するようにスクリプトを 設計してください。

表示スコープ

スクリプト プロジェクトに必要なスコープを確認するには:

1. スクリプト プロジェクトを開きます。
2. 左側の [概要] をクリックします。
3. [プロジェクトの OAuth スコープ] でスコープを確認します。

明示的なスコープを設定する

Apps Script は、関数呼び出しのコードをスキャンして、必要なスコープを自動的に判断します。ほとんどのスクリプトではこれで十分ですが、公開されたアドオン、ウェブアプリ、Chat アプリ、Chat API の呼び出しでは、より直接的な制御を行う必要があります。

Apps Script では、緩いスコープが自動的に割り当てられることがあります。 つまり、スクリプトが必要とする以上のアクセス権をユーザーに求める可能性があります。スクリプトを公開する場合は、広範なスコープを、スクリプトのニーズを過不足なくカバーする限定的なセットに置き換えます。

警告: 常に、可能な限り最小限の権限のスコープを使用してください。アドオンやその他の公開済みアプリケーションは、必要以上のスコープ権限をリクエストすべきではありません。これは、ユーザー情報を保護することが目的です。

スクリプト プロジェクトで使用するスコープは、 マニフェスト ファイルを編集して明示的に設定できます。oauthScopes マニフェスト フィールドは、プロジェクトで使用されるスコープの配列です。プロジェクトのスコープを設定するには:

1. スクリプト プロジェクトを開きます。
2. 左側の [Project Settings] をクリックします。
3. [「appsscript.json」マニフェスト ファイルをエディタで表示する] チェックボックスをオンにします。
4. 左側の [Editor] をクリックします。
5. 左側の appsscript.json ファイルをクリックします。
6. oauthScopes というラベルの付いた最上位フィールドを見つけます。存在しない場合は、追加できます。
7. oauthScopes 配列の内容を、プロジェクトで使用するスコープに置き換えます。次に例を示します。

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

8. 上部の [保存] をクリックします。

きめ細かな OAuth 権限を処理する

きめ細かな OAuth 同意画面は、まず Apps Script IDE で、スクリプトを直接実行するユーザー向けにリリースされました。この同意画面は、今後マクロ、トリガー、アドオンなどの他の実行環境にも段階的に導入される予定です。詳しくは、 Google Apps Script の IDE の実行におけるきめ細かい OAuth の同意をご覧ください。

きめ細かな OAuth 同意画面では、ユーザーが認証する OAuth スコープを個別に指定できます。これにより、ユーザーは各スクリプトと共有するアカウント データをより細かく制御できます。たとえば、スクリプトがメールとカレンダーのスコープをリクエストした場合、ユーザーはカレンダーの権限を付与しても Gmail の権限は付与しないように選択できます。

以降のセクションでは、きめ細かな OAuth 権限を処理する方法について説明します。

必要なスコープの権限を自動的に要求する

実行フローに特定のスコープが必要な場合は、ユーザーにその権限を付与するよう求めることができます。スクリプトで権限を確認し、不足している場合は自動的に権限をリクエストできます。

ScriptApp クラスの次のメソッドは、 権限を検証し、承認プロンプトを表示します。

• requireScopes(authMode, oAuthScopes): 特定のスコープに依存するフローには、このメソッドを使用します。
• requireAllScopes(authMode): 実行フローがすべてのプロジェクト スコープに依存する場合は、このメソッドを使用します。

例

次の例は、requireScopes() と requireAllScopes() を呼び出す方法を示しています。このスクリプトでは、Gmail、スプレッドシート、カレンダーのスコープを使用します。sendEmail() 関数に必要なスコープは Gmail とスプレッドシートのみですが、createEventSendEmail() 関数にはスクリプトで使用されるすべてのスコープが必要です。

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

スコープが不足している場合のカスタム処理を作成する

ユーザーの権限ステータスを取得して、カスタム処理を設計できます。 たとえば、権限が不足している機能を無効にしたり、要件を説明するダイアログを表示したりできます。次のメソッドは、ユーザーが承認したスコープと、不足しているスコープをリクエストするための URL を含む、ユーザーの権限情報を含むオブジェクトを取得します。

• getAuthorizationInfo(authMode, oAuthScopes): 特定のスコープの権限ステータスを確認します。
• getAuthorizationInfo(authMode): すべてのプロジェクト スコープの権限ステータスを確認します。

承認されたスコープのリストや、不足している権限をリクエストする URL など、認可情報オブジェクトから権限の詳細を取得するには、 AuthorizationInfo クラスのメソッドを使用します。

例

次の例は、getAuthorizationInfo() を使用して、必要なスコープがユーザーに付与されていない機能をスキップする方法を示しています。これにより、不足しているスコープの承認を求めることなく、実行フローの残りの部分を続行できます。

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

トリガー実行に権限があることを確認する

トリガーに関連付けられた関数は自動的に実行されるため、ユーザーが権限を付与できない場合があります。トリガーをインストールする前に requireScopes(authMode, oAuthScopes) を使用することをおすすめします。これは、ユーザーに不足している権限の確認を求めるもので、権限の確認がないとトリガーはインストールできません。

例

// 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 の検証

特定の OAuth スコープは、Google ユーザーデータへのアクセスを許可するため、機密性が高いと見なされます。 スクリプトプロジェクトがユーザーデータへのアクセスを許可するスコープを使用する場合は、 ウェブアプリまたは アドオンとして一般公開する前に、 OAuth クライアントの検証を受ける必要があります。詳細については、次のガイドをご覧ください。

• Apps Script の OAuth クライアント検証
• 未検証のアプリ
• OAuth 検証に関するよくある質問
• Google API サービス: ユーザーデータに関するポリシー

制限付きスコープ

機密性の高いスコープのほかにも、特定のスコープは 制限付き に分類され、ユーザーデータの保護を目的とした追加のルールが適用されます。制限付きスコープを使用するアプリを公開する場合は、すべての仕様に準拠する必要があります。

公開前に、制限付きスコープの完全なリスト を確認してください。準拠しているアプリは、 特定の API スコープの追加要件に準拠する必要があります。

レビュー プロセスを簡素化するため、可能な限り制限付きスコープの使用は避けてください。非公開のアプリでは、制限付きスコープを自由に使用できます。