Halaman ini diterjemahkan oleh Cloud Translation API.

Data Google di Kereta Api

Contoh DocList Manager [ lihat demo, source ]

Eric Bidelman, Tim Google Data API
Februari 2009

Pengantar

"Di mana Ruby ada dalam daftar library klien?"

Termotivasi oleh selera developer kami yang ganas dan popularitas Ruby on Rails (RoR) yang berkelanjutan, kolega saya, Jeff Fisher, telah memalsukan library utilitas Ruby dari kedalaman Mount Doom yang berapi-api. Perlu diperhatikan bahwa ini bukanlah library klien yang lengkap, tetapi library ini menangani dasar-dasar seperti autentikasi dan manipulasi XML dasar. Hal ini juga mengharuskan Anda bekerja langsung dengan feed Atom menggunakan modul REXML dan XPath.

Audiens

Artikel ini ditujukan bagi developer yang tertarik mengakses Google Data API menggunakan Ruby, khususnya Ruby on Rails. Ini mengasumsikan bahwa pembaca memiliki beberapa pengetahuan tentang bahasa pemrograman Ruby dan framework pengembangan web Rails. Saya berfokus pada Document List API untuk sebagian besar contoh, tetapi konsep yang sama dapat diterapkan ke semua API Data.

Memulai

Persyaratan

Patch Ruby 1.8.6 level 114+ download
RubyGems 1.3.1+ download
Rails 2.2.2+ download

Menginstal Library Utilitas Ruby Data Google

Untuk mendapatkan library, Anda dapat mendownload sumber library langsung dari hosting project atau menginstal gem:

sudo gem install gdata

Tips: Untuk mengukur dengan baik, jalankan gem list --local untuk memverifikasi bahwa permata telah diinstal dengan benar.

Autentikasi

ClientLogin

ClientLogin memungkinkan aplikasi Anda membuat pengguna login secara terprogram ke akun Google atau G Suite mereka. Setelah memvalidasi kredensial pengguna, Google akan menerbitkan token Auth untuk direferensikan dalam permintaan API berikutnya. Token tetap valid selama jangka waktu tertentu, yang ditentukan oleh layanan Google mana pun yang Anda gunakan. Untuk alasan keamanan dan untuk memberikan pengalaman terbaik kepada pengguna, Anda hanya boleh menggunakan ClientLogin saat mengembangkan aplikasi desktop terinstal. Untuk aplikasi web, sebaiknya gunakan AuthSub atau OAuth.

Library Ruby memiliki class klien untuk setiap API. Misalnya, gunakan cuplikan kode berikut untuk login ke user@gmail.com ke Document List Data API:

client = GData::Client::DocList.new
client.clientlogin('user@gmail.com', 'pa$$word')

The YouTube Data API would be:

client = GData::Client::YouTube.new
client.clientlogin('user@gmail.com', 'pa$$word')

Lihat daftar lengkap class layanan yang diterapkan. Jika layanan tidak memiliki class klien, gunakan class GData::Client::Base. Sebagai contoh, kode berikut memaksa pengguna untuk login dengan akun G Suite.

client_login_handler = GData::Auth::ClientLogin.new('writely', :account_type => 'HOSTED')
token = client_login_handler.get_token('user@example.com', 'pa$$word', 'google-RailsArticleSample-v1')
client = GData::Client::Base.new(:auth_handler => client_login_handler)

Catatan: Secara default, library menggunakan HOSTED_OR_GOOGLE untuk accountType. Nilai yang mungkin adalah HOSTED_OR_GOOGLE, HOSTED, atau GOOGLE.

Salah satu kelemahan menggunakan ClientLogin adalah aplikasi Anda dapat dikirimi verifikasi CAPTCHA pada upaya login yang gagal. Jika itu terjadi, Anda dapat menangani error dengan memanggil metode clientlogin() dengan parameter tambahannya: client.clientlogin(username, password, captcha_token, captcha_answer). Baca dokumentasi Autentikasi lengkap untuk Aplikasi yang Diinstal untuk mendapatkan informasi lebih lanjut tentang penanganan CAPTCHA.

AuthSub

Membuat URL AuthSubRequest

scope = 'http://www.google.com/calendar/feeds/'
next_url = 'http://example.com/change/to/your/app'
secure = false  # set secure = true for signed AuthSub requests
sess = true
authsub_link = GData::Auth::AuthSub.get_url(next_url, scope, secure, sess)

Blok kode sebelumnya membuat URL berikut di authsub_link:

