sharepoint-ruby 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9066e1d5499871de09ed46063dd308a81980f9e108bcdcb833092e05c4aa3f98
-  data.tar.gz: fda3bfa38a5730aa6328370f0a46e7aced79271851eb9eb02765f17e939b19db
+  metadata.gz: 06a548cde4c7aede93cbc0f46fd90e5343faff5f64e4d18bb877cf4ce4bdbf7e
+  data.tar.gz: 5b34f39ca74c0583f3dc5d509639f1dbe73972477aa2a259e6a741b7a0cbd649
 SHA512:
-  metadata.gz: '0091b8b591e50ef402cb9f06b3922a50126e4c2e2818df1c3f318ab06aeedadbb07cd7f3d436ae2cbc6265f4965fa4e05f6a589d9389f68af43a513e4faacf38'
-  data.tar.gz: 6b0cc5c1f06c2296168a3eb967c5b856dbfbc73202872df3b54c6102a021dc7cb6c245368725d786a409587406510119fecd661e8f86825808e90e48a07ccf02
+  metadata.gz: '0708c3ab5cf9238fd35617ebf07d634ef7ad0c766efec37f47ed4050938fc4aaecddc793b1a9ff4ce5e2ccc32cc0c829e650ad87ecf73abe3b5b1b6e4c857446'
+  data.tar.gz: ef28ea0e00baee2d803a30a36fedbb8b48e03e637972033e002db56fd401f8af33214bc30fb525275f41cb0503e8e3f5833e06bb6bef3cf46df21c94b7dcfdfb

data/README.md

