baidu-sdk 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 989e658f22320158d197a3dcad2a2bb02fd2bae0
+  data.tar.gz: 386a4d15d1237e93b6081d90c678328b6728774f
+SHA512:
+  metadata.gz: d1a83fcbeb4bd8eba7ebf195f2f9a62742be6271187288fbd346ed7e6dae040c343658760cc2230da600dd019ec681c848b4482307ca684e7a80667ae6c04d1e
+  data.tar.gz: cd3a8c489b63b9796988fadf59187825fbdf0d6eff4c4ba20f62863de57c622e636f8efa684e513ff978af847c320902505374a2de892479887e34aacffb4f39

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp/
+.idea/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.travis.yml

@@ -0,0 +1,15 @@
+language: ruby
+bundler_args: --without development
+script: 'bundle exec rake spec'
+
+rvm:
+  - 1.9.3
+  - 2.0.0
+  - rbx-2.1.1
+  - jruby-19mode
+  - ruby-head
+
+matrix:
+  allow_failures:
+    - rvm: rbx-2.1.1
+    - rvm: jruby-19mode

data/.yardopts

@@ -0,0 +1 @@
+--no-private

data/Gemfile

@@ -0,0 +1,17 @@
+source 'https://rubygems.org'
+
+group :development do
+  gem 'guard-rspec'
+  gem 'terminal-notifier-guard' if /darwin/ =~ RUBY_PLATFORM
+end
+
+group :test, :development do
+  gem 'rake'
+  gem 'rspec'
+  gem 'webmock'
+end
+
+gem 'rubysl', platforms: :rbx
+
+# Specify your gem's dependencies in baidu-pcs.gemspec
+gemspec

data/Guardfile

@@ -0,0 +1,6 @@
+guard :rspec, all_on_start: true, all_after_pass: true, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/HISTORY.md