https://www.google.com/accounts/AuthSubRequest?next=http%3A%2F%2Fexample.com%2Fchange%2Fto%2Fyour%2Fapp&scope=http%3A%2F%2Fwww.google.com%2Fcalendar%2Ffeeds%2F&session=1&secure=0

Anda juga dapat menggunakan metode authsub_url dari objek klien. Setiap class layanan telah menetapkan atribut authsub_scope default sehingga Anda tidak perlu menentukan atribut Anda sendiri.

client = GData::Client::DocList.new
next_url = 'http://example.com/change/to/your/app'
secure = false  # set secure = true for signed AuthSub requests
sess = true
domain = 'example.com'  # force users to login to a G Suite hosted domain
authsub_link = client.authsub_url(next_url, secure, sess, domain)

Blok kode sebelumnya membuat URL berikut:

https://www.google.com/accounts/AuthSubRequest?next=http%3A%2F%2Fexample.com%2Fchange%2Fto%2Fyour%2Fapp&scope=http%3A%2F%2Fdocs.google.com%2Ffeeds%2F&session=1&secure=0&hd=example.com

Mengupgrade token sekali pakai ke token sesi

AuthSub akan mengalihkan pengguna kembali ke http://example.com/change/to/your/app?token=SINGLE_USE_TOKEN setelah mereka memberikan akses ke data mereka. Perhatikan bahwa URL tersebut hanyalah next_url dengan token sekali pakai yang ditambahkan sebagai parameter kueri.

Berikutnya, tukarkan token sekali pakai dengan token sesi yang tahan lama:

client.authsub_token = params[:token] # extract the single-use token from the URL query params
session[:token] = client.auth_handler.upgrade()
client.authsub_token = session[:token] if session[:token]

AuthSub Secure sangat mirip. Satu-satunya penambahan adalah menyetel kunci pribadi Anda sebelum mengupgrade token:

PRIVATE_KEY = '/path/to/private_key.pem'

client.authsub_token = params[:token]
client.authsub_private_key = PRIVATE_KEY
session[:token] = client.auth_handler.upgrade()
client.authsub_token = session[:token] if session[:token]

Catatan: Untuk menggunakan token aman, pastikan untuk menetapkan secure=true saat meminta token sekali pakai. Lihat Membuat URL AuthSubRequest di atas.

Pengelolaan token

AuthSub menyediakan dua pengendali tambahan, AuthSubTokenInfo dan AuthSub UnplugToken untuk mengelola token. AuthSubTokenInfo berguna untuk memeriksa validitas token. AuthSubRevokeToken memberi pengguna opsi untuk menghentikan akses ke data mereka. Aplikasi Anda harus menggunakan AuthSubRevokeToken sebagai praktik terbaik. Kedua metode ini didukung di library Ruby.

Untuk membuat kueri metadata token:

client.auth_handler.info

Untuk mencabut token sesi:

client.auth_handler.revoke

Lihat dokumentasi lengkap Autentikasi AuthSub untuk Aplikasi Web untuk mendapatkan informasi lengkap tentang AuthSub.

OAuth

Pada saat artikel ini ditulis, OAuth belum ditambahkan ke modul GData::Auth.

Penggunaan OAuth di library utilitas seharusnya relatif sederhana saat menggunakan oauth-plugin Rails atau permata OAuth Ruby. Dalam kedua kasus tersebut, Anda dapat membuat objek GData::HTTP::Request dan meneruskan header Authorization yang dihasilkan oleh setiap library.

Mengakses feed

GET (mengambil data)

Setelah Anda menyiapkan objek klien, gunakan metode get()-nya untuk membuat kueri feed Data Google. XPath dapat digunakan untuk mengambil elemen Atom tertentu. Berikut adalah contoh pengambilan Google Dokumen pengguna:

feed = client.get('http://docs.google.com/feeds/documents/private/full').to_xml

feed.elements.each('entry') do |entry|
  puts 'title: ' + entry.elements['title'].text
  puts 'type: ' + entry.elements['category'].attribute('label').value
  puts 'updated: ' + entry.elements['updated'].text
  puts 'id: ' + entry.elements['id'].text
  
  # Extract the href value from each <atom:link>
  links = {}
  entry.elements.each('link') do |link|
    links[link.attribute('rel').value] = link.attribute('href').value
  end
  puts links.to_s
end

POST (membuat data baru)

Gunakan metode post() klien untuk membuat data baru di server. Contoh berikut akan menambahkan new_writer@example.com sebagai kolaborator ke dokumen dengan ID: doc_id.