@@ -0,0 +1,167 @@
+sharepoint-ruby
+===============
+A ruby gem that maps Sharepoint's REST API in a simple and accessible fashion.
+
+How to use
+===============
+First, you'll have to initialize a sharepoint site and open a session in order to start making requests to the REST API:
+
+```Ruby
+require 'sharepoint-ruby'
+
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'server-relative-site-url'
+site.session.authenticate 'mylogin', 'mypassword'
+
+blog = Sharepoint::Site.new 'mytenant.sharepoint.com', 'sites/blog'
+blog.session.authenticate 'user', 'pwd'
+lists = blog.lists
+for l in lists
+  puts l.title
+end
+```
+
+Note that site.session.authenticate might throw an exception if the authentication doesn't go well (wrong urls, STS unavailable, or wrong login/password).
+The exceptions might be of type ConnectionToStsFailed, AuthenticationFailed, ConnexionToSharepointFailed, UnknownAuthenticationError.
+
+### Connecting to your own STS
+By default, sharepoint-ruby uses Microsoft's STS (https://login.microsoftonline.com/extSTS.srf), which works for Sharepoint Online. You may use your own STS by using the optional third parameter of Sharepoint::Site.new:
+
+```Ruby
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
+site.session.authenticate  'username', 'password', 'https://sts_url.com/extSTS.srf'
+```
+
+### Connecting using NTLM
+You may also connect using the NTLM method. For that purpose, you'll have to overwrite the default session handler with `Sharepoint::HttpAuth::Session`.
+
+```Ruby
+require 'sharepoint-http-auth'
+
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
+site.session = Sharepoint::HttpAuth::Session.new site
+site.session.authenticate 'login', 'password'
+site.protocole = 'http' # default protocole is https: don't forget to set this if you use http.
+```
+
+### Connecting using Kerberos
+You may also connect using Kerberos if you're using *MIT Kerberos*. 
+For that purpose, you'll have to overwrite the default session handler with `Sharepoint::KerberosAuth::Session`.
+
+```Ruby
+require 'sharepoint-kerberos-auth'
+
+site = Sharepoint::Site.new 'mysite.sharepoint.com', 'site-name'
+site.session = Sharepoint::KerberosAuth::Session.new site
+site.session.authenticate 'login', 'password'
+site.protocole = 'http' # default protocole is https: don't forget to set this if you use http.
+```
+
+### General features
+
+Once you're logged in, you may access the site's ressource through the site object:
+```Ruby
+fields  = site.fields # Get all the site's fields
+groups  = site.groups # Get all the site's groups
+users   = site.users  # Get all the site's users
+
+lists = site.lists # Get all the site's list
+list  = site.list 'Documents' # Get a list by title
+list  = site.list '51925dd7-2108-481a-b1ef-4bfa4e69d48b' # Get a list by guid
+views = list.views # Get all the lists views
+
+folders = site.folders # Get all the site's folder
+folder  = site.folder '/SiteAssets/documents' # Get a folder by server relative path
+files   = folder.files # Get all the folder's files
+```
+
+### OData mapping
+When Sharepoint answers with an OData object, the `site.query` method will automatically map it to the corresponding Sharepoint::Object class.
+For instance, if Sharepoint answered with an OData object of type 'SP.List', `site.query` will return an instance of the Sharepoint::List class. These classes implement a getter and a setter for all the properties declared for the corresponding object in Sharepoint's 2013 Documentation.
+
+N.B: Note that the setter only exists if the property is declared as write-accessible in the documentation.
+N.B#2: Note that despite the camel casing used by Sharepoint, the getter and setter are snake cased (i.e: the CustomMasterUrl property becomes accessible through the custom_master_url getter and custom_mater_url= getter).
+
+#### Sharepoint::Object specifics
+Sharepoint::Object contains a few methods to help you handle your objects:
+
+The `guid` method can be used to retrieve the guid of any object.
+
+The `reload` method returns an instance of the same object from the remote sharepoint site. It may be useful if you want to be sure that your object contains the latest changes.
+
+The `save` method will automatically compile your changes and perform the MERGE request with the Sharepoint site.
+
+The `destroy` method will destroy the remote ressource on the Sharepoint site.
+
+The `copy` method can duplicate an existing object. If you send it a Sharepoint::Object as a parameter, it will duplicate into the parameter. If you don't send any parameter, it will create a new object. Note that no changes happen on the sharepoint site until you've called the `save` method on the returned object.
+
+### Deferred objects
+Some of the properties of the OData object are 'deferred', which means that the property only provides a link to a ressource that you would have to get for yourself.
+Not with the sharepoint-ruby gem however: the first time you try to access a deferred property, the object will on it's own go look for the corresponding remote ressource: the result will be stored for later uses, and then be returned to you.
+
+### Modifying Sharepoint's ressources
+The Sharepoint REST API provides us with methods to create, update or delete resources. In the Sharepoint::Object, these behaviours are implemented through the save and delete methods.
+
+##### Updating objects
+This piece of code will change the custom master page used by the Sharepoint site to 'oslo.master':
+```Ruby
+  web = site.context_info # Sharepoint::Site.context_info returns the Web object for the current site (see: http://msdn.microsoft.com/en-us/library/office/dn499819(v=office.15).aspx )
+  web.custom_master_url = '/_catalogs/masterpage/oslo.master'
+  web.save
+```
+
+##### Creating objects
+You may also create your own objects. This will be slightly different: we will create our own instance of a Sharepoint::List object.
+Some Sharepoint objects have values that can only be set during their initialization: `sharepoint-ruby` doesn't allow you to set these values through a setter.
+In the case of list, Sharepoint will require you to specify the value for the `BaseTemplate` property. This is how you would specify the default value for an attribute that isn't write-accessible:
+```Ruby
+  list             = Sharepoint::List.new site, { 'BaseTemplate' => Sharepoint::LIST_TEMPLATE_TYPE[:GenericList] }
+  list.title       = 'My new list'
+  list.description = 'A list created by sharepoint-ruby'
+  list             = list.save # At creation, the remote object created will be returned by the save method.
+```
+Note that the attribute's name in the constructor remains camel cased (`BaseTemplate`), though the getter for this attribute is still snake cased (`base_template`).
+
+##### Destroying objects
+Now, say you want to destroy the list you just created, this will do nicely:
+```Ruby
+  list.destroy
+```
+
+### Parenting
+In the previous paragraph, we saw how to create a Sharepoint::List object. Sharepoint lists aren't parented to any other objects: Sharepoint views however are parented to a list. If you wanted to create a view for the list we just created, you would have to specify a parent for the view:
+
+```Ruby
+  view               = Sharepoint::View.new site
+  view.title         = 'My new view'
+  view.personal_view = false
+  view.parent        = list # Setting the view's parent to the Sharepoint::List
+  view.save
+```
+
+### Collections
+In sharepoint-ruby, collections are merely arrays of Sharepoint::Objects. If you wish to add an object to a colleciton, set the parent to the object providing the collection.
+
+### List Items
+Sharepoint doesn't allow the user to fetch more than 100 items per query. When your list contains more than a 100 items, you may fetch them using the `find_items` method:
+
+```Ruby
+  list = site.list 'My List'
+  # Use the skip option to paginate
+  list.find_items skip: 50 # returns items from 50-150
+  # You may use other operators in your query, such as orderby, select, filter and top:
+  list.find_items skip: 100, orderby: 'Title asc'
+```
+
+### Exceptions
+Inevitably, some of your requests will fail. The object sharepoint returns when an error happens is also mapped by sharepoint-ruby in the Sharepoint::SPException class.
+The SPException class contains methods to inspect the query that was made to the server:
+
+```Ruby
+  begin
+    list = site.list 'title that does not exists'
+  rescue Sharepoint::SPException => e
+    puts "Sharepoint complained about something: #{e.message}"
+    puts "The action that was being executed was: #{e.uri}"
+    puts "The request had a body: #{e.request_body}" unless e.request_body.nil?
+  end
+```

