تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

بيانات Google حول السكك الحديدية

نموذج مدير قائمة المستندات [ عرض العرض التوضيحي، المصدر ]

إريك بيدلمان، فريق Google Data APIs
شباط (فبراير) 2009

المقدمة

"Where's Ruby is on the list of client مكتبات? "

بدافع من حماسة مطوّري البرامج وشعبية Ruby on السكك الحديدية (ROR) المتواصلة، أنشأ زميلي جيف فيشر مكتبة لمستلزمات لعبة Ruby من أعماق جبل Doom. ضع في اعتبارك أنها ليست مكتبة عميلة كاملة، ولكنها ستتعامل مع الأساسيات مثل المصادقة ومعالجة XML الأساسية. ويتطلّب ذلك أيضًا العمل مباشرةً مع خلاصة Atom باستخدام وحدة REXML وXPath.

الجمهور

هذه المقالة مُعدّة لمطوّري البرامج المهتمين بالوصول إلى واجهات برمجة تطبيقات بيانات Google باستخدام Ruby، خاصة Ruby على السكك الحديدية. وتفترض أنّ القارئ على دراية بلغة برمجة Ruby وإطار عمل تطوير خدمات "السكة الحديدية" على الويب. أركز على واجهة برمجة التطبيقات لقائمة المستندات لمعظم النماذج، ولكن يمكن تطبيق المفاهيم نفسها على أي من واجهات برمجة التطبيقات للبيانات.

البدء

المتطلّبات

إصدار 1.8.6 لروبي من المستوى 114 أو أكثر تنزيل
RubyGems 1.3.1 أو الأحدث تنزيل
السكة الحديدية 2.2.2+ تنزيل

تثبيت مكتبة أداة Google Ruby في Google Data

للحصول على المكتبة، يمكنك إما تنزيل مصدر المكتبة مباشرة من استضافة المشروع أو تثبيت الأداة:

sudo gem install gdata

نصيحة: للحصول على قياس جيد، شغّل gem list --local للتحقق من تثبيت الجوهرة بشكل صحيح.

المصادقة

ClientLogin

يتيح ClientLogin لتطبيقك تسجيل دخول المستخدمين آليًا إلى حساباتهم على Google أو G Suite. عند التحقق من بيانات اعتماد المستخدم، تصدر Google رمز مصادقة مميزًا لتتم الإشارة إليه في طلبات واجهة برمجة التطبيقات التالية. يظل الرمز المميز صالحًا لمدة زمنية محددة، يتم تحديدها من خلال أي خدمة من خدمات Google تعمل معها. لأسباب أمنية ولتوفير أفضل تجربة للمستخدمين، يجب ألا تستخدم ClientLogin إلا عند تطوير تطبيقات سطح المكتب المثبتة. بالنسبة إلى تطبيقات الويب، يُفضَّل استخدام AuthSub أو OAuth.

تحتوي مكتبة Ruby على فئة عميل لكل واجهة من واجهات برمجة التطبيقات. على سبيل المثال، استخدم مقتطف الرمز التالي لتسجيل الدخول user@gmail.com إلى واجهة برمجة التطبيقات لبيانات قائمة المستندات:

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

اطّلع على القائمة الكاملة لفئات الخدمات التي تم تنفيذها. إذا لم تكن الخدمة تتضمن فئة عميل، استخدِم فئة GData::Client::Base. على سبيل المثال، يفرض الرمز التالي على المستخدمين تسجيل الدخول باستخدام حساب 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)

ملاحظة: تستخدِم المكتبة HOSTED_OR_GOOGLE تلقائيًا في accountType. القيم المحتملة هي HOSTED_OR_GOOGLE أو HOSTED أو GOOGLE.

تتمثل إحدى سلبيات استخدام ClientLogin في إمكانية إرسال تطبيقك لاختبارات CAPTCHA في محاولات تسجيل الدخول الفاشلة. وفي حال حدوث ذلك، يمكنك التعامل مع الخطأ عن طريق استدعاء الطريقة clientlogin() مع معلماتها الإضافية: client.clientlogin(username, password, captcha_token, captcha_answer). ارجع إلى وثائق مصادقة التطبيقات المثبتة الكاملة للحصول على مزيد من المعلومات حول التعامل مع اختبارات CAPTCHA.