# Return documents the authenticated user owns
feed = client.get('http://docs.google.com/feeds/documents/private/full/-/mine').to_xml
entry = feed.elements['entry']  # first <atom:entry>

acl_entry = <<-EOF
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:gAcl='http://schemas.google.com/acl/2007'>
  <category scheme='http://schemas.google.com/g/2005#kind'
    term='http://schemas.google.com/acl/2007#accessRule'/>
  <gAcl:role value='writer'/>
  <gAcl:scope type='user' value='new_writer@example.com'/>
</entry>
EOF

# Regex the document id out from the full <atom:id>.
# http://docs.google.com/feeds/documents/private/full/document%3Adfrk14g25fdsdwf -> document%3Adfrk14g25fdsdwf
doc_id = entry.elements['id'].text[/full\/(.*%3[aA].*)$/, 1]
response = client.post("http://docs.google.com/feeds/acl/private/full/#{doc_id}", acl_entry)

PUT (memperbarui data)

Untuk memperbarui data di server, gunakan metode put() klien. Contoh berikut akan memperbarui judul dokumen. Diasumsikan bahwa Anda memiliki feed dari kueri sebelumnya.

entry = feed.elements['entry'] # first <atom:entry>

# Update the document's title
entry.elements['title'].text = 'Updated title'
entry.add_namespace('http://www.w3.org/2005/Atom')
entry.add_namespace('gd','http://schemas.google.com/g/2005')

edit_uri = entry.elements["link[@rel='edit']"].attributes['href']
response = client.put(edit_uri, entry.to_s)

HAPUS

Untuk menghapus <atom:entri> atau data lainnya dari server, gunakan metode delete(). Contoh berikut akan menghapus dokumen. Kode ini mengasumsikan bahwa Anda memiliki entri dokumen dari kueri sebelumnya.

entry = feed.elements['entry'] # first <atom:entry>
edit_uri = entry.elements["link[@rel='edit']"].attributes['href']
client.headers['If-Match'] = entry.attribute('etag').value  # make sure we don't nuke another client's updates
client.delete(edit_uri)

Membuat aplikasi Rails baru

Biasanya, latihan pertama dalam membuat aplikasi Rel baru adalah menjalankan scaffold generator untuk membuat file MVC. Setelah itu, aplikasi akan menjalankan rake db:migrate untuk menyiapkan tabel database Anda. Namun, karena aplikasi kita akan membuat kueri untuk API Daftar Dokumen Google untuk data, kita tidak terlalu memerlukan scaffolding atau database umum. Sebagai gantinya, buat aplikasi baru dan pengontrol sederhana:

rails doclist
cd doclist
ruby script/generate controller doclist

dan lakukan perubahan berikut pada config/environment.rb:

config.frameworks -= [ :active_record, :active_resource, :action_mailer ]
config.gem 'gdata', :lib => 'gdata'

Baris pertama melepaskan ActiveRecord dari aplikasi. Baris kedua memuat gem gdata saat memulai.

Terakhir, saya memilih menghubungkan rute default ('/') dengan tindakan documents di DoclistController. Tambahkan baris ini ke config/routes.rb:

map.root :controller => 'doclist', :action => 'all'

Memulai pengontrol

Karena kita tidak membuat scaffolding, tambahkan tindakan secara manual bernama 'all' ke DoclistController di app/controllers/doclist_controller.rb.

class DoclistController < ApplicationController
  def all
    @foo = 'I pity the foo!'
  end
end

dan buat all.html.erb di bagian app/views/doclist/:

<%= @foo %>

Mengaktifkan server web & amp; memulai pengembangan

Anda sekarang dapat memulai server web default dengan memanggil ruby script/server. Jika tidak ada masalah, mengarahkan browser ke http://localhost:3000/ akan menampilkan 'I pity the foo!'.

Tips: Jangan lupa untuk menghapus atau mengganti nama public/index.html.

Setelah semuanya berfungsi, lihat bagian akhir DoclistController dan ApplicationController untuk mengetahui project Project DocList Manager. Anda juga dapat melihat ContactsController, yang menangani panggilan ke Google Contacts API.

Kesimpulan

Bagian tersulit dari membuat aplikasi Google Data Rails adalah mengonfigurasi Rails! Namun, detik kedua adalah men-deploy aplikasi Anda. Untuk itu, saya sangat merekomendasikan mod_rails untuk Apache. Penyiapan, penginstalan, dan pengoperasiannya sangat mudah. Anda akan siap dan mulai bekerja dalam waktu singkat!

Resource

