Google Picker API

Google Seçici iletişim kutusu.

Google Picker API, kullanıcıların Google Drive dosyalarını seçmesine veya yüklemesine olanak tanımak için web uygulamalarınızda kullanabileceğiniz bir JavaScript API'sidir. Kullanıcılar, Drive verilerine erişmesi için uygulamalarınıza izin verebilir. Bu sayede, dosyalarıyla güvenli ve yetkili bir şekilde etkileşime geçebilirsiniz.

Google Seçici, Drive'da depolanan bilgiler için bir "Dosya Aç" iletişim kutusu işlevi görür ve şu özelliklere sahiptir:

  • Google Drive kullanıcı arayüzüne benzer bir görünüm ve tarzdır.
  • Drive dosyalarının önizlemelerini ve küçük resimlerini gösteren çeşitli görünümler.
  • Kullanıcıların ana uygulamadan asla ayrılmaması için satır içi, kalıcı pencere.

Google Seçici'nin, kullanıcıların bir klasörden diğerine dosya düzenlemesine, taşımasına veya kopyalamasına izin vermediğini unutmayın. Bunu yapmak için Google Drive API'yi veya Drive kullanıcı arayüzünü kullanabilirsiniz.

Başvuru şartları

Google Seçici'yi kullanan uygulamalar mevcut tüm Hizmet Şartları'na uymalıdır. En önemlisi, isteklerinizde kendinizi doğru şekilde tanımlamanız gerekir.

Ayrıca bir Google Cloud projeniz olmalıdır.

Ortamınızı ayarlama

Google Picker API'yi kullanmaya başlamak için ortamınızı ayarlamanız gerekir.

API'yi etkinleştirme

Google API'lerini kullanmadan önce bunları bir Google Cloud projesinde etkinleştirmeniz gerekir. Tek bir Google Cloud projesinde bir veya daha fazla API etkinleştirebilirsiniz.

API anahtarı oluşturma

API anahtarı büyük ve küçük harf, sayı, alt çizgi ve kısa çizgi (ör. AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe) içeren uzun bir dizedir. Bu kimlik doğrulama yöntemi, "İnternetteki bu bağlantıyı bilen herkes" paylaşım ayarı kullanılarak paylaşılan Google Workspace dosyaları gibi herkese açık verilere anonim olarak erişmek için kullanılır. Daha fazla bilgi için API anahtarları kullanarak kimlik doğrulama bölümüne bakın.

API anahtarı oluşturmak için:

  1. Google Cloud konsolunda Menü > API'ler ve Hizmetler > Kimlik Bilgileri'ne gidin.

    Kimlik Bilgileri'ne git

  2. Kimlik bilgileri oluştur > API anahtarı'nı tıklayın.
  3. Yeni API anahtarınız görüntülenir.
    • Uygulamanızın kodunda kullanmak üzere API anahtarınızı kopyalamak için Kopyala'yı tıklayın. API anahtarı, projenizin kimlik bilgilerinin "API anahtarları" bölümünde de bulunabilir.
    • Gelişmiş ayarları güncellemek ve API anahtarınızın kullanımını sınırlamak için Anahtarı kısıtla'yı tıklayın. Daha fazla bilgi için API anahtarı kısıtlamaları uygulama bölümüne bakın.

Web uygulaması için kimlik bilgilerini yetkilendirme

Uygulamanızda son kullanıcıların kimliğini doğrulamak ve kullanıcı verilerine erişmek için bir veya daha fazla OAuth 2.0 İstemci Kimliği oluşturmanız gerekir. İstemci kimliği, tek bir uygulamayı Google'ın OAuth sunucularına tanımlamak için kullanılır. Uygulamanız birden fazla platformda çalışıyorsa her platform için ayrı bir istemci kimliği oluşturmanız gerekir.

  1. Google Cloud konsolunda Menü > API'ler ve Hizmetler > Kimlik bilgileri'ne gidin.

    Kimlik Bilgileri'ne git

  2. Kimlik Bilgileri Oluştur > OAuth istemci kimliği'ni tıklayın.
  3. Uygulama türü > Web uygulaması'nı tıklayın.
  4. Ad alanına kimlik bilgisi için bir ad yazın. Bu ad yalnızca Google Cloud Console'da gösterilir.
  5. Uygulamanızla ilgili yetkili URI'leri ekleyin:
    • İstemci tarafı uygulamalar (JavaScript): Yetkili JavaScript kaynakları bölümünde URI ekle'yi tıklayın. Ardından, tarayıcı istekleri için kullanılacak bir URI girin. Bu, uygulamanızın OAuth 2.0 sunucusuna API istekleri gönderebileceği alan adlarını tanımlar.
    • Sunucu tarafı uygulamalar (Java, Python ve daha fazlası): Yetkili yönlendirme URI'leri bölümünde URI ekle'yi tıklayın. Ardından OAuth 2.0 sunucusunun yanıt gönderebileceği bir uç nokta URI'si girin.
  6. Create'i (Oluştur) tıklayın. OAuth istemcisi oluşturma ekranı görünür ve yeni İstemci Kimliğinizi ve İstemci sırrınızı gösterir.

    Client-ID'yi not alın. İstemci gizli anahtarları Web uygulamaları için kullanılmaz.

  7. Tamam'ı tıklayın. Yeni oluşturulan kimlik bilgisi, OAuth 2.0 İstemci Kimlikleri bölümünde gösterilir.