AuthSub

جارٍ إنشاء عنوان 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)

تؤدي كتلة الرمز السابقة إلى إنشاء عنوان URL التالي في 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

ويمكنك أيضًا استخدام الطريقة authsub_url لكائن العميل. تعيّن كل فئة خدمة سمة authsub_scope تلقائية، لذلك لا داعي لتحديد السمة الخاصة بك.

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)

تؤدي الكتلة السابقة من الشفرة إلى إنشاء عنوان URL التالي:

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

ترقية الرمز المميز للاستخدام لمرة واحدة إلى رمز مميز للجلسة

سيُعيد تطبيق AuthSub توجيه المستخدم إلى http://example.com/change/to/your/app?token=SINGLE_USE_TOKEN بعد منحه إمكانية الوصول إلى بياناته. لاحظ أن عنوان URL هو next_url فقط مع إلحاق الرمز المميز لمرة واحدة بمعلمة طلب البحث.

بعد ذلك، عليك استبدال الرمز المميّز الذي يُستخدم لمرة واحدة برمز مميّز لجلسة طويلة الأمد:

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 الآمن مشابه جدًا. الإضافة الوحيدة هي تعيين المفتاح الخاص قبل ترقية الرمز المميز:

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]

ملاحظة: لاستخدام الرموز المميّزة الآمنة، احرص على ضبط secure=true عند طلب رمز مميّز يُستخدم لمرة واحدة. راجع إنشاء عنوان URL لـ AuthSubRequest أعلاه.

إدارة الرموز المميزة

توفّر AuthSub معالجَين إضافيَين، وهما AuthSubTokenInfo و AuthSubإبطالToken لإدارة الرموز المميّزة. AuthSubTokenInfo مفيد للتحقق من صلاحية الرمز المميز. تمنح خدمة AuthSubRevokeToken المستخدمين خيار إيقاف الوصول إلى بياناتهم. ويجب أن يستخدم تطبيقك AuthSubRevokeToken كأفضل ممارسة. تتوفّر كلتا الطريقتين في مكتبة Ruby.

للاستعلام عن البيانات الوصفية للرمز المميز:

client.auth_handler.info

لإبطال رمز مميز للجلسة:

client.auth_handler.revoke

اطلع على وثائق مصادقة AuthSub لتطبيقات الويب الكاملة لمعرفة التفاصيل الدقيقة حول AuthSub.

OAuth

أثناء كتابة هذه المقالة، لم تتم إضافة OAuth إلى الوحدة GData::Auth.

يجب أن يكون استخدام OAuth في مكتبة المرافق واضحًا نسبيًا عند استخدام القضبان oauth-plugin أو Ruby oauth gem. وفي كلتا الحالتين، ستحتاج إلى إنشاء كائن GData::HTTP::Request وتمريره العنوان Authorization الذي تنشئه كل مكتبة.

الوصول إلى الخلاصات

GET (جلب البيانات)

بعد إعداد كائن عميل، استخدِم طريقة get() لطلب بحث عن خلاصة بيانات في Google. يمكن استخدام XPath لاسترداد عناصر Atom محددة. في ما يلي مثال لاسترداد مستندات Google لأحد المستخدمين:

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 (إنشاء بيانات جديدة)

استخدم طريقة post() للعميل لإنشاء بيانات جديدة على الخادم. في المثال التالي، ستتم إضافة new_writer@example.com كمتعاون إلى المستند الذي يحمل المعرّف: 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 (تحديث البيانات)

لتحديث البيانات على الخادم، استخدم طريقة put() للبرنامج. سيحدّث المثال التالي عنوان المستند. وتفترض هذه الخلاصة أن لديك خلاصة من طلب بحث سابق.

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)

حذف

لحذف Atom:أو إدخال آخر من البيانات من الخادم، استخدم طريقة delete(). سيؤدي المثال التالي إلى حذف مستند. يفترض الرمز أن لديك إدخال مستند من طلب بحث سابق.

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)

