Google Picker API là một API JavaScript mà bạn có thể sử dụng trong các ứng dụng web để cho phép người dùng chọn hoặc tải tệp lên Google Drive. Người dùng có thể cấp quyền cho các ứng dụng của bạn truy cập vào dữ liệu của họ trên Drive, mang đến một cách thức an toàn và được uỷ quyền để tương tác với các tệp của họ.
Google Picker hoạt động như một hộp thoại "Mở tệp" cho thông tin được lưu trữ trên Drive và có một số tính năng:
- Giao diện tương tự như giao diện người dùng Google Drive.
- Một số chế độ xem cho thấy bản xem trước và hình thu nhỏ của các tệp trên Drive.
- Một cửa sổ phương thức nội tuyến, vì vậy người dùng không bao giờ rời khỏi ứng dụng chính.
Xin lưu ý rằng Google Picker không cho phép người dùng sắp xếp, di chuyển hoặc sao chép tệp từ thư mục này sang thư mục khác. Để quản lý tệp, bạn phải sử dụng API Google Drive hoặc giao diện người dùng Drive.
Điều kiện tiên quyết
Các ứng dụng sử dụng Google Picker phải tuân thủ tất cả Điều khoản dịch vụ hiện hành. Quan trọng nhất là bạn phải xác định chính xác danh tính của mình trong các yêu cầu.
Bạn cũng phải có một dự án trên Google Cloud.
Thiết lập môi trường
Để bắt đầu sử dụng Google Picker API, bạn phải thiết lập môi trường của mình.
Bật API
Trước khi sử dụng API của Google, bạn cần bật các API đó trong một dự án Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án Google Cloud.Trong Google Cloud Console, hãy bật Google Picker API.
Tạo một khoá API
Khoá API là một chuỗi dài chứa các chữ cái viết hoa và viết thường, chữ số, dấu gạch dưới và dấu gạch ngang, chẳng hạn như AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe.
Phương thức xác thực này được dùng để truy cập ẩn danh vào dữ liệu có sẵn công khai, chẳng hạn như các tệp Google Workspace được chia sẻ bằng chế độ cài đặt chia sẻ "Bất kỳ ai có đường liên kết trên Internet". Để biết thêm thông tin chi tiết, hãy xem bài viết Quản lý khoá API.
Cách tạo khoá API:
- Trong bảng điều khiển Google Cloud, hãy chuyển đến phần Trình đơn > API và Dịch vụ > Thông tin xác thực.
- Nhấp vào Tạo thông tin xác thực > Khoá API.
- Khoá API mới của bạn sẽ xuất hiện.
- Nhấp vào biểu tượng Sao chép để sao chép khoá API nhằm sử dụng trong mã của ứng dụng. Bạn cũng có thể tìm thấy khoá API trong phần "Khoá API" của thông tin đăng nhập dự án.
- Để ngăn chặn việc sử dụng trái phép, bạn nên hạn chế nơi và API mà khoá API có thể được dùng. Để biết thêm thông tin chi tiết, hãy xem phần Thêm các quy tắc hạn chế đối với API.
Uỷ quyền thông tin đăng nhập cho một ứng dụng web
Để xác thực người dùng cuối và truy cập vào dữ liệu người dùng trong ứng dụng của mình, bạn cần tạo một hoặc nhiều Mã ứng dụng OAuth 2.0. Mã ứng dụng khách được dùng để xác định một ứng dụng duy nhất cho các máy chủ OAuth của Google. Nếu ứng dụng của bạn chạy trên nhiều nền tảng, bạn phải tạo một mã nhận dạng ứng dụng riêng cho mỗi nền tảng.- Ứng dụng phía máy khách (JavaScript) – Trong phần Nguồn gốc JavaScript được uỷ quyền, hãy nhấp vào Thêm URI. Sau đó, hãy nhập một URI để sử dụng cho các yêu cầu của trình duyệt. Tham số này xác định những miền mà ứng dụng của bạn có thể gửi yêu cầu API đến máy chủ OAuth 2.0.
- Ứng dụng phía máy chủ (Java, Python và các ứng dụng khác) – Trong mục URI chuyển hướng được uỷ quyền, hãy nhấp vào Thêm URI. Sau đó, hãy nhập một URI điểm cuối mà máy chủ OAuth 2.0 có thể gửi phản hồi đến.
Thông tin xác thực mới tạo sẽ xuất hiện trong phần Mã ứng dụng OAuth 2.0.
Ghi lại Mã ứng dụng khách. Khoá bí mật ứng dụng không được dùng cho các ứng dụng Web.
Lưu ý quan trọng: Ứng dụng của bạn phải gửi mã truy cập OAuth 2.0 cùng với những khung hiển thị truy cập vào dữ liệu riêng tư của người dùng khi tạo một đối tượng Picker. Để yêu cầu mã truy cập, hãy xem phần Sử dụng OAuth 2.0 để truy cập vào API Google.
Quản lý Công cụ chọn của Google
Phần còn lại của hướng dẫn này trình bày cách tải và hiển thị Google Picker từ một ứng dụng web, cũng như cách triển khai lệnh gọi lại. Để xem ví dụ đầy đủ, hãy xem Mã mẫu cho ứng dụng web.
Tải thư viện Google Picker
Để tải thư viện Google Picker, hãy gọi gapi.load bằng tên thư viện và một hàm gọi lại để gọi sau khi tải thành công:
<script>
let tokenClient;
let accessToken = null;
let pickerInited = false;
let gisInited = false;
// Use the API Loader script to load google.picker.
function onApiLoad() {
gapi.load('picker', onPickerApiLoad);
}
function onPickerApiLoad() {
pickerInited = true;
}
function gisLoaded() {
// Replace with your client ID and required scopes.
tokenClient = google.accounts.oauth2.initTokenClient({
client_id: 'CLIENT_ID',
scope: 'SCOPES',
callback: '', // defined later
});
gisInited = true;
}
</script>
<!-- Load the Google API Loader script. -->
<script async defer src="https://apis.google.com/js/api.js" onload="onApiLoad()"></script>
<script async defer src="https://accounts.google.com/gsi/client" onload="gisLoaded()"></script>
Thay thế nội dung sau:
CLIENT_ID: Mã ứng dụng khách của ứng dụng web.SCOPES: Một hoặc nhiều phạm vi OAuth 2.0 mà bạn cần yêu cầu để truy cập vào các API của Google, tuỳ thuộc vào cấp độ truy cập mà bạn cần. Để biết thêm thông tin, hãy xem Phạm vi OAuth 2.0 cho các API của Google.
Thư viện JavaScript google.accounts.oauth2 giúp bạn nhắc người dùng đồng ý và lấy mã truy cập để xử lý dữ liệu người dùng. Phương thức initTokenClient khởi tạo một ứng dụng mã thông báo mới bằng mã ứng dụng khách của ứng dụng web. Để biết thêm thông tin, hãy xem phần Sử dụng mô hình mã thông báo.
Hàm onApiLoad tải các thư viện Google Picker. Hàm callback onPickerApiLoad được gọi sau khi thư viện Google Picker tải thành công.
Lưu ý: Nếu đang dùng TypeScript, bạn có thể cài đặt @types/google.picker để dùng window.google.picker. Để báo cáo vấn đề với các loại này, hãy mở một phiếu yêu cầu hỗ trợ.
Hiển thị Google Picker
Hàm createPicker đảm bảo Google Picker API hoàn tất quá trình tải và mã thông báo OAuth 2.0 được tạo. Dùng phương thức PickerBuilder.setAppId để đặt Mã ứng dụng Drive bằng số dự án trên đám mây nhằm cho phép ứng dụng truy cập vào các tệp của người dùng. Sau đó, hàm này sẽ tạo một phiên bản của Google Picker và hiển thị phiên bản đó:
// Create and render a Google Picker object for selecting from Drive.
function createPicker() {
const showPicker = () => {
// Replace with your API key and App ID.
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.DOCS)
.setOAuthToken(accessToken)
.setDeveloperKey('API_KEY')
.setCallback(pickerCallback)
.setAppId('APP_ID')
.build();
picker.setVisible(true);
}
// Request an access token.
tokenClient.callback = async (response) => {
if (response.error !== undefined) {
throw (response);
}
accessToken = response.access_token;
showPicker();
};
if (accessToken === null) {
// Prompt the user to select a Google Account and ask for consent to share their data
// when establishing a new session.
tokenClient.requestAccessToken({prompt: 'consent'});
} else {
// Skip display of account chooser and consent dialog for an existing session.
tokenClient.requestAccessToken({prompt: ''});
}
}
Thay thế nội dung sau:
API_KEY: Khoá API của bạn.APP_ID: Số dự án của bạn trên Cloud.
Để tạo một phiên bản Google Picker, bạn phải tạo một đối tượng Picker bằng cách sử dụng PickerBuilder. PickerBuilder nhận một View, một mã thông báo OAuth 2.0, một khoá dành cho nhà phát triển và một hàm gọi lại để gọi khi thành công (pickerCallback).
Đối tượng Picker kết xuất một View tại một thời điểm. Chỉ định ít nhất một khung hiển thị, bằng cách ViewId (google.picker.ViewId.*) hoặc bằng cách tạo một thực thể DocsView để có thêm quyền kiểm soát cách khung hiển thị được kết xuất.
Nếu có nhiều chế độ xem được thêm vào Google Picker, người dùng có thể chuyển từ chế độ xem này sang chế độ xem khác bằng cách nhấp vào một thẻ ở bên trái. Bạn có thể nhóm các thẻ một cách hợp lý bằng các đối tượng ViewGroup.
Để xem danh sách các khung hiển thị hợp lệ, hãy xem ViewId trong tài liệu tham khảo về Google Picker. Để lấy mã thông báo cho bất kỳ khung hiển thị nào trong số này, hãy sử dụng phạm vi https://www.googleapis.com/auth/drive.file.
Triển khai lệnh gọi lại Google Picker
Bạn có thể dùng một lệnh gọi lại Google Picker để phản hồi các hoạt động tương tác của người dùng trong Google Picker, chẳng hạn như chọn một tệp hoặc nhấn vào nút Huỷ. Giao diện ResponseObject truyền tải thông tin về lựa chọn của người dùng.
// A callback implementation.
function pickerCallback(data) {
let url = 'nothing';
if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
const doc = data[google.picker.Response.DOCUMENTS][0];
url = doc[google.picker.Document.URL];
}
const message = `You picked: ${url}`;
document.getElementById('result').textContent = message;
}
Lệnh gọi lại nhận được một đối tượng dữ liệu được mã hoá JSON. Đối tượng này chứa một Action mà người dùng thực hiện bằng Google Picker (google.picker.Response.ACTION). Nếu người dùng chọn một mục, mảng google.picker.Response.DOCUMENTS cũng sẽ được điền sẵn. Trong ví dụ này, google.picker.Document.URL xuất hiện trên trang chính. Để biết thông tin chi tiết về các trường dữ liệu, hãy xem giao diện ResponseObject.
Lọc các loại tệp cụ thể
Sử dụng ViewGroup làm cách lọc các mục cụ thể. Đoạn mã mẫu sau đây cho thấy cách khung hiển thị phụ "Drive" chỉ hiển thị tài liệu và bản trình bày.
const picker = new google.picker.PickerBuilder()
.addViewGroup(
new google.picker.ViewGroup(google.picker.ViewId.DOCS)
.addView(google.picker.ViewId.DOCUMENTS)
.addView(google.picker.ViewId.PRESENTATIONS))
.setOAuthToken(oauthToken)
.setDeveloperKey(developerKey)
.setAppId(cloudProjectNumber)
.setCallback(pickerCallback)
.build();
Để biết danh sách các loại khung hiển thị hợp lệ, hãy xem ViewId.
Điều chỉnh giao diện của Google Picker
Bạn có thể dùng đối tượng Feature để bật hoặc tắt các tính năng cho nhiều khung hiển thị. Để tinh chỉnh giao diện của cửa sổ Google Picker, hãy sử dụng phương thức PickerBuilder.enableFeature hoặc PickerBuilder.disableFeature. Ví dụ: nếu chỉ có một chế độ xem, bạn có thể muốn ẩn ngăn điều hướng (Feature.NAV_HIDDEN) để người dùng có thêm không gian xem các mục.
Mẫu mã sau đây cho thấy ví dụ về bộ chọn tìm kiếm của bảng tính bằng cách sử dụng tính năng này:
const picker = new google.picker.PickerBuilder()
.addView(google.picker.ViewId.SPREADSHEETS)
.enableFeature(google.picker.Feature.NAV_HIDDEN)
.setDeveloperKey(developerKey)
.setCallback(pickerCallback)
.build();