選擇 Google Drive API 範圍

本文包含 Google Drive API 專屬的授權和驗證資訊。閱讀本文前，請務必先參閱「瞭解驗證和授權」，瞭解 Google Workspace 的一般驗證和授權資訊。

設定 OAuth 2.0 授權

如要授權應用程式，Google 雲端硬碟 API 需要您在兩個位置定義 OAuth 範圍：Google Cloud 控制台和應用程式。

在 Google Cloud 控制台中，您必須在應用程式的 OAuth 同意畫面設定中，聲明應用程式需要的範圍。這是應用程式可要求的最高權限層級。這是向 Google 提出的正式要求，而 Google 會在同意畫面上向使用者顯示已聲明的範圍。讓使用者確切瞭解應用程式要求存取的資料和動作。

設定 OAuth 同意畫面並選擇範圍，定義向使用者和應用程式審查人員顯示的資訊，然後註冊應用程式，以便日後發布。

在應用程式中啟動 API 時，您必須明確要求該工作階段所需的特定範圍。Google Cloud 控制台會定義應用程式可要求的最高權限層級，但程式碼會決定特定使用者的實際權限。確保應用程式只會要求執行特定工作所需的權限。

您可以在應用程式的程式碼中，一次宣告一或多個 OAuth 範圍 (以陣列形式)。

下列程式碼範例說明如何宣告多個 OAuth 範圍：

Java

List<String> SCOPES = Arrays.asList(
  DriveScopes.DRIVE_FILE,
  DriveScopes.DRIVE_METADATA_READONLY
);

Python

SCOPES = [
  "https://www.googleapis.com/auth/drive.file",
  "https://www.googleapis.com/auth/drive.metadata.readonly",
]

Node.js

const SCOPES = [
  'https://www.googleapis.com/auth/drive.file',
  'https://www.googleapis.com/auth/drive.metadata.readonly'
];

如要查看完整程式碼範例中如何宣告及使用範圍，請參閱快速入門導覽課程。

Drive API 範圍

如要定義授予應用程式的存取層級，您需要識別並宣告授權範圍。授權範圍是 OAuth 2.0 URI 字串，其中包含 Google Workspace 應用程式名稱、存取資料類型和存取層級。「範圍」是指應用程式要求存取 Google Workspace 資料，包括使用者 Google 帳戶資料。

安裝應用程式時，系統會要求使用者驗證應用程式使用的範圍。一般來說，您應盡可能選擇範圍最窄的範圍，並避免要求應用程式不需要的範圍。使用者更願意授予存取權給範圍有限且說明清楚的應用程式。

請盡可能使用非機密範圍，因為這類範圍會授予每個檔案的存取權，並將存取權限縮小至應用程式所需的特定功能。

非機密範圍

在多數用途中，建議使用下列 Drive API 範圍：

範圍代碼 說明
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 查看及管理此應用程式在 Google 雲端硬碟中的設定資料。
https://www.googleapis.com/auth/drive.install 允許應用程式顯示為「開啟方式」或「新增」選單中的選項。
https://www.googleapis.com/auth/drive.file 使用 Google Picker API 或應用程式的檔案挑選器時，建立新的雲端硬碟檔案，或修改您透過應用程式開啟的檔案，或使用者與應用程式共用的檔案。

機密範圍

範圍代碼 說明
https://www.googleapis.com/auth/drive.apps.readonly 查看有權存取雲端硬碟的應用程式。

受限制的範圍

範圍代碼 說明
https://www.googleapis.com/auth/drive 查看及管理所有雲端硬碟檔案。
https://www.googleapis.com/auth/drive.readonly 查看及下載所有雲端硬碟檔案。
https://www.googleapis.com/auth/drive.activity 查看及新增雲端硬碟檔案的活動記錄。
https://www.googleapis.com/auth/drive.activity.readonly 查看雲端硬碟檔案的活動記錄。
https://www.googleapis.com/auth/drive.meet.readonly 查看 Google Meet 建立或編輯的雲端硬碟檔案。
https://www.googleapis.com/auth/drive.metadata 查看及管理雲端硬碟中檔案的中繼資料。
https://www.googleapis.com/auth/drive.metadata.readonly 查看雲端硬碟中檔案的中繼資料。
https://www.googleapis.com/auth/drive.scripts 修改 Google Apps Script 指令碼的行為。

