Using Batching API

From Facebook Developer Wiki

(Redirected from Using batching API)
Jump to: navigation, search

Contents

[edit] Using the Facebook Batch API

The Facebook batch API allows you to combine multiple separate API calls into a single request. This could reduce the traffic volume to Facebook server as well as reduce latency substantially. The API itself is described in batch.run.

Directly calling the batch API can be inconvenient because it requires the caller to construct an array of JSON-encoded parameters from the individual operations and then break down the array of results later.

Fortunately, you can take advantage of the batch API easily because we just updated our PHP5 client libraries. This article describes how to enable batching in our updated PHP5 client library. (For the new Javascript client library methods look at section: Batching Using the JavaScript Client Library).

Note: There is maximum limit of 20 individual operations that can be performed in a single batch execution.

[edit] Batching Using the PHP5 Client Library

To support batch operations, we added two methods and a property to FacebookRestClient class.

public function begin_batch(); public function end_batch(); public $batch_mode;


In addition, we changed the signature of each individual API function to return a reference instead of an object.

Here is a code example that calls the Facebook API but doesn't use batching:

$api_client = $facebook->api_client; $friends = $api_client->friends_get(); $notifications = $api_client->notifications_get();


When the above code is converted to use batching, it looks like this:

$api_client = $facebook->api_client; $api_client->begin_batch(); $friends = & $api_client->friends_get(); $notifications = & $api_client->notifications_get(); $api_client->end_batch();


By default, the batch mode is FacebookRestClient::BATCH_MODE_SERVER_PARALLEL. With this mode, the individual operations may be executed in parallel to obtain the best performance. However, if your individual operations have to be executed in order, you should set $batch_mode to FacebookRestClient::BATCH_MODE_SERIAL_ONLY.

It should be noted that when operations are performed in batch mode, the results of individual operations (such as $friends in the example above) are not populated until end_batch() function is returned.

Note: We currently only added batching support for PHP5 client library. That library requires PHP5.2 or greater for json_encode and json_decode() functions. We will add batching support to PHP4 client library in the future.

[edit] Batching Using the JavaScript Client Library

With the new JavaScript Client Library, you can perform batch operations using the FB.BatchSequencer object. After creating a BatchSequencer object, it can be passed as the last argument of each individual API call. When you need to execute all batched operations, you can call the execute() method on the FB.BatchSequencer object.

Here is a JavaScript code sample:

/// Example of calling APIs in batched mode //First create a sequencer for batch execution var sequencer = new FB.BatchSequencer(); // By default, individual APIs may be executed in parallel on the server side. // To force sequential executions on the server, uncomment the following code // sequencer.isParallel = false; //Calling friends_get API, passing the sequencer as last argument var pendingFriendsResult = api.friends_get(sequencer); //Call notifications_get API, passing the sequencer as last argument var pendingNotificationsResult = api.notifications_get(sequencer); //Actually execute the APIs that are queued inside the sequencer, passing a callback function that is called //when the batch operation is completed. When the callback function is called, the 'result' or 'exception' properties of //pendingFriendsResult and pendingNotificationsResult are updated. sequencer.execute(function() { Debug.dump(pendingFriendsResult.result, 'friendsResult from batch execution'); Debug.dump(pendingNotificationsResult.result, 'notificationsResult from batch execution'); });


[edit] Batching Using the Open-Source Java Client Library

As of version 1.7.1, the Open-source Java API has built-in support for the Batch API. In order to use it, all you have to do is call 'client.beginBatch()' to initiate batch mode, and then make whatever API calls you want to include as part of your batch. Once you have specified all the desired API calls, call 'client.executeBatch()' to batch your API calls to the server. The result is returned as a list, containing the responses to each API call, in the order in which you specified them.

Here is a Java code example:

//create a client instance IFacebookRestClient<Document> client = new FacebookRestClient(YOUR_API_KEY, YOUR_SECRET_KEY, SESSION_ID); //set the client to run in batch mode client.beginBatch(); //these commands will be batched client.users_getLoggedInUser(); //while the client is in batch mode, all API calls will return null client.friends_get(); //execute the batch (which also terminates batch mode until beginBatch is called again) List<? extends Object> batchResponse = client.executeBatch(false); //the list contains the results of the queries, in the same order they were defined Long userId = (Long) batchResponse.get(0); Document friends = (Document)batchResponse.get(1); NodeList nodes = friends.getElementsByTagName("uid"); //print the results System.out.println("USER: " + userId); for (int index = 0; index < nodes.getLength(); index++) { System.out.println("FRIEND: " + nodes.item(index).getFirstChild().getTextContent()); }
Retrieved from "http://wiki.developers.facebook.com/index.php/Using_Batching_API"
reference