data/lib/sharepoint-data.rb

@@ -0,0 +1,5 @@
+module Sharepoint
+  module Data
+
+  end
+end

data/lib/sharepoint-errors.rb

@@ -0,0 +1,34 @@
+module Sharepoint
+  class Error < StandardError; end
+
+  class RequestError < Error; end
+  class DataError < Error
+    def initialize data, uri = nil, body = nil
+      @data = data['error']
+      @uri  = uri
+      @body = body
+    end
+
+    def lang         ; @data['message']['lang']  ; end
+    def message      ; @data['message']['value'] ; end
+    def code         ; @data['code'] ; end
+    def uri          ; @uri ; end
+    def request_body ; @body ; end
+  end
+
+  # @deprecated Use DataError instead
+  SPException = DataError
+  deprecate_constant :SPException
+
+  class UnsupportedType < Error
+    attr_accessor :type_name
+
+    def initialize type_name
+      @type_name = type_name
+    end
+
+    def message
+      "unsupported type '#{@type_name}'"
+    end
+  end
+end

data/lib/sharepoint-files.rb

@@ -1,4 +1,6 @@
+require 'sharepoint-errors'
 require 'open-uri'
+require 'securerandom'
 
 module Sharepoint
   class Folder < Sharepoint::Object
@@ -24,6 +26,12 @@ module Sharepoint
       body = { '__metadata' => { 'type' => 'SP.Folder' }, 'ServerRelativeUrl' => name.to_s }
       @site.query :post, uri, body.to_json
     end
+
+    def add_file_via_streaming name, file
+      add_file name, nil
+      spo_file = file_from_name name
+      spo_file.upload_file_via_streaming file
+    end
   end
 
   class File < Sharepoint::Object
@@ -60,6 +68,24 @@ module Sharepoint
         file.write content
       end
     end
+
+    def upload_file_via_streaming file
+      uuid = SecureRandom.uuid
+      bytes_written = 0
+      ::File.open(file) do |fh|
+        while data = fh.read(10 * 1024 * 1024) do
+          uri = (bytes_written == 0) ? "#{__metadata['uri']}/startupload(uploadId=guid'#{uuid}')" : "#{__metadata['uri']}/continueupload(uploadId=guid'#{uuid}',fileOffset=#{bytes_written})"
+          result = @site.query :post, uri, data, skip_json: true
+          new_position = (JSON.parse(result).dig('d', 'ContinueUpload') || JSON.parse(result).dig('d', 'StartUpload')).to_i
+          bytes_written += data.size
+          if new_position != bytes_written
+            raise Sharepoint::Error.new("Streamed #{bytes_written} bytes data, but sharepoint reports position #{new_position}")
+          end
+        end
+      end
+      uri = "#{__metadata['uri']}/finishupload(uploadId=guid'#{uuid}',fileOffset=#{bytes_written})"
+      result = @site.query :post, uri, nil, skip_json: true
+    end
   end
 
   class FileVersion < Sharepoint::Object

data/lib/sharepoint-lists.rb

@@ -113,7 +113,7 @@ module Sharepoint
         item_id = response['d']['ID']
         @site.query :get, "#{site_url}_api/#{__metadata['id']}/items(#{item_id})"
       else
-        raise Sharepoint::SPException.new response, action, payload
+        raise Sharepoint::DataError.new response, action, payload
       end
     end
 

data/lib/sharepoint-ruby.rb

@@ -1,24 +1,11 @@
 require 'curb'
 require 'json'
+require 'sharepoint-errors'
 require 'sharepoint-session'
 require 'sharepoint-object'
 require 'sharepoint-types'
 
 module Sharepoint