Önemli: Uygulamanız, bir Picker nesnesi oluştururken gizli kullanıcı verilerine erişen görünümleri içeren bir OAuth 2.0 erişim jetonu göndermelidir. Erişim jetonu istemek için Google API'lerine Erişmek için OAuth 2.0'ı Kullanma başlıklı makaleye göz atın.

Google Seçici'yi göster

Bu kılavuzun geri kalanında, Google Seçici'nin bir web uygulamasından nasıl yükleneceği ve görüntüleneceği ele alınmaktadır. Örneğin tamamını görüntülemek için Google Seçici kod örneğine gidin.

Google Picker kitaplığını yükle

Google Seçici kitaplığını yüklemek için kitaplık adıyla ve başarılı bir yüklemenin ardından çağrılacak bir geri çağırma işleviyle gapi.load() çağrısı yapın:

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

Aşağıdakini değiştirin:

  • CLIENT_ID: Web uygulamanızın istemci kimliği.
  • SCOPES: İhtiyacınız olan erişim düzeyine bağlı olarak, Google API'lerine erişmek için istemeniz gereken bir veya daha fazla OAuth 2.0 kapsamı. Daha fazla bilgi için Google API'leri için OAuth 2.0 Kapsamları bölümüne bakın.

google.accounts.oauth2 JavaScript kitaplığı, kullanıcı izni istemenize ve kullanıcı verileriyle çalışmak için bir erişim jetonu almanıza yardımcı olur. initTokenClient() yöntemi, web uygulamanızın istemci kimliğiyle yeni bir jeton istemcisi başlatır. Daha fazla bilgi için Jeton modelini kullanma bölümüne bakın.

onApiLoad() işlevi, Google Seçici kitaplıklarını yükler. onPickerApiLoad() geri çağırma işlevi, Google Seçici kitaplığı başarıyla yüklendikten sonra çağrılır.

Google Seçici'yi göster

Aşağıdaki createPicker() işlevi, Google Picker API'nin yüklenmesinin tamamlandığını ve bir OAuth jetonunun oluşturulduğundan emin olmak için kontrol gerçekleştirir. Bu işlev, daha sonra Google Seçici'nin bir örneğini oluşturur ve bunu görüntüler:

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

Google Seçici örneği oluşturmak için PickerBuilder kullanarak bir Picker nesnesi oluşturmanız gerekir. PickerBuilder, başarılı olduğunda çağırmak için bir View, bir OAuth jetonu, bir geliştirici anahtarı ve bir geri çağırma işlevi (pickerCallback) alır.

Picker nesnesi her defasında bir View oluşturur. ViewId (google.​picker.​ViewId.*) veya bir türün örneği oluşturarak (google.​picker.​*View) en az bir görünüm belirtin. Görünümün nasıl oluşturulacağı üzerinde ek kontrol sağlamak için görünümü türe göre belirtin.

Google Seçici'ye birden fazla görünüm eklenirse, kullanıcılar soldaki bir sekmeyi tıklayarak bir görünümden diğerine geçiş yapabilir. Sekmeler, ViewGroup nesneleriyle mantıksal olarak gruplandırılabilir.

Google Seçici geri çağırmasını uygulama

Google Seçici'deki kullanıcı etkileşimlerine (ör. dosya seçme veya İptal'e basma) tepki vermek için Google Seçici geri çağırması kullanılabilir. Response nesnesi, kullanıcının seçimleriyle ilgili bilgi aktarır.

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

Geri çağırma, JSON kodlamalı bir data nesnesi alır. Bu nesne, kullanıcının Google Seçici (google.picker.Response.ACTION) ile gerçekleştirdiği bir Action içerir. Kullanıcı bir Document öğesi seçerse google.picker.Response.DOCUMENTS dizisi de doldurulur. Bu örnekte google.picker.Document.URL ana sayfada gösterilmektedir. Veri alanlarıyla ilgili ayrıntılar için JSON Referansı'na bakın.

Belirli dosya türlerini filtreleme

Belirli öğeleri filtreleme yöntemi olarak ViewGroup kullanın. Aşağıdaki kod örneğinde, "Google Drive" alt görünümünde yalnızca doküman ve sunuların nasıl gösterildiği gösterilmektedir.

    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();
    
Geçerli görünüm türlerinin listesi için ViewId sayfasına bakın.

Google Seçici'nin görünümünü ayarlama

Özellikleri çeşitli görünümlerde etkinleştirmek veya devre dışı bırakmak için Feature nesnesini kullanabilirsiniz. Google Seçici penceresinin görünümüne ince ayar yapmak için PickerBuilder.enableFeature() veya PickerBuilder.disableFeature() işlevini kullanın. Örneğin, tek bir görünümünüz varsa kullanıcılara öğeleri görmeleri için daha fazla alan sağlamak üzere gezinme bölmesini (Feature.NAV_HIDDEN) gizlemek isteyebilirsiniz.

Aşağıdaki kod örneğinde, bu özelliği kullanan bir e-tablo arama seçici örneği gösterilmektedir:

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

Google Seçici'yi başka dillerde oluştur

setLocale(locale) yöntemini kullanıp PickerBuilder örneğine yerel ayarı sağlayarak kullanıcı arayüzü dilini belirtin.

Aşağıdaki kod örneğinde yerel ayarın Fransızca olarak nasıl ayarlanacağı gösterilmiştir:

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

Şu anda desteklenen yerel ayarların listesi aşağıda verilmiştir:

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