Tài liệu này giải thích cách tích hợp Google Picker vào các ứng dụng web của bạn bằng Google Picker API.
Google Picker API là một API JavaScript mà bạn có thể triển khai để cho phép người dùng chọn hoặc tải tệp lên Google Drive bằng Google Picker. 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ọ.
Tính năng
Bộ chọn của Google 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.
- Chế độ xem được lọc trước chỉ hiển thị các loại tệp cụ thể (như PDF hoặc hình ảnh) hoặc một số thư mục.
- 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 mặc dù bạn có thể chọn và tải tệp lên bằng Google Picker, nhưng công cụ này 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.
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 trên Google Cloud. Bạn có thể bật một hoặc nhiều API trong một dự án trên Google Cloud.Trong bảng điều khiển Cloud, hãy bật Google Picker API.
Tạo một khoá API
Khoá API là một chuỗi dài chứa chữ cái viết hoa và viết thường, 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ông khai, chẳng hạn như các tệp trên Google Workspace được chia sẻ bằng chế độ chia sẻ "Bất kỳ ai có đường liên kết này 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 xác thực 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 khách 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ã ứng dụng khách riêng cho mỗi nền tảng.- Trong Google API Console, hãy chuyển đến phần Trình đơn > Nền tảng Xác thực của Google > Ứng dụng.
- Nhấp vào Tạo ứng dụng.
- Nhấp vào Loại ứng dụng > Ứng dụng web.
- Trong trường Name (Tên), hãy nhập tên cho thông tin đăng nhập. Tên này chỉ xuất hiện trong Google API Console.
- Thêm các URI được uỷ quyền liên quan đến ứng dụng của bạn:
- Ứ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.
- Nhấp vào Tạo.
Thông tin xác thực mới tạo sẽ xuất hiện trong phần Mã ứng dụng khách OAuth 2.0.
Xin lưu ý rằng 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 các khung hiển thị truy cập vào dữ liệu người dùng riêng tư khi tạo đố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 các API của Google.
Quản lý Công cụ chọn của Google
Phần còn lại của tài liệu 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 mẫu mã đầy đủ, hãy xem phần Sử dụng các tính năng của Google Picker API trong ứ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 callback để 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ần 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
Để tạo một phiên bản Google Picker, bạn phải tạo một đối tượng Picker bằng PickerBuilder. PickerBuilder nhận một View, mã thông báo OAuth 2.0, khoá nhà phát triển và một hàm callback để gọi khi thành công (pickerCallback).
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 trên đám mây của bạn.
Đối tượng Picker hiển thị 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ể của 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 khung hiển thị được thêm vào Google Picker, người dùng có thể chuyển đổi giữa các khung hiển thị 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 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, thì mảng docs 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ề tất cả các thuộc tính, hãy xem giao diện ResponseObject.
Lọc các loại tệp cụ thể
Sử dụng ViewGroup để 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. Bạn cũng có thể dùng đối tượng DocsView cho các lựa chọn lọc bổ sung.
Đ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();
Chủ đề có liên quan
- Mã mẫu: Sử dụng các tính năng của Google Picker API trong ứng dụng web
- Sử dụng thành phần web Google Picker
- Chọn phạm vi của API Google Drive