Chọn phạm vi API Google Drive

Tài liệu này chứa thông tin uỷ quyền và xác thực dành riêng cho Google Drive API. Trước khi đọc tài liệu này, hãy nhớ đọc thông tin chung về quy trình xác thực và uỷ quyền của Google Workspace tại Tìm hiểu về quy trình xác thực và uỷ quyền.

Định cấu hình OAuth 2.0 để uỷ quyền

Để uỷ quyền cho ứng dụng, Google Drive API yêu cầu bạn xác định các phạm vi OAuth ở hai nơi: Google Cloud Console và ứng dụng của bạn.

Trong Google Cloud Console, bạn phải khai báo các phạm vi mà ứng dụng của bạn cần trong cấu hình màn hình xin phép bằng OAuth. Đây là cấp độ quyền cao nhất mà ứng dụng của bạn có thể yêu cầu. Đây là yêu cầu chính thức gửi đến Google và các phạm vi đã khai báo là những gì Google hiển thị cho người dùng trên màn hình yêu cầu sự đồng ý. Nhờ đó, người dùng có thể hiểu chính xác những dữ liệu và hành động mà ứng dụng của bạn đang yêu cầu quyền truy cập.

Định cấu hình màn hình đồng ý OAuth và chọn phạm vi để xác định thông tin sẽ hiển thị cho người dùng và người đánh giá ứng dụng, đồng thời đăng ký ứng dụng để bạn có thể xuất bản ứng dụng sau này.

Trong ứng dụng, khi khởi chạy API, bạn phải yêu cầu rõ ràng các phạm vi cụ thể mà bạn cần cho phiên đó. Mặc dù Google Cloud Console xác định cấp cao nhất của các quyền mà ứng dụng của bạn được phép yêu cầu, nhưng mã sẽ xác định các quyền thực tế cho một người dùng nhất định. Điều này giúp đảm bảo rằng ứng dụng chỉ yêu cầu các quyền cần thiết cho một tác vụ cụ thể.

Bạn có thể khai báo một hoặc nhiều phạm vi OAuth cùng một lúc trong mã của ứng dụng dưới dạng một mảng.

Mẫu mã sau đây cho biết cách khai báo nhiều phạm vi 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'
];

Để xem cách các phạm vi được khai báo và sử dụng trong một mẫu mã đầy đủ, hãy xem phần Bắt đầu nhanh.

Phạm vi Drive API

Để xác định cấp truy cập được cấp cho ứng dụng của bạn, bạn cần xác định và khai báo phạm vi uỷ quyền. Phạm vi uỷ quyền là một chuỗi URI OAuth 2.0 chứa tên ứng dụng Google Workspace, loại dữ liệu mà ứng dụng đó truy cập và cấp độ truy cập. Phạm vi là các yêu cầu của ứng dụng để xử lý dữ liệu trên Google Workspace, bao gồm cả dữ liệu Tài khoản Google của người dùng.

Khi ứng dụng của bạn được cài đặt, người dùng sẽ được yêu cầu xác thực các phạm vi mà ứng dụng sử dụng. Nói chung, bạn nên chọn phạm vi tập trung hẹp nhất có thể và tránh yêu cầu các phạm vi mà ứng dụng của bạn không cần. Người dùng sẵn sàng cấp quyền truy cập vào các phạm vi có giới hạn và được mô tả rõ ràng.

Bất cứ khi nào có thể, hãy sử dụng các phạm vi không nhạy cảm vì chúng cấp quyền truy cập cho từng tệp và thu hẹp quyền truy cập vào các tính năng cụ thể mà ứng dụng cần.

Phạm vi không nhạy cảm

Bạn nên dùng các phạm vi Drive API sau đây cho hầu hết các trường hợp sử dụng:

Mã phạm vi Mô tả
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.appfolder		 Xem và quản lý dữ liệu cấu hình riêng của ứng dụng trong Google Drive.
https://www.googleapis.com/auth/drive.install Cho phép các ứng dụng xuất hiện dưới dạng một lựa chọn trong trình đơn "Mở bằng" hoặc "Mới".
https://www.googleapis.com/auth/drive.file Tạo tệp mới trên Drive hoặc sửa đổi tệp hiện có mà bạn mở bằng một ứng dụng hoặc người dùng chia sẻ với một ứng dụng trong khi sử dụng Google Picker API hoặc trình chọn tệp của ứng dụng.

Phạm vi nhạy cảm

Mã phạm vi Mô tả
https://www.googleapis.com/auth/drive.apps.readonly Xem những ứng dụng được phép truy cập vào Drive của bạn.

Phạm vi bị hạn chế

Mã phạm vi Mô tả
https://www.googleapis.com/auth/drive Xem và quản lý tất cả tệp của bạn trên Drive.
https://www.googleapis.com/auth/drive.readonly Xem và tải tất cả tệp của bạn trên Drive xuống.
https://www.googleapis.com/auth/drive.activity Xem và thêm vào hồ sơ hoạt động của các tệp trong Drive.
https://www.googleapis.com/auth/drive.activity.readonly Xem hồ sơ hoạt động của các tệp trong Drive.
https://www.googleapis.com/auth/drive.meet.readonly Xem các tệp trên Drive do Google Meet tạo hoặc chỉnh sửa.
https://www.googleapis.com/auth/drive.metadata Xem và quản lý siêu dữ liệu của các tệp trong Drive.
https://www.googleapis.com/auth/drive.metadata.readonly Xem siêu dữ liệu của các tệp trong Drive.
https://www.googleapis.com/auth/drive.scripts Sửa đổi hoạt động của các tập lệnh Google Apps Script.

