Class: Koala::Facebook::API

Inherits:
Object
  • Object
show all
Includes:
GraphAPIMethods
Defined in:
lib/koala/api.rb,
lib/koala/api/graph_collection.rb

Defined Under Namespace

Classes: GraphCollection

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from GraphAPIMethods

#batch, #debug_token, #delete_connections, #delete_like, #delete_object, #get_connection, #get_object, #get_object_metadata, #get_objects, #get_page, #get_page_access_token, #get_picture, #get_picture_data, #get_user_picture_data, #put_comment, #put_connections, #put_like, #put_object, #put_picture, #put_video, #put_wall_post, #search, #set_app_restrictions

Constructor Details

#initialize(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret) ⇒ Koala::Facebook::API

Note:

If no access token is provided, you can only access some public information.

Creates a new API client.

Parameters:

  • access_token (String) (defaults to: Koala.config.access_token) —

    access token

  • app_secret (String) (defaults to: Koala.config.app_secret) —

    app secret, for tying your access tokens to your app secret If you provide an app secret, your requests will be signed by default, unless you pass appsecret_proof: false as an option to the API call. (See developers.facebook.com/docs/graph-api/securing-requests/)



18
19
20
21
 
# File 'lib/koala/api.rb', line 18

def initialize(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret)
  @access_token = access_token
  @app_secret = app_secret
end

Instance Attribute Details

#access_token ⇒ Object (readonly)

Returns the value of attribute access_token.



23
24
25
 
# File 'lib/koala/api.rb', line 23

def access_token
  @access_token
end

#app_secret ⇒ Object (readonly)

Returns the value of attribute app_secret.



23
24
25
 
# File 'lib/koala/api.rb', line 23

def app_secret
  @app_secret
end

Instance Method Details

#api(path, args = {}, verb = "get", options = {}) ⇒ Object

Note:

You’ll rarely need to call this method directly.

Makes a request to the appropriate Facebook API.

Parameters:

  • path —

    the server path for this request (leading / is prepended if not present)

  • args (defaults to: {}) —

    arguments to be sent to Facebook

  • verb (defaults to: "get") —

    the HTTP method to use

  • options (defaults to: {}) —

    request-related options for Koala and Faraday. See github.com/arsduo/koala/wiki/HTTP-Services for additional options.

Options Hash (options):

  • :http_component (Symbol) —

    which part of the response (headers, body, or status) to return

  • :format (Symbol) —

    which request format to use. Currently, :json is supported

  • :preserve_form_arguments (Symbol) —

    preserve arrays in arguments, which are expected by certain FB APIs (see the ads API in particular, developers.facebook.com/docs/marketing-api/adgroup/v2.4)

  • :beta (Boolean) —

    use Facebook’s beta tier

  • :use_ssl (Boolean) —

    force SSL for this request, even if it’s tokenless. (All API requests with access tokens use SSL.)

Returns:

  • a Koala::HTTPService::Response object representing the returned Facebook data

Raises:

See Also:

  • GraphAPIMethods#graph_call


87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# File 'lib/koala/api.rb', line 87

def api(path, args = {}, verb = "get", options = {})
  # we make a copy of args so the modifications (added access_token & appsecret_proof)
  # do not affect the received argument
  args = args.dup

  # If a access token is explicitly provided, use that
  # This is explicitly needed in batch requests so GraphCollection
  # results preserve any specific access tokens provided
  args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token

  if options.delete(:appsecret_proof) && args["access_token"] && @app_secret
    args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"])
  end

  # Translate any arrays in the params into comma-separated strings
  args = sanitize_request_parameters(args) unless preserve_form_arguments?(options)

  # add a leading / if needed...
  path = "/#{path}" unless path =~ /^\//

  # make the request via the provided service
  result = Koala.make_request(path, args, verb, options)

  if result.status.to_i >= 500
    raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
  end

  result
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.)

Parameters:

  • path —

    the Graph API path to query (no leading / needed)

  • verb (defaults to: "get") —

    the type of HTTP request to make (get, post, delete, etc.)

Yields:

  • response when making a batch API call, you can pass in a block that parses the results, allowing for cleaner code. The block’s return value is returned in the batch results. See the code for GraphAPIMethods#get_picture for examples. (Not needed in regular calls; you’ll probably rarely use this.)

Returns:

  • the result from Facebook

Raises:



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

def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
  # enable appsecret_proof by default
  options = {:appsecret_proof => true}.merge(options) if @app_secret
  response = api(path, args, verb, options)

  error = GraphErrorChecker.new(response.status, response.body, response.headers).error_if_appropriate
  raise error if error

  # if we want a component other than the body (e.g. redirect header for images), provide that
  http_component = options[:http_component]
  desired_data = if options[:http_component]
    http_component == :response ? response : response.send(http_component)
  else
    # turn this into a GraphCollection if it's pageable
    API::GraphCollection.evaluate(response, self)
  end

  # now process as appropriate for the given call (get picture header, etc.)
  post_processing ? post_processing.call(desired_data) : desired_data
end