Google Picker API

Dialog Pemilih Google.

Google Picker API adalah JavaScript API yang dapat Anda gunakan di aplikasi web untuk memungkinkan pengguna memilih atau mengupload file Google Drive. Pengguna dapat memberikan izin ke aplikasi Anda untuk mengakses data Drive mereka, yang memberikan cara yang aman dan sah untuk berinteraksi dengan file mereka.

Pemilih Google berfungsi sebagai dialog "File Dibuka" untuk informasi yang disimpan di Drive dan memiliki fitur berikut:

  • Tampilan dan nuansa yang serupa dengan UI Google Drive.
  • Beberapa tampilan menampilkan pratinjau dan gambar thumbnail file Drive.
  • Jendela modal inline, sehingga pengguna tidak pernah meninggalkan aplikasi utama.

Perhatikan bahwa Alat Pilih Google tidak memungkinkan pengguna untuk mengatur, memindahkan, atau menyalin file dari satu folder ke folder lain. Untuk melakukannya, Anda dapat menggunakan Google Drive API atau UI Drive.

Persyaratan permohonan

Aplikasi yang menggunakan Alat Pilih Google harus mematuhi semua Persyaratan Layanan yang ada. Yang terpenting, Anda harus mengidentifikasi diri Anda dengan benar dalam permintaan Anda.

Anda juga harus memiliki project Google Cloud.

Menyiapkan lingkungan Anda

Untuk mulai menggunakan Google Picker API, Anda harus menyiapkan lingkungan Anda.

Mengaktifkan API

Sebelum menggunakan Google API, Anda harus mengaktifkannya di project Google Cloud. Anda dapat mengaktifkan satu atau beberapa API dalam satu project Google Cloud.

Membuat Kunci API

Kunci API adalah string panjang yang berisi huruf besar dan kecil, angka, garis bawah, dan tanda hubung, seperti AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Metode autentikasi ini digunakan untuk mengakses data yang tersedia untuk publik secara anonim, seperti file Google Workspace yang dibagikan menggunakan setelan berbagi "Siapa saja di internet yang memiliki link ini". Untuk mengetahui detail selengkapnya, lihat Mengautentikasi menggunakan kunci API.

Untuk membuat kunci API:

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Create credentials > API key.
  3. Kunci API baru Anda akan ditampilkan.
    • Klik Salin untuk menyalin kunci API untuk digunakan dalam kode aplikasi Anda. Kunci API juga dapat ditemukan di bagian "Kunci API" pada kredensial project Anda.
    • Klik Restrict key untuk memperbarui setelan lanjutan dan membatasi penggunaan kunci API. Untuk detail selengkapnya, lihat Menerapkan pembatasan kunci API.

Memberi otorisasi pada kredensial untuk aplikasi web

Untuk mengautentikasi pengguna akhir dan mengakses data pengguna di aplikasi, Anda perlu membuat satu atau beberapa Client ID OAuth 2.0. Client ID digunakan untuk mengidentifikasi satu aplikasi ke server OAuth Google. Jika aplikasi Anda berjalan di beberapa platform, Anda harus membuat client ID terpisah untuk setiap platform.

  1. Di konsol Google Cloud, buka Menu > APIs & Services > Credentials.

    Buka Kredensial

  2. Klik Buat Kredensial > Client ID OAuth.
  3. Klik Jenis aplikasi > Aplikasi web.
  4. Di kolom Name, ketik nama untuk kredensial tersebut. Nama ini hanya ditampilkan di Konsol Google Cloud.
  5. Tambahkan URI resmi yang terkait dengan aplikasi Anda:
    • Aplikasi sisi klien (JavaScript)–Pada Asal JavaScript yang diizinkan, klik Tambahkan URI. Kemudian, masukkan URI yang akan digunakan untuk permintaan browser. Atribut ini mengidentifikasi domain tempat aplikasi Anda dapat mengirim permintaan API ke server OAuth 2.0.
    • Aplikasi sisi server (Java, Python, dan lainnya)–Di bagian URI pengalihan yang diotorisasi, klik Tambahkan URI. Kemudian, masukkan URI endpoint yang dapat menjadi tujuan pengiriman respons oleh server OAuth 2.0.
  6. Klik Create. Layar yang dibuat klien OAuth akan muncul, yang menampilkan Client ID dan Rahasia klien Anda yang baru.

    Catat Client-ID. Rahasia klien tidak digunakan untuk aplikasi Web.

  7. Klik OK. Kredensial yang baru dibuat akan muncul di Client ID OAuth 2.0.