Daftar Google Data API
Halaman project Library Utilitas Ruby Data Google
Artikel: Menggunakan Ruby dengan Google Data API
Download Ruby
Mendownload RubyGems dan Rails

Lampiran

Contoh

DocList Manager adalah contoh lengkap Ruby on Rails yang menunjukkan topik yang dibahas dalam artikel ini. Kode sumber lengkap tersedia dari hosting project.

Contoh Lainnya

Mengambil daftar Google Dokumen pengguna menggunakan ClientLogin.

#!/usr/bin/ruby

require 'rubygems'
require 'gdata'
require 'highline/import'

def user_input(prompt='> ', echo=true)
  ask(prompt) {|q| q.echo = echo}
end

email = user_input('email: ')
pass = user_input('password: ', false)

client = GData::Client::DocList.new({:source => 'google-RailsArticleSample-v1'})
client.clientlogin(email, pass)

feed = client.get(client.authsub_scope + 'documents/private/full').to_xml

puts 'Listing all documents: --------------------'
feed.elements.each('entry') do |entry|
  puts 'title: ' + entry.elements['title'].text
  puts 'type: ' + entry.elements['category'].attribute('label').value
  puts 'updated: ' + entry.elements['updated'].text
  puts 'id: ' + entry.elements['id'].text[/%3[aA](.*)$/, 1]
  puts
end

Gabungkan menggunakan Document List, Contacts, dan Sheets API. Contoh ini menunjukkan penggunaan AuthSub yang aman di RoR.

require 'gdata'

class YourController < ApplicationController
  before_filter :authenticate_client

  PRIVATE_KEY = '/path/to/private_key.pem'
  DOCLIST_SCOPE = 'http://docs.google.com/feeds/'
  CONTACTS_SCOPE = 'http://www.google.com/m8/feeds/'
  SPREADSHEETS_SCOPE = 'http://spreadsheets.google.com/feeds/'

  def authenticate_client
    scopes = [DOCLIST_SCOPE, SPREADSHEETS_SCOPE, CONTACTS_SCOPE]
    @client = GData::Client::Base.new({:authsub_scope => scopes.join(' '),
                                       :source => 'google-RailsArticleSample-v1'})

    if params[:token].nil? and session[:token].nil?
      next_url = url_for :controller => self.controller_name, :action => self.action_name
      secure = true
      @authsub_link = @client.authsub_url(next_url, secure, true)
      render :controller => 'your_controller', :action => 'your_action'
    elsif params[:token] and session[:token].nil?
      @client.authsub_token = params[:token]
      @client.authsub_private_key = PRIVATE_KEY
      session[:token] = @client.auth_handler.upgrade()
    end

    if session[:token]
      @client.authsub_token = session[:token]
      @client.authsub_private_key = PRIVATE_KEY  # Make sure to set your private key for subsequent requests
    end
  end

  def get_docs
    @feed = @client.get(@client.authsub_scope + 'documents/private/full').to_xml
  end
end

Membuat, mengedit, dan menghapus playlist di YouTube menggunakan token AuthSub.

#!/usr/bin/ruby

require 'rubygems'
require 'gdata'

yt = GData::Client::YouTube.new({:source => 'google-RailsArticleSample-v1'})
yt.authsub_token = 'SESSION_TOKEN'
yt.client_id = 'CLIENT_ID'
yt.developer_key = 'DEVELOPER_KEY'

# 1.) Creating a new playlist
entry = <<-EOF
<entry xmlns="http://www.w3.org/2005/Atom"
    xmlns:yt="http://gdata.youtube.com/schemas/2007">
  <title type="text">Ruby Utility Unit Test</title>
  <summary>This is a test playlist.</summary>
</entry>
EOF

response = yt.post('http://gdata.youtube.com/feeds/api/users/default/playlists', entry).to_xml

# 2.) Updating the received playlist
edit_uri = response.elements["link[@rel='edit']"].attributes['href']
response.elements['summary'].text = 'Updated description'

response = yt.put(edit_uri, response.to_s).to_xml

# 3.) Deleting the playlist
yt.delete(edit_uri)

Perintah Rails yang Berguna

Jika Anda seperti saya dan sudah lama tidak menggunakan Rails, berikut daftar perintah yang perlu diingat.

Mengupdate penginstalan RubyGem: sudo gem update --system
Perbarui gem yang diinstal: sudo gem update
Membuat Rails baru dengan MySQL sebagai db: rails -d mysql APP_NAME
Memulai server dalam produksi di port lain: ruby script/server -p PORT -e production
Menghapus file log: rake log:clear