Module: Koala::Facebook::GraphAPIMethods

Included in:
GraphAPI, GraphAndRestAPI
Defined in:
lib/koala/graph_api.rb

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.included(base) ⇒ Object 



208
209
210
211
212
213
214
 
# File 'lib/koala/graph_api.rb', line 208

def self.included(base)
  base.class_eval do
    def self.batch
      raise NoMethodError, "The BatchAPI signature has changed (the original implementation was not thread-safe).  Please see https://github.com/arsduo/koala/wiki/Batch-requests.  (This message will be removed in the final 1.1 release.)"
    end
  end
end

Instance Method Details

#batch(http_options = {}, &block) ⇒ Object

Batch API



198
199
200
201
202
203
204
205
206
 
# File 'lib/koala/graph_api.rb', line 198

def batch(http_options = {}, &block)
  batch_client = GraphBatchAPI.new(access_token)
  if block
    yield batch_client
    batch_client.execute(http_options)
  else
    batch_client
  end
end

#check_response(response) ⇒ Object 



228
229
230
231
232
233
234
235
 
# File 'lib/koala/graph_api.rb', line 228

def check_response(response)
  # check for Graph API-specific errors
  # this returns an error, which is immediately raised (non-batch)
  # or added to the list of batch results (batch)
  if response.is_a?(Hash) && error_details = response["error"]
    APIError.new(error_details) 
  end
end

#delete_connections(id, connection_name, args = {}, options = {}) ⇒ Object

Raises:



93
94
95
96
97
 
# File 'lib/koala/graph_api.rb', line 93

def delete_connections(id, connection_name, args = {}, options = {})
  # Deletes a given connection
  raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
  graph_call("#{id}/#{connection_name}", args, "delete", options)
end

#delete_like(object_id, options = {}) ⇒ Object

Raises:



171
172
173
174
175
 
# File 'lib/koala/graph_api.rb', line 171

def delete_like(object_id, options = {})
  # Unlikes a given object for the logged-in user
  raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Unliking requires an access token"}) unless @access_token
  graph_call("#{object_id}/likes", {}, "delete", options)
end

#delete_object(id, options = {}) ⇒ Object

Raises:



64
65
66
67
68
 
# File 'lib/koala/graph_api.rb', line 64

def delete_object(id, options = {})
  # Deletes the object with the given ID from the graph.
  raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
  graph_call(id, {}, "delete", options)
end

#get_comments_for_urls(urls = [], args = {}, options = {}) ⇒ Object 



79
80
81
82
83
84
85
 
# File 'lib/koala/graph_api.rb', line 79

def get_comments_for_urls(urls = [], args = {}, options = {})
  # Fetchs the comments for given URLs (array or comma-separated string)
  # see https://developers.facebook.com/blog/post/490
  return [] if urls.empty?
  args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
  get_object("comments", args, options)
end

#get_connections(id, connection_name, args = {}, options = {}) ⇒ Object

Connections



72
73
74
75
76
77
 
# File 'lib/koala/graph_api.rb', line 72

def get_connections(id, connection_name, args = {}, options = {})
  # Fetchs the connections for given object.
  graph_call("#{id}/#{connection_name}", args, "get", options) do |result|
    result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
  end
end

#get_object(id, args = {}, options = {}) ⇒ Object

Objects



34
35
36
37
 
# File 'lib/koala/graph_api.rb', line 34

def get_object(id, args = {}, options = {})
  # Fetchs the given object from the graph.
  graph_call(id, args, "get", options)
end

#get_objects(ids, args = {}, options = {}) ⇒ Object 



39
40
41
42
43
44
 
# File 'lib/koala/graph_api.rb', line 39

def get_objects(ids, args = {}, options = {})
  # Fetchs all of the given objects from the graph.
  # If any of the IDs are invalid, they'll raise an exception.
  return [] if ids.empty?
  graph_call("", args.merge("ids" => ids.respond_to?(:join) ? ids.join(",") : ids), "get", options)
end

#get_page(params) ⇒ Object

GraphCollection support



188
189
190
191
192
193
194
 
# File 'lib/koala/graph_api.rb', line 188

def get_page(params)
  # Pages through a set of results stored in a GraphCollection
  # Used for connections and search results
  graph_call(*params) do |result|
    result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
  end
end

#get_picture(object, args = {}, options = {}) ⇒ Object

Media (photos and videos) to delete photos or videos, use delete_object(object_id) note: you’ll need the user_photos or user_videos permissions to actually access media after upload



103
104
105
106
107
108
 
# File 'lib/koala/graph_api.rb', line 103

def get_picture(object, args = {}, options = {})
  # Gets a picture object, returning the URL (which Facebook sends as a header)
  graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
    result["Location"]
  end