Penting: Aplikasi Anda harus mengirimkan token akses OAuth 2.0 dengan tampilan yang mengakses data pribadi pengguna saat membuat objek Picker. Untuk meminta token akses, lihat Menggunakan OAuth 2.0 untuk Mengakses Google API.

Menampilkan Pemilih Google

Bagian selanjutnya dari panduan ini membahas cara memuat dan menampilkan Pemilih Google dari aplikasi web. Untuk melihat contoh lengkap, buka contoh kode Pemilih Google.

Memuat library Google Picker

Untuk memuat library Pemilih Google, panggil gapi.load() dengan nama library dan fungsi callback yang akan dipanggil setelah pemuatan berhasil:

    <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>
    

Ganti kode berikut:

  • CLIENT_ID: Client ID aplikasi web Anda.
  • SCOPES: Satu atau beberapa cakupan OAuth 2.0 yang perlu Anda minta untuk mengakses Google API, bergantung pada tingkat akses yang Anda perlukan. Untuk informasi selengkapnya, lihat Cakupan OAuth 2.0 untuk Google API.

Library JavaScript google.accounts.oauth2 membantu Anda meminta izin pengguna dan mendapatkan token akses untuk menggunakan data pengguna. Metode initTokenClient() melakukan inisialisasi klien token baru dengan client ID aplikasi web Anda. Untuk mengetahui informasi selengkapnya, lihat Menggunakan model token.

Fungsi onApiLoad() memuat library Pemilih Google. Fungsi callback onPickerApiLoad() dipanggil setelah library Pemilih Google berhasil dimuat.

Menampilkan Pemilih Google

Fungsi createPicker() di bawah memeriksa untuk memastikan Google Picker API selesai dimuat dan bahwa token OAuth dibuat. Fungsi ini kemudian membuat instance Pemilih Google dan menampilkannya:

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

Untuk membuat instance Pemilih Google, Anda harus membuat objek Picker menggunakan PickerBuilder. PickerBuilder menggunakan View, token OAuth, kunci developer, dan fungsi callback untuk dipanggil setelah berhasil (pickerCallback).

Objek Picker merender satu View dalam satu waktu. Tentukan setidaknya satu tampilan, baik dengan ViewId (google.​picker.​ViewId.*) maupun dengan membuat instance suatu jenis (google.​picker.​*View). Tentukan tampilan menurut jenis untuk kontrol tambahan atas cara merender tampilan.

Jika lebih dari satu tampilan ditambahkan ke Pemilih Google, pengguna dapat beralih dari satu tampilan ke tampilan lainnya dengan mengklik tab di sebelah kiri. Tab dapat dikelompokkan secara logis dengan objek ViewGroup.

Mengimplementasikan callback Pemilih Google

Callback Pemilih Google dapat digunakan untuk bereaksi terhadap interaksi pengguna di Alat Pilih Google, seperti memilih file atau menekan tombol Batal. Objek Response menyampaikan informasi tentang pilihan pengguna.

    // 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;
    }
    

Callback menerima objek data yang dienkode JSON. Objek ini berisi Action yang dijalankan pengguna dengan Pemilih Google (google.picker.Response.ACTION). Jika pengguna memilih item Document, array google.picker.Response.DOCUMENTS juga akan diisi. Dalam contoh ini, google.picker.Document.URL ditampilkan di halaman utama. Untuk mengetahui detail tentang kolom data, lihat Referensi JSON.

Memfilter jenis file tertentu

Gunakan ViewGroup sebagai cara untuk memfilter item tertentu. Contoh kode berikut menunjukkan bagaimana subtampilan "Google Drive" hanya menampilkan dokumen dan presentasi.

    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();
    
Untuk daftar jenis tampilan yang valid, lihat ViewId.

Menyesuaikan tampilan Alat Pilih Google

Anda dapat menggunakan objek Feature untuk mengaktifkan atau menonaktifkan fitur untuk berbagai tampilan. Untuk menyesuaikan tampilan jendela Pemilih Google, gunakan fungsi PickerBuilder.enableFeature() atau PickerBuilder.disableFeature(). Misalnya, jika Anda hanya memiliki satu tampilan, sebaiknya sembunyikan panel navigasi (Feature.NAV_HIDDEN) agar pengguna memiliki lebih banyak ruang untuk melihat item.

Contoh kode berikut menunjukkan contoh pemilih penelusuran spreadsheet yang menggunakan fitur ini:

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

Merender Pemilih Google dalam bahasa lain

Tentukan bahasa UI dengan menyediakan lokalitas ke instance PickerBuilder menggunakan metode setLocale(locale).

Contoh kode berikut menunjukkan cara menyetel lokalitas ke bahasa Prancis:

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

Berikut adalah daftar lokalitas yang saat ini didukung:

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