@@ -0,0 +1,2 @@
+## 0.0.1 (2013-11-28)
+* 首个版本

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Lonre Wang
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,161 @@
+# Baidu SDK for Ruby [![Build Status](https://travis-ci.org/lonre/baidu-sdk-ruby.png?branch=master)](https://travis-ci.org/lonre/baidu-sdk-ruby)
+
+Unofficial Baidu REST API SDK for Ruby.
+非官方百度开放接口 Ruby 开发包。
+
+## 安装
+
+如果你通过 Bundler 来管理你的应用，添加如下一行到应用的 Gemfile 中：
+
+    gem 'baidu-sdk'
+
+然后在终端执行：
+
+    $ bundle
+
+或者直接安装：
+
+    $ gem install baidu-sdk
+
+`baidu-sdk` 当前支持 Ruby(MRI) 版本：1.9.3, 2.0.0
+
+## 使用简介
+[baidu-sdk api doc](http://rubydoc.info/gems/baidu-sdk/frames)
+
+本项目根据百度开放接口划分成多个独立模块，如：`Baidu::OAuth`, `Baidu::PCS`等等。
+
+`Hash` 必须使用 `symbol` key，无论是返回值或作为参数传递给方法。
+
+涉及到调用 Baidu REST API 并返回 Hash 时，除非特别说明，Hash 是在原始 API 返回的 JSON 结果之上 `parse(JSON.parse(resp.body, symbolize_names: true))` 而来，Hash 和 JSON 拥有相同的结构，返回的具体结构可以参考各个方法的 API Doc。如：
+```ruby
+# 返回的原始 JSON
+#   {"quota":15000000000,"used":5221166,"request_id":4043312634}
+result = pcs_client.quota
+result[:quota]  # => 15000000000
+result[:used]   # => 5221166
+```
+
+## OAuth
+首先确保已经在百度开发者中心创建了应用。如果还没有创建应用，请通过此链接 [百度开发者中心](http://developer.baidu.com/console) 创建一个新的应用，获取应用的 `API Key` 和 `Secret Key`。
+
+1. 使用全局配置方式：
+    ```ruby
+    Baidu.config do |c|
+      c.client_id     = 'an_api_key'
+      c.client_secret = 'a_securet_key'
+    end
+    ```
+    此全局配置为可选方式，还可以在新建 `Baidu::OAuth::Client` 实例的时候指定 `API Key` 和 `Secret Key`。
+
+2. 创建 Baidu::OAuth::Client 实例
+    ```ruby
+    require 'baidu/oauth'
+    client = Baidu::OAuth::Client.new
+    # 或者
+    client = Baidu::OAuth::Client.new('a_client_id', 'a_client_secret')
+    ```
+    后者创建的实例受全局配置影响
+3. Baidu OAuth 有四种（当前实现两种）获取 Access Token 的方式，包括 `Authorization Code`, `Implicit Grant`, `Client Credentials`, `Device`以及一个刷新方式`Refresh Token`
+
+    ```ruby
+    client.code_flow.authorize_url  # 使用 Authorization Code 授权流程
+    client.code_flow.get_token      # 使用 Authorization Code 授权流程
+    client.device_flow.user_and_device_code  # 使用 Device 授权流程
+    client.device_flow.get_token             # 使用 Device 授权流程
+    client.refresh                           # Access Token刷新方式
+    ```
+4. `Baidu::Session` 包含授权信息
+
+    ```ruby
+    session = client.code_flow.get_token
+    session = client.device_flow.get_token
+    ...
+    ```
+
+### Authorization Code 授权流程示例：
+
+```ruby
+# 1. Edit and save this snippet as code.rb
+# 2. Run by: ruby coce.rb
+# 3. Visit: http://localhost:4567/auth
+
+require 'sinatra'
+require 'baidu/oauth'
+
+Baidu.config do |c|
+  c.client_id     = ENV['BAIDU_CLIENT_ID']      # Change to your client_id
+  c.client_secret = ENV['BAIDU_CLIENT_SECRET']  # Change to your client_secret
+end
+
+# 使用时需要到 http://developer.baidu.com/console 将此 callback 添加到应用安全设置中
+callback_uri = 'http://localhost:4567/auth/callback'
+
+get '/' do
+  'Hello world!'
+end
+
+get '/auth' do
+  client = Baidu::OAuth::Client.new
+  redirect client.code_flow.authorize_url(callback_uri, confirm_login: true)
+end
+
+get '/auth/callback' do
+  begin
+    client = Baidu::OAuth::Client.new
+    session = client.code_flow.get_token params[:code], callback_uri
+    "auth success: #{session.access_token}"
+  rescue => e
+    e.to_s
+  end
+end
+```
+
+## PCS
+要使用 PCS 必须到 [百度开发者中心](http://developer.baidu.com/console) 开启指定应用的 PCS API 权限，参考 [开通PCS API权限](http://developer.baidu.com/wiki/index.php?title=docs/pcs/guide/api_approve)，并获取所设置的文件目录。
+
+文件 API 已经完全实现。API 中涉及到的文件或目录路径，都是相对于开通 PCS API 权限时所设置的文件目录。比如：上传文件时需要指定文件保存路径，假设指定为 `/mydata/hi.png`，那么在 PCS 中实际的保存路径为 `/apps/文件目录/mydata/hi.png`。
+
+1. 全局配置
+    ```ruby
+    Baidu.config do |c|
+        # ...
+        c.pcs_dir_name = 'notes'  # 文件目录名称
+        # ...
+    end
+    ```
+    全局配置非强制性的，可以在创建 `Baidu::PCS::Client` 实例时设置
+
+2. 创建 Baidu::PCS::Client 实例
+    ```ruby
+    require 'baidu/pcs'
+    client = Baidu::PCS::Client.new('token_or_session')
+    # 或者
+    client = Baidu::PCS::Client.new('token_or_session', 'notes')
+    ```
+
+3. API 调用
+    ```ruby
+    File.open('/opt/ubuntu-12.04.3-server-amd64.iso', 'r') do |f|
+        client.upload(f, block_upload: true)
+    end
+    ```
+
+## 异常处理
+API 的异常被封装为 `Baidu::Errors::Error`，包含三个子类：
+
+1. `Baidu::Errors::AuthError`    # Access Token 过期或未授权
+2. `Baidu::Errors::ClientError`  # API 返回 `400+` 错误
+3. `Baidu::Errors::ServerError`  # API 返回 `500+` 错误
+
+`Baidu::Errors::Error => e`，异常的具体信息可以通过如下方式获取到：
+```ruby
+begin
+    client.list('apitest/movies')
+rescue Baidu::Errors::Error => e
+    puts e.code  # 错误代码，详情参考百度开发者中心文档
+    puts e.msg   # 错误描述
+end
+```
+
+## Copyright
+MIT License. Copyright (c) 2013 Lonre Wang.

data/Rakefile

@@ -0,0 +1,4 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)

data/baidu-pcs.gemspec

@@ -0,0 +1,24 @@
+# encoding: UTF-8
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'baidu/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "baidu-sdk"
+  spec.version       = Baidu::VERSION
+  spec.authors       = ["Lonre Wang"]
+  spec.email         = ["me@wanglong.me"]
+  spec.description   = %q{Unofficial Baidu REST api sdk for ruby, including OAuth, PCS, etc.}
+  spec.summary       = %q{Unofficial Baidu REST API SDK for Ruby.}
+  spec.homepage      = "https://github.com/lonre/baidu-sdk-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_runtime_dependency     "multipart-post", "~> 1.2"
+  spec.add_development_dependency "bundler", "~> 1.3"
+end

data/lib/baidu/configure.rb

@@ -0,0 +1,27 @@
+module Baidu
+  module Configure
+    # 申请创建应用后获取的 API Key
+    # @return [String]
+    attr_accessor :client_id
+
+    # 申请创建应用后获取的 Secret Key
+    # @return [String]
+    attr_accessor :client_secret
+
+    # 用来控制是否在终端输出调试信息，主要涉及网络请求部分（Net::HTTP）
+    # @note 请勿在生产环境中打开
+    # @return [Boolean] 默认为 false
+    attr_accessor :debug
+
+    # 通过 block 进行 API 配置
+    #
+    # @yield [c]
+    # @yieldparam c [Configure]
+    # @return [Configure]
+    def config
+      self.debug = false  # 默认 false
+      yield self
+      self
+    end
+  end
+end

data/lib/baidu/core.rb

@@ -0,0 +1,19 @@
+# encoding: UTF-8
+
+require 'json'
+require 'net/https'
+require 'uri'
+require 'baidu/version'
+require 'baidu/session'
+require 'baidu/errors/error'
+require 'baidu/support/util'
+require 'baidu/support/request'
+require 'baidu/configure'
+
+module Baidu
+
+  class << self
+    include Baidu::Configure
+  end
+
+end

data/lib/baidu/errors/error.rb

@@ -0,0 +1,22 @@
+module Baidu
+  module Errors
+    class Error < StandardError
+      attr_reader :msg, :code, :response
+
+      def initialize(msg, code=nil, response=nil)
+        @msg, @code, @response = msg, code, response
+      end
+
+      def to_s
+        arr = %w[Error]
+        arr << "code: #{code}" unless code.nil?
+        arr << "msg: #{msg}"   unless msg.nil?
+        arr.join(' ')
+      end
+    end
+
+    class AuthError < Error; end
+    class ClientError < Error; end
+    class ServerError < Error; end
+  end
+end

data/lib/baidu/oauth.rb

@@ -0,0 +1,11 @@
+require 'baidu/core'
+require 'baidu/oauth/client'
+
+module Baidu
+  module OAuth
+    SITE                   = 'https://openapi.baidu.com'
+    AUTHORIZATION_ENDPOINT = '/oauth/2.0/authorize'
+    TOKEN_ENDPOINT         = '/oauth/2.0/token'
+    DEVICE_ENDPOINT        = '/oauth/2.0/device/code'
+  end
+end

data/lib/baidu/oauth/client.rb

@@ -0,0 +1,66 @@
+# encoding: UTF-8
+
+require 'baidu/oauth/flow/code'
+require 'baidu/oauth/flow/device'
+
+module Baidu
+  module OAuth
+    class Client
+      include Baidu::Support::Request
+
+      # 申请创建应用后获取的 API Key
+      # @return [String]
+      attr_accessor :client_id
+      # 申请创建应用后获取的 Secret Key
+      # @return [String]
+      attr_accessor :client_secret
+      # @private
+      attr_reader :site
+
+      # 创建一个 OAuth API 实例
+      #
+      # @example 如果不使用全局配置，则可以在创建新实例时指定 +client_id+ 和 +client_secret+
+      #   client = Baidu::OAuth::Client.new('a_client_id', 'a_client_secret')
+      def initialize(client_id=Baidu.client_id, client_secret=Baidu.client_secret)
+        @client_id     = client_id
+        @client_secret = client_secret
+        @site          = Baidu::OAuth::SITE
+      end
+
+      # @!method code_flow
+      #   采用 Authorization Code 获取 Access Token 的授权验证流程
+      #   @return [Flow::Code]
+      # @!method device_flow
+      #   采用 Device Code 获取 Access Token 的授权验证流程
+      #   @return [Flow::Device]
+      # @see http://developer.baidu.com/wiki/index.php?title=docs/oauth/authorization Authorization Code
+      # @see http://developer.baidu.com/wiki/index.php?title=docs/oauth/device Device
+      [:code, :device].each do |flow|
+        define_method("#{flow}_flow".to_sym) do
+          Baidu::OAuth::Flow.const_get(flow.capitalize).new self
+        end
+      end
+
+      # 刷新 Access Token
+      #
+      # @param [String] token 用于刷新 Access Token 用的 Refresh Token
+      # @option params [String] :scope 以空格分隔的权限列表，若不传递此参数，代表请求的数据访问操作权限与上次获取 Access Token 时一致。
+      #                                通过 Refresh Token 刷新 Access Token 时所要求的scope权限范围必须小于等于上次获取 Access Token 时授予的权限范围。
+      #                                关于权限的具体信息请参考“{http://developer.baidu.com/wiki/index.php?title=docs/oauth/list 权限列表}”
+      # @return [Baidu::Session]
+      # @see http://developer.baidu.com/wiki/index.php?title=docs/oauth/list 权限列表
+      # @see http://developer.baidu.com/wiki/index.php?title=docs/oauth/overview Access Token 生命周期
+      def refresh(token, params={})
+        body = {
+          grant_type:    'refresh_token',
+          refresh_token: token,
+          client_id:     self.client_id,
+          client_secret: self.client_secret
+        }.update params
+        rest = post Baidu::OAuth::TOKEN_ENDPOINT, nil, body
+        return nil if rest.nil?
+        Baidu::Session.from rest
+      end
+    end
+  end
+end