end

#graph_call(path, args = {}, verb = "get", options = {}, &post_processing) ⇒ Object

Direct access to the Facebook API see any of the above methods for example invocations



218
219
220
221
222
223
224
225
226
 
# File 'lib/koala/graph_api.rb', line 218

def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
  result = api(path, args, verb, options) do |response|
    error = check_response(response)
    raise error if error
  end

  # now process as appropriate (get picture header, make GraphCollection, etc.)
  post_processing ? post_processing.call(result) : result
end

#put_comment(object_id, message, options = {}) ⇒ Object

Comments to delete comments, use delete_object(comment_id) to get comments, use get_connections(object, “likes”)



158
159
160
161
 
# File 'lib/koala/graph_api.rb', line 158

def put_comment(object_id, message, options = {})
  # Writes the given comment on the given post.
  self.put_object(object_id, "comments", {:message => message}, options)
end

#put_connections(id, connection_name, args = {}, options = {}) ⇒ Object

Raises:



87
88
89
90
91
 
# File 'lib/koala/graph_api.rb', line 87

def put_connections(id, connection_name, args = {}, options = {})
  # Posts a certain connection
  raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
  graph_call("#{id}/#{connection_name}", args, "post", options)
end

#put_like(object_id, options = {}) ⇒ Object

Likes to get likes, use get_connections(user, “likes”)



166
167
168
169
 
# File 'lib/koala/graph_api.rb', line 166

def put_like(object_id, options = {})
  # Likes the given post.
  self.put_object(object_id, "likes", {}, options)
end

#put_object(parent_object, connection_name, args = {}, options = {}) ⇒ Object

Raises:



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
 
# File 'lib/koala/graph_api.rb', line 46

def put_object(parent_object, connection_name, args = {}, options = {})
  # Writes the given object to the graph, connected to the given parent.
  # See http://developers.facebook.com/docs/api#publishing for all of
  # the supported writeable objects.
  # 
  # For example,
  #     graph.put_object("me", "feed", :message => "Hello, world")
  # writes "Hello, world" to the active user's wall.
  #
  # Most write operations require extended permissions. For example,
  # publishing wall posts requires the "publish_stream" permission. See
  # http://developers.facebook.com/docs/authentication/ for details about
  # extended permissions.
    
  raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
  graph_call("#{parent_object}/#{connection_name}", args, "post", options)
end

#put_picture(*picture_args) ⇒ Object

Can be called in multiple ways:

put_picture(file, [content_type], ...)
put_picture(path_to_file, [content_type], ...)

You can pass in uploaded files directly from Rails or Sinatra. (See lib/koala/uploadable_io.rb for supported frameworks)

Optional parameters can be added to the end of the argument list:

  • args: a hash of request parameters (default: {})

  • target_id: ID of the target where to post the picture (default: “me”)

  • options: a hash of http options passed to the HTTPService module

    put_picture(file, content_type, => “Message”, 01234560) put_picture(params, => “Message”)



126
127
128
 
# File 'lib/koala/graph_api.rb', line 126

def put_picture(*picture_args)
  put_object(*parse_media_args(picture_args, "photos"))
end

#put_video(*video_args) ⇒ Object 



130
131
132
133
134
 
# File 'lib/koala/graph_api.rb', line 130

def put_video(*video_args)
  args = parse_media_args(video_args, "videos")
  args.last[:video] = true
  put_object(*args)
end

#put_wall_post(message, attachment = {}, profile_id = "me", options = {}) ⇒ Object

Wall posts To get wall posts, use get_connections(user, “feed”) To delete a wall post, just use delete_object(post_id)



140
141
142
143
144
145
146
147
148
149
150
151
152
 
# File 'lib/koala/graph_api.rb', line 140

def put_wall_post(message, attachment = {}, profile_id = "me", options = {})
  # attachment is a hash describing the wall post
  # (see X for more details)
  # For instance, 
  # 
  #     {"name" => "Link name"
  #      "link" => "http://www.example.com/",
  #      "caption" => "{*actor*} posted a new review",
  #      "description" => "This is a longer description of the attachment",
  #      "picture" => "http://www.example.com/thumbnail.jpg"}

  self.put_object(profile_id, "feed", attachment.merge({:message => message}), options)
end

#search(search_terms, args = {}, options = {}) ⇒ Object

Search



179
180
181
182
183
184
 
# File 'lib/koala/graph_api.rb', line 179

def search(search_terms, args = {}, options = {})
  args.merge!({:q => search_terms}) unless search_terms.nil?
  graph_call("search", args, "get", options) do |result|
    result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
  end
end