API Google Picker

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

Google CHỌN API là một API JavaScript mà bạn có thể sử dụng trong ứng dụng web của mình để cho phép người dùng chọn hoặc tải tệp Google Drive lên. Người dùng có thể cấp cho ứng dụng của bạn quyền truy cập vào Dữ liệu trên Drive, giúp bạn tương tác với các tệp một cách an toàn và được uỷ quyền.

Công cụ chọn của Google hoạt động như một công cụ "Mở tệp" hộp thoại để xem 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ự giao diện người dùng của Google Drive.
  • Một số chế độ xem hiển thị bản xem trước và hình thu nhỏ của các tệp trên Drive.
  • Cửa sổ phương thức 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 Công cụ 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ừ một thư mục sang một thiết bị 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 dùng Bộ chọn của Google phải tuân thủ tất cả ứng dụng hiện có Điều khoản dịch vụ. Quan trọng nhất là bạn phải xác định chính xác của chính bạn trong yêu cầu của mình.

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 API Bộ chọn của Google, 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 các API này 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 Google Cloud.

  • Trong bảng điều khiển Google Cloud, hãy bật API Bộ chọn của Google.

    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, chữ số dấu gạch dưới và dấu gạch nối, chẳng hạn như AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Phương pháp xác thực này được dùng để truy cập ẩn danh công khai dữ liệu, chẳng hạn như các tệp trên Google Workspace được chia sẻ bằng lệnh "Bất kỳ ai trên Internet bằng đường liên kết này" cài đặt cách chia sẻ. Để biết thêm thông tin, hãy xem 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 đăng nhập.

    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 > 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 để dùng trong mã của ứng dụng. Khoá API cũng có thể là có trong "khoá API" trong thông tin đăng nhập của dự án.
    • Nhấp vào Hạn chế khoá để cập nhật các chế độ cài đặt nâng cao và hạn chế việc sử dụng của khoá API. Để biết thêm thông tin, hãy xem phần Áp dụng các quy tắc hạn chế đối với khoá API.

Cấp 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 của mình, bạn cần phải 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 vào 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 Loại ứng dụng > Ứ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 mục 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 về trình duyệt. Phần này xác định các miền mà từ đó ứ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 mục URI chuyển hướng được phép, hãy nhấp vào Thêm URI. Sau đó, 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 OAuth do ứng dụng tạo sẽ xuất hiện, cho biết Mã ứng dụng khách và Mật khẩu ứng dụng mới của bạn.

    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 được 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ã truy cập OAuth 2.0 với các chế độ xem có quyền truy cập 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 bài viết Sử dụng OAuth 2.0 để truy cập API Google.

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

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

Để tải thư viện Google Partners, hãy gọi gapi.load() cùng với tên thư viện và để 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ế đoạn mã 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 bài viết Phạm vi 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 để thao tác với dữ liệu người dùng. Phương thức initTokenClient() sẽ 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 trong Bộ chọn của Google. Chiến lược phát hành đĩa đơn Hàm callback onPickerApiLoad() được gọi sau thư viện Google Inspector tải thành công.

Hiển thị Công cụ chọn của Google

Hàm createPicker() sẽ kiểm tra để đảm bảo API Bộ chọn của Google tải xong và mã thông báo OAuth đã được tạo. Sử dụng Trường setAppId để đặt giá trị Mã ứng dụng Drive để cho phép ứng dụng truy cập vào tệp của người dùng. Sau đó, hàm này sẽ tạo một thực thể của Công cụ chọn của Google và hiển thị thực thể đó:

    // 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)
            .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: ''});
      }
    }
    

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

Đối tượng Picker kết xuất một View tại mỗi thời điểm. Hãy chỉ định ít nhất một chế độ xem bằng cách ViewId (google.​picker.​ViewId.*) hoặc bằng cách tạo một bản sao của một loại (google.​picker.​*View). Chỉ định chế độ xem theo loại để có thêm kiểm soát cách hiển thị khung hiển thị.

Nếu có nhiều chế độ xem được thêm vào Google CHỌN, 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ẻ với các đối tượng ViewGroup theo cách hợp lý.

Triển khai lệnh gọi lại trong Bộ chọn của Google

Bạn có thể dùng một lệnh gọi lại của Google trong Bộ chọn để phản ứng với hoạt động tương tác của người dùng trong Công cụ chọn của Google, chẳng hạn như chọn một tệp hoặc nhấn Cancel (Huỷ). Response đối tượng truyền tải thông tin về 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 nhận đố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, mảng google.picker.Response.DOCUMENTS cũng đượ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 Tài liệu tham khảo về JSON.

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

Hãy dùng ViewGroup để lọc các mục cụ thể. Mã mẫu sau đây biểu thị cách "Google Drive" chế độ xem phụ 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 chế độ xem hợp lệ, hãy truy cập ViewId.

Chỉnh sửa giao diện của Công cụ chọn của Google

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 chế độ xem. Để tinh chỉnh giao diện của cửa sổ Công cụ 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 chế độ xem, bạn có thể ẩn ngăn điều hướng (Feature.NAV_HIDDEN) nhằm giúp người dùng có thêm không gian để xem các mục.

Mã mẫu sau đây là ví dụ về bộ chọn tìm kiếm của bảng tính khi 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 PickerBuilder bằng 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