class Koala::Facebook::API
Attributes
Public Class Methods
Creates a new API
client. @param [String] access_token
access token @param [String] 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 https://developers.facebook.com/docs/graph-api/securing-requests/)
@note If no access token is provided, you can only access some public information. @return [Koala::Facebook::API] the API
client
# File lib/koala/api.rb 18 def initialize(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret) 19 @access_token = access_token 20 @app_secret = app_secret 21 end
Public Instance Methods
Makes a request to the appropriate Facebook
API
. @note You'll rarely need to call this method directly.
@see GraphAPIMethods#graph_call
@param path the server path for this request (leading / is prepended if not present) @param args arguments to be sent to Facebook
@param verb the HTTP method to use @param options request-related options for Koala
and Faraday.
See https://github.com/arsduo/koala/wiki/HTTP-Services for additional options.
@option options [Symbol] :http_component which part of the response (headers, body, or status) to return @option options [Symbol] :format which request format to use. Currently, :json is supported @option options [Symbol] :preserve_form_arguments preserve arrays in arguments, which are
expected by certain FB APIs (see the ads API in particular, https://developers.facebook.com/docs/marketing-api/adgroup/v2.4)
@option options [Boolean] :beta use Facebook's beta tier @option options [Boolean] :use_ssl force SSL for this request, even if it's tokenless.
(All API requests with access tokens use SSL.)
@raise [Koala::Facebook::ServerError] if Facebook
returns an error (response status >= 500)
@return a Koala::HTTPService::Response
object representing the returned Facebook
data
# File lib/koala/api.rb 87 def api(path, args = {}, verb = "get", options = {}) 88 # we make a copy of args so the modifications (added access_token & appsecret_proof) 89 # do not affect the received argument 90 args = args.dup 91 92 # If a access token is explicitly provided, use that 93 # This is explicitly needed in batch requests so GraphCollection 94 # results preserve any specific access tokens provided 95 args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token 96 97 if options.delete(:appsecret_proof) && args["access_token"] && @app_secret 98 args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"]) 99 end 100 101 # Translate any arrays in the params into comma-separated strings 102 args = sanitize_request_parameters(args) unless preserve_form_arguments?(options) 103 104 # add a leading / if needed... 105 path = "/#{path}" unless path =~ /^\// 106 107 # make the request via the provided service 108 result = Koala.make_request(path, args, verb, options) 109 110 if result.status.to_i >= 500 111 raise Koala::Facebook::ServerError.new(result.status.to_i, result.body) 112 end 113 114 result 115 end
Make a call directly to the Graph API
. (See any of the other methods for example invocations.)
@param path the Graph API
path to query (no leading / needed) @param args (see get_object
) @param verb the type of HTTP request to make (get, post, delete, etc.) @options (see get_object
)
@yield 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 {#get_picture} for examples. (Not needed in regular calls; you'll probably rarely use this.)
@raise [Koala::Facebook::APIError] if Facebook
returns an error
@return the result from Facebook
# File lib/koala/api.rb 44 def graph_call(path, args = {}, verb = "get", options = {}, &post_processing) 45 # enable appsecret_proof by default 46 options = {:appsecret_proof => true}.merge(options) if @app_secret 47 response = api(path, args, verb, options) 48 49 error = GraphErrorChecker.new(response.status, response.body, response.headers).error_if_appropriate 50 raise error if error 51 52 # if we want a component other than the body (e.g. redirect header for images), provide that 53 http_component = options[:http_component] 54 desired_data = if options[:http_component] 55 http_component == :response ? response : response.send(http_component) 56 else 57 # turn this into a GraphCollection if it's pageable 58 API::GraphCollection.evaluate(response, self) 59 end 60 61 # now process as appropriate for the given call (get picture header, etc.) 62 post_processing ? post_processing.call(desired_data) : desired_data 63 end
Private Instance Methods
# File lib/koala/api.rb 141 def check_response(http_status, body, headers) 142 end
# File lib/koala/api.rb 137 def preserve_form_arguments?(options) 138 options[:format] == :json || options[:preserve_form_arguments] || Koala.config.preserve_form_arguments 139 end
Sanitizes Ruby objects into Facebook-compatible string values.
@param parameters a hash of parameters.
Returns a hash in which values that are arrays of non-enumerable values
(Strings, Symbols, Numbers, etc.) are turned into comma-separated strings.
# File lib/koala/api.rb 125 def sanitize_request_parameters(parameters) 126 parameters.reduce({}) do |result, (key, value)| 127 # if the parameter is an array that contains non-enumerable values, 128 # turn it into a comma-separated list 129 # in Ruby 1.8.7, strings are enumerable, but we don't care 130 if value.is_a?(Array) && value.none? {|entry| entry.is_a?(Enumerable) && !entry.is_a?(String)} 131 value = value.join(",") 132 end 133 result.merge(key => value) 134 end 135 end