このページは Cloud Translation API によって翻訳されました。

認証スコープ

ユーザーは、自分のデータにアクセスするスクリプトプロジェクトまたはユーザーに代わって動作するスクリプトプロジェクトを承認する必要があります。ユーザーが初めて認証を必要とするスクリプトを実行すると、UI に認証フローを開始するためのプロンプトが表示されます。

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

ほとんどのスクリプトの場合、必要なスコープが自動的に検出されます。スクリプトで使用されているスコープを表示できます。URL 文字列を使用して、manifestでスコープを明示的に設定することもできます。公開されるアプリは常に可能な限り狭いスコープを使用する必要があるため、アドオンなどの特定のアプリでは、スコープを明示的に設定することが必要になることがあります。

認可フロー中に、Apps Script は必要なスコープの人間可読の説明をユーザーに提示します。たとえば、スクリプトでスプレッドシートへの読み取り専用アクセス権が必要な場合は、マニフェストのスコープが https://www.googleapis.com/auth/spreadsheets.readonly になります。承認フローの際に、このスコープを持つスクリプトから、このアプリに「Google スプレッドシートの表示」を許可するようユーザーに求めるメッセージが表示されます。

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

スクリプトが実行されるサーフェス（Apps Script IDE から直接スクリプトを実行する場合など）では、詳細な OAuth 同意画面が表示されます。これにより、ユーザーはすべての権限を一度に付与するのではなく、付与する権限を個別に選択できます。きめ細かい OAuth 権限を処理するようにスクリプトを設計することが重要です。

スコープを表示する

スクリプトプロジェクトで現在必要なスコープを確認する手順は次のとおりです。

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

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

Apps Script は、コードをスキャンして、必要な関数呼び出しを検出し、スクリプトに必要なスコープを自動的に決定します。ほとんどのスクリプトではこれで十分で、時間を節約できますが、公開済みのアドオン、ウェブアプリ、Google Chat アプリ、Google Chat API の呼び出しでは、スコープをより直接的に制御する必要があります。

Apps Script では、プロジェクトに非常に許可の範囲の広いスコープが自動的に割り当てられることがあります。これは、スクリプトが必要な以上の情報をユーザーに求めていることを意味します。これは好ましい方法ではありません。公開済みのスクリプトの場合は、広範なスコープを、スクリプトのニーズを満たす範囲に限定したセットに置き換える必要があります。

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

スクリプトプロジェクトを開きます。
左側の [プロジェクト設定] をクリックします。
[「appsscript.json」マニフェストファイルをエディタで表示する] チェックボックスをオンにします。
左側の [エディタ] をクリックします。
左側の appsscript.json ファイルをクリックします。
oauthScopes というラベルの付いた最上位フィールドを見つけます。存在しない場合は、追加できます。
oauthScopes フィールドは、文字列の配列を指定します。プロジェクトで使用するスコープを設定するには、この配列の内容を、使用するスコープに置き換えます。次に例を示します。
```
      {
        ...
        "oauthScopes": [
          "https://www.googleapis.com/auth/spreadsheets.readonly",
          "https://www.googleapis.com/auth/userinfo.email"
        ],
       ...
      }
```
上部の保存アイコン（）をクリックします。

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

詳細な OAuth 同意画面では、ユーザーが承認する個々の OAuth スコープを指定できます。きめ細かい OAuth 権限により、ユーザーは各スクリプトと共有するアカウントデータをよりきめ細かく管理できます。たとえば、メールスコープとカレンダースコープの両方の権限をリクエストするスクリプトを開発するとします。ユーザーは、Gmail ではなく Google カレンダーの機能にのみスクリプトを使用したい場合があります。きめ細かい OAuth 権限を使用すると、カレンダーの権限のみを付与し、Gmail の権限は付与しないように選択できます。

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

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

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

ScriptApp クラスの次のメソッドを使用すると、必要なスコープの権限を検証し、不足している権限をリクエストする認可プロンプトを自動的にレンダリングできます。

requireScopes(authMode, oAuthScopes): このメソッドは、スクリプトで使用されるすべてのスコープではなく、1 つ以上のスコープに依存する実行フローに対して使用します。
requireAllScopes(authMode): 実行フローがスクリプトで使用されるすべてのスコープに依存している場合は、このメソッドを使用します。

例

次の例は、requireScopes(authMode, oAuthScopes) メソッドと requireAllScopes(authMode) メソッドを呼び出す方法を示しています。このスクリプトでは、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("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!");
}

不足しているスコープ用のカスタムエクスペリエンスを作成する

スクリプトを実行しているユーザーの権限の詳細を取得し、権限のステータスに基づいてカスタムエクスペリエンスを設計できます。たとえば、ユーザーが付与していない権限を必要とするスクリプトの特定の機能を無効にしたり、不足している権限を説明するカスタムダイアログを表示したりできます。次のメソッドは、ユーザーの権限情報を含むオブジェクトを取得します。このオブジェクトには、ユーザーが承認したスコープと、不足しているスコープをリクエストするための URL が含まれます。

getAuthorizationInfo(authMode, oAuthScopes): このメソッドは、特定のスコープの権限ステータスを確認するために使用します。
getAuthorizationInfo(authMode): このメソッドは、スクリプトで使用されるすべてのスコープの権限ステータスを確認するために使用します。

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

例

次の例は、getAuthorizationInfo(authMode, oAuthScopes) メソッドを呼び出して、必要なスコープが付与されていない実行フロー内の特定の機能をスキップする方法を示しています。これにより、不足しているスコープの承認を求めることなく、残りの実行フローを続行できます。

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

OAuth の確認

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

制限付きのスコープ

センシティブスコープに加えて、特定のスコープは制限付きとして分類され、ユーザーデータの保護に役立つ追加のルールが適用されます。1 つ以上の制限付きスコープを使用するウェブアプリまたはアドオンを公開する場合は、公開前に、指定されたすべての制限に準拠する必要があります。

公開を試みる前に、制限付きスコープの一覧を確認してください。アプリでこれらの API のいずれかを使用している場合は、公開前に特定の API スコープの追加要件に準拠する必要があります。