إنشاء تطبيق جديد لخطوط السكك الحديدية

عادةً ما يتطلب الأمر الأول عند إنشاء تطبيق السكك الحديدية الجديد تشغيل مولدات السقالات لإنشاء ملفات MVC. بعد ذلك، يتم تشغيل rake db:migrate لإعداد جداول قاعدة البيانات. ومع ذلك، ونظرًا لأن تطبيقنا سيبحث في واجهة برمجة التطبيقات لقائمة مستندات Google عن البيانات، فلم نعد بحاجة إلى أي سقالات أو قواعد بيانات عامة. بدلاً من ذلك، أنشئ تطبيقًا جديدًا ووحدة تحكم بسيطة:

rails doclist
cd doclist
ruby script/generate controller doclist

وأجرِ التغييرات التالية على config/environment.rb:

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

يزيل السطر الأول ActiveRecord من التطبيق. يعمل السطر الثاني على تحميل جوهرة gdata عند بدء التشغيل.

أخيرًا، اخترت ربط المسار التلقائي ('/') بالإجراء documents في DoclistController. إضافة هذا السطر إلى config/routes.rb:

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

بدء وحدة تحكم

نظرًا لأننا لم ننشئ أي سقالات، فأضف إجراء باسم "all" يدويًا إلى DoclistController في app/controllers/doclist_controller.rb.

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

وأنشئ all.html.erb ضمن app/views/doclist/:

<%= @foo %>

ابدأ تشغيل خادم الويب وابدأ التطوير

من المفترض أن يصبح بإمكانك الآن بدء خادم الويب التلقائي من خلال استدعاء ruby script/server. إذا كان كل شيء على ما يرام، يجب أن يؤدي توجيه المتصفح إلى http://localhost:3000/ إلى عرض "I pity the foo!".

نصيحة: لا تنس إزالة public/index.html أو إعادة تسميتها.

بعد الانتهاء من الإجراءات، ألقِ نظرة على DoclistController النهائي وApplicationController للاطلاع على مشروع مشروع DocList Manager. ستحتاج أيضًا إلى الاطّلاع على ContactsController، الذي يتعامل مع المكالمات الواردة إلى واجهة برمجة تطبيقات "جهات اتصال Google".

الخاتمة

أصعب شيء في إنشاء تطبيق Google Datarails هو تهيئة Trains! ومع ذلك، تتمثّل الخطوة الثانية في نشر تطبيقك. ولذلك، أوصي بشدة باستخدام mod_rails لنظام Apache. من السهل جدًا إعداده وتثبيته وتشغيله. ستتمكن من البدء في وقت قصير!

الموارد

قائمة بواجهات برمجة التطبيقات لبيانات Google
صفحة مشروع مكتبة بيانات Google Ruby
مقالة: استخدام Ruby مع Google Data APIs
تنزيل Ruby
تنزيل RubyGems وRrails

الملحق

أمثلة

يعتبر DocList Manager نموذجًا كاملاً لـ Ruby on السكك الحديدية يوضح الموضوعات التي تمت مناقشتها في هذه المقالة. تتوفر شفرة المصدر الكاملة من خلال استضافة المشروع.

مزيد من الأمثلة

استرد قائمة مستندات Google لأحد المستخدمين باستخدام 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

المزج باستخدام واجهة برمجة التطبيقات لقائمة المستندات وجهات الاتصال وجداول البيانات يوضح هذا المثال استخدام AuthSub آمن في 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

إنشاء قائمة تشغيل في YouTube وتعديلها وحذفها باستخدام رمز 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)

أوامر سكة حديد مفيدة

إذا كنت مثلي ولم تستخدم "السكك الحديدية" منذ مدة، فإليك قائمة بالأوامر التي تستحق تذكرها.

تحديث تثبيت RubyGem: sudo gem update --system
تحديث الجواهر المثبّتة: sudo gem update
إنشاء خطوط سكك حديدية جديدة باستخدام MySQL كقاعدة بيانات: rails -d mysql APP_NAME
بدء الخادم في مرحلة الإنتاج باستخدام منفذ آخر: ruby script/server -p PORT -e production
محو ملفات السجلّ: rake log:clear