Batch.run
From Facebook Developer Wiki
Contents |
Description
Executes a list of individual API calls in a single batch.
The batch API allows you to combine multiple individual operations into a single request. This could reduce the traffic load to Facebook server and latency substantially.
Note that there is limit of 20 individual operations that can be performed in a single batch execution.
Parameters
| Required | Name | Type | Description | |
| required | api_key | string | The application key associated with the calling application. | |
|---|---|---|---|---|
| call_id | float | The request's sequence number. Each successive call for any session must use a sequence number greater than the last. We suggest using the current time in milliseconds, such as PHP's microtime(true) function. | ||
| sig | string | An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application. | ||
| v | string | This must be set to 1.0 to use this version of the API. | ||
| method_feed | string | A JSON encoded array of strings. Each element in the array should contain the full parameters for a method, including method name, sig, etc. Currently, there is a maximum limit of 15 elements in the array. | ||
| optional | serial_only | bool | An optional parameter to indicate whether the methods in the method_feed must be executed in order. The default value is false. | |
| format | string | The desired response format, which can be either XML or JSON. (Default value is XML.) | ||
| callback | string | Name of a function to call. This is primarily to enable cross-domain javascript requests using the <script> tag, sometimes known as "JSONP". This works with both XML and JSON. |
Response
An array of individual results as strings.
Example Return XML
<?xml version="1.0" encoding="UTF-8"?>
<batch_run_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true">
<batch_run_response_elt><?xml version="1.0" encoding="UTF-8"?>
<friends_get_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd" list="true">
<uid>1160</uid>
</friends_get_response>
</batch_run_response_elt>
</batch_run_response>
FQL Equivalent
FQL queries take the form: SELECT <fields> FROM <table> WHERE <conditions>
There is no equivalent FQL query.
Error Codes
| Code | Description | |
| 1 | An unknown error occurred. Please resubmit the request. | |
|---|---|---|
| 2 | The service is not available at this time. | |
| 4 | The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed. | |
| 5 | The request came from a remote address not allowed by this application. | |
| 100 | One of the parameters specified was missing or invalid. | |
| 101 | The API key submitted is not associated with any known application. | |
| 102 | The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key. | |
| 103 | The submitted call_id was not greater than the previous call_id for this session. | |
| 104 | Incorrect signature. | |
| 950 | Each batch API cannot contain more than 20 items. |
Notes
- This function does not require a
session_key, unless it is being called by a desktop application.
- The
method_feedparameter is a JSON-encoded array of strings. Each string contains all the parameters for each individual API call, such assession_key,api_keyandsig.
For example, suppose you want to send a batch API request to execute friends.get and notifications.get. First, you would construct all the parameters forfriends.getandnotifications.getand place them into an array of strings, like this:["method=friends.get&session_key=abcd&api_key=abcd&format=JSON&call_id=717&v=1.0&sig=0123", "method=notifications.get&session_key=abcd&api_key=abcd&format=JSON&call_id=717&v=1.0&sig=0123"]
Now you can use your favorite JSON encoding function to encode the array into a JSON string, and use it as the value of themethod_feedparameter, like this:method_feed=%5B%22method%3Dfriends.get%26session_key%3abcd ... 22method%3Dnotifications.get%26session_key%abcd ..."