Các phạm vi trong bảng trước cho biết mức độ nhạy cảm của chúng, theo các định nghĩa sau:

Nếu ứng dụng của bạn cần quyền truy cập vào bất kỳ API nào khác của Google, bạn cũng có thể thêm các phạm vi đó. Để biết thêm thông tin về các phạm vi API của Google, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.

Để biết thêm thông tin về các phạm vi OAuth 2.0 cụ thể, hãy xem Phạm vi OAuth 2.0 cho các API của Google.

Điều kiện để sử dụng phạm vi bị hạn chế

Chỉ một số loại ứng dụng cụ thể mới được phép sử dụng các phạm vi bị hạn chế cho Google Drive. Để đủ điều kiện, ứng dụng của bạn phải thuộc một trong các danh mục sau:

  1. Sao lưu và đồng bộ hoá: Các ứng dụng dành riêng cho nền tảng và ứng dụng web cung cấp tính năng đồng bộ hoá cục bộ hoặc tự động sao lưu các tệp của người dùng trên Drive.

  2. Năng suất và giáo dục: Ứng dụng có giao diện người dùng chính có thể liên quan đến việc tương tác với tệp, siêu dữ liệu hoặc quyền trên Drive. Các ứng dụng này bao gồm ứng dụng quản lý công việc, ghi chú, giao tiếp nhóm làm việc và cộng tác trong lớp học.

  3. Báo cáo và bảo mật: Ứng dụng cung cấp thông tin chi tiết cho người dùng hoặc khách hàng về cách chia sẻ hoặc truy cập vào tệp.

Để tiếp tục sử dụng các phạm vi bị hạn chế, bạn nên chuẩn bị ứng dụng của mình cho quy trình xác minh phạm vi bị hạn chế.

Di chuyển một ứng dụng hiện có khỏi các phạm vi bị hạn chế

Nếu ứng dụng Drive của bạn sử dụng các phạm vi bị hạn chế, bạn nên di chuyển sang một phạm vi API Drive không nhạy cảm. Việc sử dụng các phạm vi không nhạy cảm, chẳng hạn như drive.file, sẽ cấp quyền truy cập hẹp và theo từng tệp cho các tính năng cụ thể mà một ứng dụng cần.

Nhiều ứng dụng có thể chuyển sang quyền truy cập vào từng tệp mà không cần thay đổi gì.

Nếu đang sử dụng công cụ chọn tệp của riêng mình, bạn nên chuyển sang Google Picker API. API này hỗ trợ đầy đủ các phạm vi.

Lợi ích của phạm vi tệp trên Drive

Việc sử dụng phạm vi OAuth drive.file kết hợp với Google Picker API sẽ tối ưu hoá cả trải nghiệm người dùng và độ an toàn cho ứng dụng của bạn.

Phạm vi drive.file OAuth cho phép người dùng chọn những tệp mà họ muốn chia sẻ với ứng dụng của bạn. Điều này giúp họ có nhiều quyền kiểm soát hơn và yên tâm rằng quyền truy cập của ứng dụng vào tệp của họ bị hạn chế và an toàn hơn. Ngược lại, việc yêu cầu quyền truy cập rộng rãi vào tất cả các tệp trên Drive có thể khiến người dùng không muốn tương tác với ứng dụng của bạn.

Sau đây là một số lý do bạn nên sử dụng phạm vi drive.file:

  • Khả năng sử dụng: Phạm vi drive.file hoạt động với tất cả Tài nguyên REST của Drive API, nghĩa là bạn có thể sử dụng phạm vi này theo cách tương tự như khi sử dụng các phạm vi OAuth rộng hơn.

  • Tính năng: Google Picker API cung cấp một giao diện tương tự như giao diện người dùng Drive. Điều này bao gồm một số khung hiển thị cho thấy bản xem trước và hình thu nhỏ của các tệp trên Drive, cũng như một cửa sổ phương thức nội tuyến để người dùng không bao giờ rời khỏi ứng dụng chính.

  • Tiện lợi: Các ứng dụng có thể áp dụng bộ lọc cho một số loại tệp nhất định trên Drive (chẳng hạn như Google Tài liệu, Trang tính và ảnh) khi sử dụng bộ lọc trên các tệp của Google Picker.

  • Quy trình xác minh đơn giản: Vì drive.file không phải là thông tin nhạy cảm nên quy trình xác minh sẽ tinh giản hơn.

Lưu trữ mã làm mới một cách an toàn

Để truy cập vào dữ liệu riêng tư bằng Drive API, ứng dụng của bạn phải lấy được mã truy cập cấp quyền truy cập vào API đó. Một mã truy cập duy nhất có thể cấp nhiều mức độ truy cập vào nhiều API, được điều chỉnh theo các phạm vi mà bạn yêu cầu.

Vì mã truy cập chỉ tồn tại trong thời gian ngắn, nên bạn phải sử dụng mã làm mới để truy cập vào Drive API trong thời gian dài. Mã làm mới cho phép ứng dụng của bạn yêu cầu mã truy cập mới.

Lưu mã làm mới trong bộ nhớ dài hạn, an toàn và tiếp tục sử dụng chúng chừng nào chúng còn hợp lệ.

Để biết thêm thông tin, hãy xem bài viết Sử dụng OAuth 2.0 để truy cập vào các API của Google.