API Google Picker

Hộp thoại Bộ chọn của Google.

Google Picker API là API JavaScript mà bạn có thể dùng trong các ứng dụng web để cho phép người dùng chọn hoặc tải tệp trên Google Drive lên. 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 trên Drive của họ, mang đến cho họ một cách thức an toàn và được uỷ quyền để tương tác với các tệp.

Bộ chọn của Google hoạt động như một hộp thoại "File Open" (Mở tệp) cho thông tin được lưu trữ trên Drive và có các tính năng sau:

  • Giao diện tương tự như giao diện người dùng của Google Drive.
  • Một số chế độ xem cho thấy bản xem trước và hình thu nhỏ của tệp trên Drive.
  • Một cửa sổ cửa sổ cùng dòng, do đó người dùng không bao giờ rời khỏi ứng dụng chính.

Xin lưu ý rằng Bộ chọn của Google không cho phép người dùng sắp xếp, di chuyển hoặc sao chép các tệp từ thư mục này sang thư mục khác. Để làm việc đó, bạn có thể sử dụng API Google Drive hoặc giao diện người dùng Drive.

Yêu cầu về đơn đăng ký

Các ứng dụng sử dụng Bộ chọn của Google phải tuân thủ tất cả Điều khoản dịch vụ hiện có. Quan trọng nhất là bạn phải xác định chính xác bản thân 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 các API của Google, bạn cần bật những 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 Google Cloud, hãy bật Google Picker API.

    Bật 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 nối, chẳng hạn như AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Phương thức xác thực này 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ế độ cài đặt chia sẻ "Bất kỳ ai trên Internet có đường liên kết này". Để biết thêm thông tin chi tiết, hãy xem bài viết Xác thực bằng cách sử dụng khoá API.

Cách tạo khoá API:

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > API và dịch vụ > Thông tin xác thực.

    Chuyển đến phần Thông tin xác thực

  2. Nhấp vào Create credentials (Tạo thông tin xác thực) > API key (Khoá API).
  3. 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" trong thông tin xác thực của dự án.
    • Nhấp vào Restrict key (Hạn chế khoá) để cập nhật chế độ cài đặt nâng cao và hạn chế việc sử dụng khoá API. Để biết thêm thông tin chi tiết, hãy xem phần Áp dụng các hạn chế đối với khoá API.

Ủy quyền thông tin đăng nhập cho ứ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, 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 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 từng nền tảng.

  1. Trong bảng điều khiển Google Cloud, hãy chuyển đến Trình đơn > API và dịch vụ > Thông tin xác thực.

    Chuyển đến phần Thông tin xác thực

  2. Nhấp vào Tạo thông tin xác thực > Mã ứng dụng khách OAuth.
  3. Nhấp vào Application type (Loại ứng dụng) > Web application (Ứng dụng web).
  4. Trong trường Tên, nhập tên cho thông tin đăng nhập. Tên này chỉ hiển thị trong bảng điều khiển Google Cloud.
  5. Thêm 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 cho phép, hãy nhấp vào Thêm URI. Sau đó, nhập URI để sử dụng cho các yêu cầu của trình duyệt. Mã này xác định các 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.v.) – Trong phần URI chuyển hướng được uỷ quyền, hãy nhấp vào Thêm URI. Sau đó, hãy nhập URI điểm cuối mà máy chủ OAuth 2.0 có thể gửi phản hồi.
  6. Nhấp vào Tạo. Màn hình ứng dụng OAuth đã tạo sẽ xuất hiện, cho thấy Mã ứng dụng khách và Mật khẩu ứng dụng khách mới.

    Ghi lại Mã ứng dụng khách. Mật khẩu ứng dụng khách không được dùng cho các ứng dụng web.

  7. Nhấp vào OK. Thông tin đăng nhập mới tạo sẽ xuất hiện trong phần Mã ứng dụng OAuth 2.0.
Lưu ý quan trọng: Ứng dụng của bạn phải gửi một mã truy cập OAuth 2.0 với các khung hiển thị truy cập vào dữ liệu riêng tư của người dùng 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 API Google.

Hiển thị Bộ 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ị Bộ chọn của Google trong một ứng dụng web. Để xem ví dụ đầy đủ, hãy chuyển đến mã mẫu Bộ chọn của Google.

Tải thư viện Bộ chọn của Google