-  class SPException < Exception
-    def initialize data, uri = nil, body = nil
-      @data = data['error']
-      @uri  = uri
-      @body = body
-    end
-
-    def lang         ; @data['message']['lang']  ; end
-    def message      ; @data['message']['value'] ; end
-    def code         ; @data['code'] ; end
-    def uri          ; @uri ; end
-    def request_body ; @body ; end
-  end
-
   class Site
     attr_reader   :server_url
     attr_accessor :url, :protocol
@@ -80,14 +67,16 @@ module Sharepoint
         @session.send :curl, curl unless not @session.methods.include? :curl
         block.call curl           unless block.nil?
       end
-      unless skip_json || (result.body_str.nil? || result.body_str.empty?)
+      if !(skip_json || (result.body_str.nil? || result.body_str.empty?))
         begin
           data = JSON.parse result.body_str
-          raise Sharepoint::SPException.new data, uri, body unless data['error'].nil?
+          raise Sharepoint::DataError.new data, uri, body unless data['error'].nil?
           make_object_from_response data
         rescue JSON::ParserError => e
-          raise Exception.new("Exception with body=#{body}, e=#{e.inspect}, #{e.backtrace.inspect}, response=#{result.body_str}")
+          raise Sharepoint::RequestError.new("Exception with body=#{body}, e=#{e.inspect}, #{e.backtrace.inspect}, response=#{result.body_str}")
         end
+      elsif result.status.to_i >= 400
+        raise Sharepoint::RequestError.new("#{method.to_s.upcase} #{uri} responded with #{result.status}")
       else
         result.body_str
       end
@@ -119,10 +108,10 @@ module Sharepoint
       type_parts = type_name.split '.'
       type_name  = type_parts.pop
       constant   = Sharepoint
-      type_parts.each do |part| constant = constant.const_get part end
+      type_parts.each do |part| constant = constant.const_get(part, false) end
 
-      klass      = constant.const_get type_name rescue nil
-      if klass
+      if constant.const_defined? type_name
+        klass = constant.const_get type_name rescue nil
         klass.new self, data
       else
         Sharepoint::GenericSharepointObject.new type_name, self, data

data/lib/sharepoint-session.rb

@@ -28,12 +28,11 @@ module Sharepoint
   end
 
   class Session
-    class ConnexionToStsFailed < Exception ; end
-    class ConnexionToSharepointFailed < Exception; end
-    class UnknownAuthenticationError  < Exception; end
-    class AuthenticationFailed < Exception
-      def initialize message ; super message ; end
-    end
+    class Error < Sharepoint::Error; end
+    class ConnexionToStsFailed        < Sharepoint::Session::Error; end
+    class ConnexionToSharepointFailed < Sharepoint::Session::Error; end
+    class UnknownAuthenticationError  < Sharepoint::Session::Error; end
+    class AuthenticationFailed        < Sharepoint::Session::Error; end
 
     attr_accessor :site
 

data/lib/sharepoint-types.rb

@@ -1,18 +1,6 @@
 require 'sharepoint-object'
 
 module Sharepoint
-  class UnsupportedType < ::Exception
-    attr_accessor :type_name
-
-    def initialize type_name
-      @type_name = type_name
-    end
-
-    def message
-      "unsupported type '#{@type_name}'"
-    end
-  end
-
   module Type
     def initialize site, data = nil
       data               ||= Hash.new
@@ -28,6 +16,7 @@ require 'sharepoint-users'
 require 'sharepoint-lists'
 require 'sharepoint-files'
 require 'sharepoint-fields'
+require 'sharepoint-data'
 require 'date'
 
 module Sharepoint

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sharepoint-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Michael Martin Moro
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-02-11 00:00:00.000000000 Z
+date: 2021-01-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: curb
@@ -36,6 +36,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
+- lib/sharepoint-data.rb
+- lib/sharepoint-errors.rb
 - lib/sharepoint-fields.rb
 - lib/sharepoint-files.rb
 - lib/sharepoint-http-auth.rb
@@ -53,7 +56,7 @@ homepage: https://github.com/Plaristote/sharepoint-ruby
 licenses:
 - BSD
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -68,9 +71,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
+rubyforge_project:
 rubygems_version: 2.7.9
-signing_key: 
+signing_key:
 specification_version: 4
 summary: sharepoint client
 test_files: []