根據下列定義，上表中的範圍代表其敏感度：

如果應用程式需要存取任何其他 Google API，也可以新增這些範圍。如要進一步瞭解 Google API 範圍，請參閱「使用 OAuth 2.0 存取 Google API」。

如要進一步瞭解特定 OAuth 2.0 範圍，請參閱「Google API 適用的 OAuth 2.0 範圍」。

受限制範圍的資格

只有特定類型的應用程式，才能使用 Google 雲端硬碟的受限範圍。如要符合資格，應用程式必須屬於下列任一類別：

  1. 備份與同步：提供本機同步或自動備份使用者雲端硬碟檔案的平台專用和網路應用程式。

  2. 生產力和教育：主要使用者介面可能涉及與雲端硬碟檔案、中繼資料或權限互動的應用程式。包括工作管理、筆記、工作群組通訊和課堂協作應用程式。

  3. 報表和安全性：這類應用程式可讓使用者或客戶深入瞭解檔案的共用或存取方式。

如要繼續使用受限範圍，請準備應用程式以進行受限範圍驗證。

從受限制的範圍遷移現有應用程式

如果您的雲端硬碟應用程式使用受限制的範圍，建議改用非敏感的 Google Drive API 範圍。使用非機密範圍 (例如 drive.file) 可授予每個檔案的存取權，並限制應用程式只能存取所需特定功能。

許多應用程式都能轉換為檔案存取權，不需進行任何變更。

如果您使用自己的檔案挑選工具，建議改用 Google Picker API，這個 API 完全支援不同範圍。

雲端硬碟檔案範圍的優點

搭配使用 drive.file OAuth 範圍和 Google Picker API，可同時提升應用程式的使用者體驗和安全性。

drive.file OAuth 範圍可讓使用者選擇要與應用程式共用哪些檔案，進一步控管檔案存取權，並確保應用程式只能存取有限的檔案，更加安全。反之，如果要求存取所有雲端硬碟檔案，可能會讓使用者不想與您的應用程式互動。

以下是建議使用 drive.file 範圍的幾個原因：

  • 可用性：drive.file 範圍適用於所有 Drive API REST 資源，因此您可以使用這個範圍，就像使用更廣泛的 OAuth 範圍一樣。

  • 功能：Google Picker API 提供的介面與雲端硬碟 UI 類似。包括顯示雲端硬碟檔案預覽畫面和縮圖的幾個檢視畫面，以及內嵌模式視窗，讓使用者不必離開主要應用程式。

  • 便利性：應用程式使用 Google 挑選器檔案中的篩選器時，可以套用特定雲端硬碟檔案類型 (例如 Google 文件、試算表和相片) 的篩選器。

  • 簡單的驗證程序：由於 drive.file 不屬於敏感資訊，因此驗證程序較為簡化。

安全儲存更新權杖

如要使用 Drive API 存取私人資料，應用程式必須取得可授予該 API 存取權的存取權杖。單一存取權杖可根據您要求的作用域，授予多個 API 不同程度的存取權。

由於存取權杖的效期較短，如要長期存取 Drive API，必須使用更新權杖。應用程式可透過更新權杖要求新的存取權杖。

將更新權杖儲存在安全的長期儲存空間，並在權杖有效期間繼續使用。

詳情請參閱「使用 OAuth 2.0 存取 Google API」。

  • 如要瞭解 Google Workspace 的驗證和授權機制，請參閱「瞭解驗證和授權」。
  • 如需 Google Cloud 驗證和授權的總覽，請參閱驗證總覽。
  • 如要進一步瞭解服務帳戶，請參閱服務帳戶。
  • 如需疑難排解說明，請參閱「解決錯誤」。