Để tải thư viện Bộ chọn của Google, hãy gọi gapi.load() kèm theo 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() {
        // TODO(developer): 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ế các đoạn mã sau:

  • CLIENT_ID: Mã ứng dụng khách của ứng dụng web của bạn.
  • 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 Các phạm vi của OAuth 2.0 cho API 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 để làm việc với dữ liệu người dùng. Phương thức initTokenClient() khởi chạy 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 Bộ chọn của Google tải thành công.

Hiển thị Bộ chọn của Google

Hàm createPicker() dưới đây sẽ kiểm tra để đảm bảo rằng Google Picker API đã tải xong và mã thông báo OAuth đã được tạo. Sau đó, hàm này sẽ tạo một thực thể của Bộ chọn của Google và hiển thị bản sao đó:

    // Create and render a Google Picker object for selecting from Drive.
    function createPicker() {
      const showPicker = () => {
        // TODO(developer): Replace with your API key
        const picker = new google.picker.PickerBuilder()
            .addView(google.picker.ViewId.DOCS)
            .setOAuthToken(accessToken)
            .setDeveloperKey('API_KEY')
            .setCallback(pickerCallback)
            .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: ''});
      }
    }
    

Để tạo một thực thể của Google Picker, bạn phải tạo đối tượng Picker bằng cách sử dụng PickerBuilder. PickerBuilder sẽ lấy View, mã thông báo OAuth, khoá nhà phát triển và hàm callback để gọi thành công (pickerCallback).

Đối tượng Picker kết xuất mỗi lần một View. Hãy 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 một loại (google.​picker.​*View). Hãy chỉ định khung hiển thị theo loại để kiểm soát thêm cách kết xuất khung hiển thị.

Nếu có nhiều khung hiển thị được thêm vào Bộ chọn của Google, thì người dùng có thể chuyển từ khung hiển thị này sang khung hiển thị 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ẻ theo cách hợp lý với đối tượng ViewGroup.

Triển khai lệnh gọi lại trong Google Picker

Bạn có thể dùng lệnh gọi lại Bộ chọn của Google để phản ứng với các hoạt động tương tác của người dùng trong Bộ chọn của Google, chẳng hạn như chọn một tệp hoặc nhấn vào Huỷ. Đối tượng Response truyền tải thông tin về các lựa chọn của người dùng.

    // A simple callback implementation.
    function pickerCallback(data) {
      let url = 'nothing';
      if (data[google.picker.Response.ACTION] == google.picker.Action.PICKED) {
        let doc = data[google.picker.Response.DOCUMENTS][0];
        url = doc[google.picker.Document.URL];
      }
      let message = `You picked: ${url}`;
      document.getElementById('result').innerText = message;
    }
    

Lệnh gọi lại sẽ nhận được đối tượng data đượ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 Công cụ chọn của Google (google.picker.Response.ACTION). Nếu người dùng chọn một mục Document, thì mảng google.picker.Response.DOCUMENTS cũng sẽ được điền. Trong ví dụ này, google.picker.Document.URL được hiển thị trên trang chính. Để biết thông tin chi tiết về các trường dữ liệu, hãy tham khảo Tài liệu tham khảo JSON.

Lọc loại tệp cụ thể

Bạn có thể sử dụng ViewGroup để lọc ra các mục cụ thể. Mã mẫu sau đây cho thấy cách chế độ xem phụ "Google Drive" chỉ hiển thị tài liệu và bản trình bày.

    let 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)
        .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ổ Bộ chọn của Google, hãy sử dụng hàm PickerBuilder.enableFeature() hoặc PickerBuilder.disableFeature(). Ví dụ: nếu chỉ có một khung hiển thị, bạn nê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ã mẫu sau đây cho thấy ví dụ về bộ chọn tìm kiếm của một bảng tính sử dụng tính năng này:

     let picker = new google.picker.PickerBuilder()
         .addView(google.picker.ViewId.SPREADSHEETS)
         .enableFeature(google.picker.Feature.NAV_HIDDEN)
         .setDeveloperKey(developerKey)
         .setCallback(pickerCallback)
         .build();
     

Hiển thị Bộ chọn của Google bằng các ngôn ngữ khác

Chỉ định ngôn ngữ giao diện người dùng bằng cách cung cấp ngôn ngữ cho thực thể PickerBuilder thông qua phương thức setLocale(locale).

Mã mẫu sau đây cho biết cách đặt ngôn ngữ thành tiếng Pháp:

    let picker = new google.picker.PickerBuilder()
        .addView(google.picker.ViewId.IMAGE_SEARCH)
        .setLocale('fr')
        .setDeveloperKey(developerKey)
        .setCallback(pickerCallback)
        .build();
    

Sau đây là danh sách các ngôn ngữ hiện được hỗ trợ:

af
am
ar
bg
bn
ca
cs
da
de
el
en
en-GB
es
es-419
et
eu
fa
fi
fil
fr
fr-CA
gl
gu
hi
hr
hu
id
is
it
iw
ja
kn
ko
lt
lv
ml
mr
ms
nl
no
pl
pt-BR
pt-PT
ro
ru
sk
sl
sr
sv
sw
ta
te
th
tr
uk
ur
vi
zh-CN
zh-HK
zh-TW
zu