選擇 Google Drive API 範圍

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

設定授權所需的 OAuth 2.0

設定 OAuth 同意畫面並選擇範圍,定義要向使用者顯示的資訊及應用程式審查者,並註冊應用程式以供日後發布。

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/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.metadata 查看及管理雲端硬碟中的檔案中繼資料。 受限制
https://www.googleapis.com/auth/drive.metadata.readonly 查看雲端硬碟中的檔案中繼資料。 受限制
https://www.googleapis.com/auth/drive.scripts 修改 Google Apps Script 指令碼的行為。 受限制

上表中的「使用情形」欄根據下列定義,指出每個範圍的機密程度:

  • 建議 / 非機密:這些範圍提供的最低授權存取權範圍,並且只需要基本應用程式驗證。如要瞭解這項規定,請參閱「驗證準備步驟」。

  • 建議 / 機密:這些範圍可讓您存取使用者為應用程式授權的特定 Google 使用者資料,因此您必須完成額外的應用程式驗證。如要進一步瞭解這項規定,請參閱「要求機密範圍的應用程式適用步驟」。

  • 受限制:這些範圍可廣泛存取 Google 使用者資料,並要求您完成受限制範圍的驗證程序。如要瞭解這項規定,請參閱 Google API 服務使用者資料政策特定 API 範圍的其他規定。如果您在伺服器 (或傳輸) 上儲存受限制的範圍資料,則必須通過安全性評估。

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

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

OAuth 驗證

使用特定 OAuth 範圍時,您可能需要讓應用程式完成 Google 的 OAuth 驗證程序。請參閱 OAuth API 驗證常見問題,瞭解應用程式應在何時進行驗證,以及需要哪種驗證。另請參閱《Google 雲端硬碟服務條款》。

使用受限制範圍的時機

如果是雲端硬碟,只有下列應用程式類型可以存取受限範圍:

  1. 提供本機同步或自動備份使用者雲端硬碟檔案的平台專屬和網頁應用程式。
  2. 效率提升和教育應用程式的使用者介面,可能涉及與雲端硬碟檔案 (或其中繼資料或權限) 互動。效率提升應用程式包括工作管理、筆記、工作小組通訊和課堂協作應用程式。
  3. 提供報表與安全性應用程式,讓使用者或客戶瞭解檔案的共用或存取方式。

如要繼續使用受限制的範圍,請為應用程式做好受限制範圍的驗證準備

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

如果您已使用任何受限制範圍開發雲端硬碟應用程式,建議您遷移應用程式,改為使用非機密範圍,因為應用程式會授予個別檔案的存取權範圍,並限制應用程式所需的特定功能存取權。許多應用程式都可以使用個別檔案存取權,而不需要進行任何變更。如果您使用自己的檔案選擇器,建議您改用完全支援不同範圍的 Google Picker API。

drive.file OAuth 範圍的優點

使用 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 非敏感性,因此可簡化驗證程序。

儲存更新權杖

將更新權杖儲存在安全的長期儲存空間中,只要這些權杖仍有效,即可繼續使用。