Module: Koala::Facebook::GraphAPIMethods
- Included in:
- API
- Defined in:
- lib/koala/api/graph_api.rb
Overview
Methods used to interact with the Facebook Graph API.
See github.com/arsduo/koala/wiki/Graph-API for a general introduction to Koala and the Graph API.
The Graph API is made up of the objects in Facebook (e.g., people, pages, events, photos, etc.) and the connections between them (e.g., friends, photo tags, event RSVPs, etc.). Koala provides access to those objects types in a generic way. For example, given an OAuth access token, this will fetch the profile of the active user and the list of the user’s friends:
You can see a list of all of the objects and connections supported by the API at developers.facebook.com/docs/reference/api/.
You can obtain an access token via OAuth or by using the Facebook JavaScript SDK. If you’re using the JavaScript SDK, you can use the OAuth#get_user_from_cookie method to get the OAuth access token for the active user from the cookie provided by Facebook. See the Koala and Facebook documentation for more information.
Instance Method Summary collapse
-
#batch(http_options = {}, &block) ⇒ Object
Execute a set of Graph API calls as a batch.
-
#debug_token(input_token, &block) ⇒ Object
Get an access token information The access token used to instantiate the API object needs to be the app access token or a valid User Access Token from a developer of the app.
-
#delete_connections(id, connection_name, args = {}, options = {}, &block) ⇒ Object
Delete an object’s connection (for instance, unliking the object).
-
#delete_like(id, options = {}, &block) ⇒ Object
Unlike a given object.
-
#delete_object(id, options = {}, &block) ⇒ Object
Delete an object from the Graph if you have appropriate permissions.
-
#fql_multiquery(queries = {}, args = {}, options = {}, &block) ⇒ Object
Make an FQL multiquery.
-
#fql_query(query, args = {}, options = {}, &block) ⇒ Object
Make an FQL query.
-
#get_comments_for_urls(urls = [], args = {}, options = {}, &block) ⇒ Object
Fetches the comments from fb:comments widgets for a given set of URLs (array or comma-separated string).
-
#get_connection(id, connection_name, args = {}, options = {}, &block) ⇒ Koala::Facebook::API::GraphCollection
(also: #get_connections)
Fetch information about a given connection (e.g. type of activity – feed, events, photos, etc.) for a specific user.
-
#get_object(id, args = {}, options = {}, &block) ⇒ Object
Get information about a Facebook object.
-
#get_object_metadata(id, &block) ⇒ Object
Get the metadata of a Facebook object, including its type.
-
#get_objects(ids, args = {}, options = {}, &block) ⇒ Object
Get information about multiple Facebook objects in one call.
-
#get_page(params, &block) ⇒ Object
Certain calls such as #get_connections return an array of results which you can page through forwards and backwards (to see more feed stories, search results, etc.).
-
#get_page_access_token(id, args = {}, options = {}, &block) ⇒ Object
Get a page’s access token, allowing you to act as the page.
-
#get_picture(object, args = {}, options = {}, &block) ⇒ Object
Fetches a photo url.
-
#get_picture_data(object, args = {}, options = {}, &block) ⇒ Object
Fetches a photo data hash.
- #get_user_picture_data(*args, &block) ⇒ Object
-
#graph_call(path, args = {}, verb = "get", options = {}) { ... } ⇒ Object
Make a call directly to the Graph API.
-
#put_comment(id, message, options = {}, &block) ⇒ Object
Comment on a given object.
-
#put_connections(id, connection_name, args = {}, options = {}, &block) ⇒ Object
Write an object to the Graph for a specific user.
-
#put_like(id, options = {}, &block) ⇒ Object
Like a given object.
-
#put_object(parent_object, connection_name, args = {}, options = {}, &block) ⇒ Object
Write an object to the Graph for a specific user.
-
#put_picture(*picture_args, &block) ⇒ Object
Upload a photo.
-
#put_video(*video_args, &block) ⇒ Object
Upload a video.
-
#put_wall_post(message, attachment = {}, target_id = "me", options = {}, &block) ⇒ Object
Write directly to the user’s wall.
-
#search(search_terms, args = {}, options = {}, &block) ⇒ Koala::Facebook::API::GraphCollection
Search for a given query among visible Facebook objects.
-
#set_app_restrictions(app_id, restrictions_hash, args = {}, options = {}, &block) ⇒ Object
App restrictions require you to JSON-encode the restriction value.
Instance Method Details
#batch(http_options = {}, &block) ⇒ Object
Execute a set of Graph API calls as a batch. See batch request documentation for more information and examples.
511 512 513 514 515 516 517 518 519 |
# File 'lib/koala/api/graph_api.rb', line 511 def batch( = {}, &block) batch_client = GraphBatchAPI.new(self) if block yield batch_client batch_client.execute() else batch_client end end |
#debug_token(input_token, &block) ⇒ Object
Get an access token information The access token used to instantiate the API object needs to be the app access token or a valid User Access Token from a developer of the app. See developers.facebook.com/docs/howtos/login/debugging-access-tokens/#step1
427 428 429 430 431 |
# File 'lib/koala/api/graph_api.rb', line 427 def debug_token(input_token, &block) access_token_info = graph_call("debug_token", {:input_token => input_token}) block ? block.call(access_token_info) : access_token_info end |
#delete_connections(id, connection_name, args = {}, options = {}, &block) ⇒ Object
to access connections like /user_id/CONNECTION/other_user_id, simply pass “CONNECTION/other_user_id” as the connection_name
Delete an object’s connection (for instance, unliking the object).
176 177 178 179 180 |
# File 'lib/koala/api/graph_api.rb', line 176 def delete_connections(id, connection_name, args = {}, = {}, &block) # Deletes a given connection raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token graph_call("#{id}/#{connection_name}", args, "delete", , &block) end |
#delete_like(id, options = {}, &block) ⇒ Object
Unlike a given object. Convenience method equivalent to delete_connection(id, “likes”).
337 338 339 340 341 |
# File 'lib/koala/api/graph_api.rb', line 337 def delete_like(id, = {}, &block) # Unlikes a given object for the logged-in user raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless @access_token graph_call("#{id}/likes", {}, "delete", , &block) end |
#delete_object(id, options = {}, &block) ⇒ Object
Delete an object from the Graph if you have appropriate permissions.
108 109 110 111 112 |
# File 'lib/koala/api/graph_api.rb', line 108 def delete_object(id, = {}, &block) # Deletes the object with the given ID from the graph. raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token graph_call(id, {}, "delete", , &block) end |
#fql_multiquery(queries = {}, args = {}, options = {}, &block) ⇒ Object
Make an FQL multiquery. This method simplifies the result returned from multiquery into a more logical format.
392 393 394 395 396 397 398 399 |
# File 'lib/koala/api/graph_api.rb', line 392 def fql_multiquery(queries = {}, args = {}, = {}, &block) resolved_results = if results = get_object("fql", args.merge(:q => JSON.dump(queries)), ) # simplify the multiquery result format results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome} end block ? block.call(resolved_results) : resolved_results end |
#fql_query(query, args = {}, options = {}, &block) ⇒ Object
Make an FQL query. Convenience method equivalent to get_object(“fql”, :q => query).
371 372 373 |
# File 'lib/koala/api/graph_api.rb', line 371 def fql_query(query, args = {}, = {}, &block) get_object("fql", args.merge(:q => query), , &block) end |
#get_comments_for_urls(urls = [], args = {}, options = {}, &block) ⇒ Object
Fetches the comments from fb:comments widgets for a given set of URLs (array or comma-separated string). See developers.facebook.com/blog/post/490.
442 443 444 445 446 |
# File 'lib/koala/api/graph_api.rb', line 442 def get_comments_for_urls(urls = [], args = {}, = {}, &block) return [] if urls.empty? args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls) get_object("comments", args, , &block) end |
#get_connection(id, connection_name, args = {}, options = {}, &block) ⇒ Koala::Facebook::API::GraphCollection Also known as: get_connections
to access connections like /user_id/CONNECTION/other_user_id, simply pass “CONNECTION/other_user_id” as the connection_name
Fetch information about a given connection (e.g. type of activity – feed, events, photos, etc.) for a specific user. See Facebook’s documentation for a complete list of connections.
128 129 130 131 |
# File 'lib/koala/api/graph_api.rb', line 128 def get_connection(id, connection_name, args = {}, = {}, &block) # Fetches the connections for given object. graph_call("#{id}/#{connection_name}", args, "get", , &block) end |
#get_object(id, args = {}, options = {}, &block) ⇒ Object
Get information about a Facebook object.
55 56 57 58 |
# File 'lib/koala/api/graph_api.rb', line 55 def get_object(id, args = {}, = {}, &block) # Fetches the given object from the graph. graph_call(id, args, "get", , &block) end |
#get_object_metadata(id, &block) ⇒ Object
Get the metadata of a Facebook object, including its type.
69 70 71 72 |
# File 'lib/koala/api/graph_api.rb', line 69 def (id, &block) result = graph_call(id, {"metadata" => "1"}, "get", {}, &block) result["metadata"] end |
#get_objects(ids, args = {}, options = {}, &block) ⇒ Object
Get information about multiple Facebook objects in one call.
84 85 86 87 88 89 |
# File 'lib/koala/api/graph_api.rb', line 84 def get_objects(ids, args = {}, = {}, &block) # Fetches 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", , &block) end |
#get_page(params, &block) ⇒ Object
You’ll rarely need to use this method unless you’re using Sinatra or another non-Rails framework (see GraphCollection for more information).
Certain calls such as #get_connections return an array of results which you can page through forwards and backwards (to see more feed stories, search results, etc.). Those methods use get_page to request another set of results from Facebook.
473 474 475 |
# File 'lib/koala/api/graph_api.rb', line 473 def get_page(params, &block) graph_call(*params, &block) end |
#get_page_access_token(id, args = {}, options = {}, &block) ⇒ Object
Get a page’s access token, allowing you to act as the page. Convenience method for @api.get_object(page_id, :fields => “access_token”).
410 411 412 413 414 415 416 |
# File 'lib/koala/api/graph_api.rb', line 410 def get_page_access_token(id, args = {}, = {}, &block) access_token = get_object(id, args.merge(:fields => "access_token"), ) do |result| result ? result["access_token"] : nil end block ? block.call(access_token) : access_token end |
#get_picture(object, args = {}, options = {}, &block) ⇒ Object
to delete photos or videos, use delete_object(id)
Fetches a photo url. Note that this method returns the picture url, not the full API response. For the hash containing the full metadata for the photo, use #get_user_picture_data instead.
194 195 196 197 198 199 200 201 202 |
# File 'lib/koala/api/graph_api.rb', line 194 def get_picture(object, args = {}, = {}, &block) Koala::Utils.deprecate("API#get_picture will be removed in a future version. Please use API#get_picture_data, which returns a hash including the url.") get_user_picture_data(object, args, ) do |result| # Try to extract the URL result = result.fetch('data', {})['url'] if result.respond_to?(:fetch) block ? block.call(result) : result end end |
#get_picture_data(object, args = {}, options = {}, &block) ⇒ Object
Fetches a photo data hash.
211 212 213 214 215 216 217 218 |
# File 'lib/koala/api/graph_api.rb', line 211 def get_picture_data(object, args = {}, = {}, &block) # The default response for a Graph API query like GET /me/picture is to # return a 302 redirect. This is a surprising difference from the # common return type, so we add the `redirect: false` parameter to get # a RESTful API response instead. args = args.merge(:redirect => false) graph_call("#{object}/picture", args, "get", , &block) end |
#get_user_picture_data(*args, &block) ⇒ Object
220 221 222 223 |
# File 'lib/koala/api/graph_api.rb', line 220 def get_user_picture_data(*args, &block) Koala::Utils.deprecate("API#get_user_picture_data is deprecated and will be removed in a future version. Please use API#get_picture_data, which has the same signature.") get_picture_data(*args, &block) end |
#graph_call(path, args = {}, verb = "get", options = {}) { ... } ⇒ Object
Make a call directly to the Graph API. (See any of the other methods for example invocations.)
538 539 540 541 542 543 544 545 546 547 548 549 550 551 |
# File 'lib/koala/api/graph_api.rb', line 538 def graph_call(path, args = {}, verb = "get", = {}, &post_processing) # enable appsecret_proof by default = {:appsecret_proof => true}.merge() if @app_secret result = api(path, args, verb, ) do |response| error = check_response(response.status, response.body, response.headers) raise error if error end # turn this into a GraphCollection if it's pageable result = GraphCollection.evaluate(result, self) # now process as appropriate for the given call (get picture header, etc.) post_processing ? post_processing.call(result) : result end |
#put_comment(id, message, options = {}, &block) ⇒ Object
Comment on a given object. Convenience method equivalent to put_connection(id, “comments”).
To delete comments, use delete_object(comment_id). To get comments, use get_connections(object, “likes”).
309 310 311 312 |
# File 'lib/koala/api/graph_api.rb', line 309 def put_comment(id, , = {}, &block) # Writes the given comment on the given post. put_connections(id, "comments", {:message => }, , &block) end |
#put_connections(id, connection_name, args = {}, options = {}, &block) ⇒ Object
to access connections like /user_id/CONNECTION/other_user_id, simply pass “CONNECTION/other_user_id” as the connection_name
Write an object to the Graph for a specific user. See Facebook’s documentation for all the supported writeable objects. It is important to note that objects take the singular form, i.e. “event” when using put_connections.
Most write operations require extended permissions. For example, publishing wall posts requires the “publish_stream” permission. See developers.facebook.com/docs/authentication/ for details about extended permissions.
158 159 160 161 162 163 |
# File 'lib/koala/api/graph_api.rb', line 158 def put_connections(id, connection_name, args = {}, = {}, &block) # Posts a certain connection raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless @access_token graph_call("#{id}/#{connection_name}", args, "post", , &block) end |
#put_like(id, options = {}, &block) ⇒ Object
Like a given object. Convenience method equivalent to put_connections(id, “likes”).
To get a list of a user’s or object’s likes, use get_connections(id, “likes”).
324 325 326 327 |
# File 'lib/koala/api/graph_api.rb', line 324 def put_like(id, = {}, &block) # Likes the given post. put_connections(id, "likes", {}, , &block) end |
#put_object(parent_object, connection_name, args = {}, options = {}, &block) ⇒ Object
put_object is (for historical reasons) the same as put_connections. Please use put_connections; in a future version of Koala (2.0?), put_object will issue a POST directly to an individual object, not to a connection.
Write an object to the Graph for a specific user.
97 98 99 |
# File 'lib/koala/api/graph_api.rb', line 97 def put_object(parent_object, connection_name, args = {}, = {}, &block) put_connections(parent_object, connection_name, args, , &block) end |
#put_picture(*picture_args, &block) ⇒ Object
to access the media after upload, you’ll need the user_photos or user_videos permission as appropriate.
Upload a photo.
This can be called in multiple ways:
put_picture(file, [content_type], ...)
put_picture(path_to_file, [content_type], ...)
put_picture(picture_url, ...)
You can also pass in uploaded files directly from Rails or Sinatra. See the Koala wiki for more information.
249 250 251 |
# File 'lib/koala/api/graph_api.rb', line 249 def put_picture(*picture_args, &block) put_connections(*parse_media_args(picture_args, "photos"), &block) end |
#put_video(*video_args, &block) ⇒ Object
Upload a video. Functions exactly the same as put_picture (URLs supported as of Facebook API version 2.3).
256 257 258 259 260 |
# File 'lib/koala/api/graph_api.rb', line 256 def put_video(*video_args, &block) args = parse_media_args(video_args, "videos") args.last[:video] = true put_connections(*args, &block) end |
#put_wall_post(message, attachment = {}, target_id = "me", options = {}, &block) ⇒ Object
Write directly to the user’s wall. Convenience method equivalent to put_connections(id, “feed”).
To get wall posts, use get_connections(user, “feed”) To delete a wall post, use delete_object(post_id)
289 290 291 292 293 294 295 |
# File 'lib/koala/api/graph_api.rb', line 289 def put_wall_post(, = {}, target_id = "me", = {}, &block) if properties = .delete(:properties) || .delete("properties") properties = JSON.dump(properties) if properties.is_a?(Hash) || properties.is_a?(Array) ["properties"] = properties end put_connections(target_id, "feed", .merge({:message => }), , &block) end |
#search(search_terms, args = {}, options = {}, &block) ⇒ Koala::Facebook::API::GraphCollection
Search for a given query among visible Facebook objects. See Facebook documentation for more information.
352 353 354 355 |
# File 'lib/koala/api/graph_api.rb', line 352 def search(search_terms, args = {}, = {}, &block) args.merge!({:q => search_terms}) unless search_terms.nil? graph_call("search", args, "get", , &block) end |
#set_app_restrictions(app_id, restrictions_hash, args = {}, options = {}, &block) ⇒ Object
App restrictions require you to JSON-encode the restriction value. This is neither obvious nor intuitive, so this convenience method is provided.
457 458 459 |
# File 'lib/koala/api/graph_api.rb', line 457 def set_app_restrictions(app_id, restrictions_hash, args = {}, = {}, &block) graph_call(app_id, args.merge(:restrictions => JSON.dump(restrictions_hash)), "post", , &block) end |