GraphRequest
A more recent version of this class is available. Check out the latest version.

A single request to be sent to the Facebook Platform through the Graph API. The Request class provides functionality relating to serializing and deserializing requests and responses, making calls in batches (with a single round-trip to the service) and making calls asynchronously.

The particular service endpoint that a request targets is determined by a graph path (see the setGraphPath.setGraphPath(String) method).

A Request can be executed either anonymously or representing an authenticated user. In the former case, no AccessToken needs to be specified, while in the latter, an AccessToken must be provided. If requests are executed in a batch, a Facebook application ID must be associated with the batch, either by setting the application ID in the AndroidManifest.xml or via FacebookSdk or by calling the setDefaultBatchApplicationId.setDefaultBatchApplicationId(String) method.

After completion of a request, the AccessToken, if not null and taken from AccessTokenManager, will be checked to determine if its Facebook access token needs to be extended; if so, a request to extend it will be issued in the background.

Extends:Object
Package:facebook
Constructors
GraphRequest()

Constructs a request without an access token, graph path, or any other parameters.

public GraphRequest()
GraphRequest(AccessToken, String)

Constructs a request with an access token to retrieve a particular graph path. An access token need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph requests can be expected to succeed in this case.

public GraphRequest(AccessToken accessToken, String graphPath)
ParameterDescription
accessTokenThe access token to use, or null
graphPathThe graph path to retrieve
GraphRequest(AccessToken, String, Bundle, HttpMethod)

Constructs a request with a specific AccessToken, graph path, parameters, and HTTP method. An access token need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph requests can be expected to succeed in this case.

Depending on the httpMethod parameter, the object at the graph path may be retrieved, created, or deleted.

public GraphRequest(AccessToken accessToken, String graphPath, Bundle parameters, HttpMethod httpMethod)
ParameterDescription
accessTokenThe access token to use, or null
graphPathThe graph path to retrieve, create, or delete
parametersAdditional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.
httpMethodThe HttpMethod to use for the request, or null for default (HttpMethod.GET)
GraphRequest(AccessToken, String, Bundle, HttpMethod, Callback)

Constructs a request with a specific access token, graph path, parameters, and HTTP method. An access token need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph\ requests can be expected to succeed in this case.

Depending on the httpMethod parameter, the object at the graph path may be retrieved, created, or deleted.

public GraphRequest(AccessToken accessToken, String graphPath, Bundle parameters, HttpMethod httpMethod, Callback callback)
ParameterDescription
accessTokenThe access token to use, or null
graphPathThe graph path to retrieve, create, or delete
parametersAdditional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.
httpMethodThe HttpMethod to use for the request, or null for default (HttpMethod.GET)
callbackA callback that will be called when the request is completed to handle success or error conditions
GraphRequest(AccessToken, String, Bundle, HttpMethod, Callback, String)

Constructs a request with a specific access token, graph path, parameters, and HTTP method. An access token need not be provided, in which case the request is sent without an access token and thus is not executed in the context of any particular user. Only certain graph requests can be expected to succeed in this case.

Depending on the httpMethod parameter, the object at the graph path may be retrieved, created, or deleted.

public GraphRequest(AccessToken accessToken, String graphPath, Bundle parameters, HttpMethod httpMethod, Callback callback, String version)
ParameterDescription
accessTokenThe access token to use, or null
graphPathThe graph path to retrieve, create, or delete
parametersAdditional parameters to pass along with the Graph API request; parameters must be Strings, Numbers, Bitmaps, Dates, or Byte arrays.
httpMethodThe HttpMethod to use for the request, or null for default (HttpMethod.GET)
callbackA callback that will be called when the request is completed to handle success or error conditions
versionThe version of the Graph API
Class Methods
newDeleteObjectRequest(AccessToken, String, Callback)

Creates a new Request configured to delete a resource through the Graph API.

public static GraphRequest newDeleteObjectRequest(AccessToken accessToken, String id, Callback callback)
ParameterDescription
accessTokenThe access token to use, or null
idThe id of the object to delete
callbackA callback that will be called when the request is completed to handle success or error conditions
Returns
A Request that is ready to execute
newMeRequest(AccessToken, GraphJSONObjectCallback)

Creates a new Request configured to retrieve a user's own profile.

public static GraphRequest newMeRequest(AccessToken accessToken, GraphJSONObjectCallback callback)
ParameterDescription
accessTokenThe access token to use, or null
callbackA callback that will be called when the request is completed to handle success or error conditions
Returns
A Request that is ready to execute
newPostRequest(AccessToken, String, JSONObject, Callback)

Creates a new Request configured to post a GraphObject to a particular graph path, to either create or update the object at that path.

public static GraphRequest newPostRequest(AccessToken accessToken, String graphPath, JSONObject graphObject, Callback callback)
ParameterDescription
accessTokenThe access token to use, or null
graphPathThe graph path to retrieve, create, or delete
graphObjectThe graph object to create or update
callbackA callback that will be called when the request is completed to handle success or error conditions
Returns
A Request that is ready to execute
newMyFriendsRequest(AccessToken, GraphJSONArrayCallback)

Creates a new Request configured to retrieve a user's friend list.

public static GraphRequest newMyFriendsRequest(AccessToken accessToken, GraphJSONArrayCallback callback)
ParameterDescription
accessTokenThe access token to use, or null
callbackA callback that will be called when the request is completed to handle success or error conditions
Returns
A Request that is ready to execute
newGraphPathRequest(AccessToken, String, Callback)

Creates a new Request configured to retrieve a particular graph path.

public static GraphRequest newGraphPathRequest(AccessToken accessToken, String graphPath, Callback callback)
ParameterDescription
accessTokenThe access token to use, or null
graphPathThe graph path to retrieve
callbackA callback that will be called when the request is completed to handle success or error conditions
Returns
A Request that is ready to execute
newPlacesSearchRequest(AccessToken, Location, int, int, String, GraphJSONArrayCallback)

Creates a new Request that is configured to perform a search for places near a specified location via the Graph API. At least one of location or searchText must be specified.

public static GraphRequest newPlacesSearchRequest(AccessToken accessToken, Location location, int radiusInMeters, int resultsLimit, String searchText, GraphJSONArrayCallback callback)
ParameterDescription
accessTokenThe access token to use, or null
locationThe location around which to search; only the latitude and longitude components of the location are meaningful
radiusInMetersThe radius around the location to search, specified in meters; this is ignored if no location is specified
resultsLimitThe maximum number of results to return
searchTextOptional text to search for as part of the name or type of an object
callbackA callback that will be called when the request is completed to handle success or error conditions
Returns
A Request that is ready to execute
newCustomAudienceThirdPartyIdRequest(AccessToken, Context, String, Callback)

Creates a new Request configured to retrieve an App User ID for the app's Facebook user. Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with, and then use the resultant Custom Audience to target ads.

The GraphObject in the response will include a "custom_audience_third_party_id" property, with the value being the ID retrieved. This ID is an encrypted encoding of the Facebook user's ID and the invoking Facebook app ID. Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences.

The ID retrieved represents the Facebook user identified in the following way: if the specified access token (or active access token if null) is valid, the ID will represent the user associated with the active access token; otherwise the ID will represent the user logged into the native Facebook app on the device. A null ID will be provided into the callback if a) there is no native Facebook app, b) no one is logged into it, or c) the app has previously called FacebookSdk.setLimitEventAndDataUsage(android.content.Context, boolean) ;} with true for this user. You must call this method from a background thread for it to work properly.

public static GraphRequest newCustomAudienceThirdPartyIdRequest(AccessToken accessToken, Context context, String applicationId, Callback callback)
ParameterDescription
accessTokenThe access token to issue the Request on, or null If there is no logged-in Facebook user, null is the expected choice.
contextThe Application context from which the app ID will be pulled, and from which the 'attribution ID' for the Facebook user is determined. If there has been no app ID set, an exception will be thrown.
applicationIdExplicitly specified Facebook App ID. If null, the application ID from the access token will be used, if any; if not, the application ID from metadata will be used.
callbackA callback that will be called when the request is completed to handle success or error conditions. The GraphObject in the Response will contain a "custom_audience_third_party_id" property that represents the user as described above.
Returns
A Request that is ready to execute
newCustomAudienceThirdPartyIdRequest(AccessToken, Context, Callback)

Creates a new Request configured to retrieve an App User ID for the app's Facebook user. Callers will send this ID back to their own servers, collect up a set to create a Facebook Custom Audience with, and then use the resultant Custom Audience to target ads.

The GraphObject in the response will include a "custom_audience_third_party_id" property, with the value being the ID retrieved. This ID is an encrypted encoding of the Facebook user's ID and the invoking Facebook app ID. Multiple calls with the same user will return different IDs, thus these IDs cannot be used to correlate behavior across devices or applications, and are only meaningful when sent back to Facebook for creating Custom Audiences.

The ID retrieved represents the Facebook user identified in the following way: if the specified access token (or active access token if null) is valid, the ID will represent the user associated with the active access token; otherwise the ID will represent the user logged into the native Facebook app on the device. A null ID will be provided into the callback if a) there is no native Facebook app, b) no one is logged into it, or c) the app has previously called FacebookSdk.setLimitEventAndDataUsage(android.content.Context, boolean) with true for this user. You must call this method from a background thread for it to work properly.

public static GraphRequest newCustomAudienceThirdPartyIdRequest(AccessToken accessToken, Context context, Callback callback)
ParameterDescription
accessTokenThe access token to issue the Request on, or null If there is no logged-in Facebook user, null is the expected choice.
contextThe Application context from which the app ID will be pulled, and from which the 'attribution ID' for the Facebook user is determined. If there has been no app ID set, an exception will be thrown.
callbackA callback that will be called when the request is completed to handle success or error conditions. The GraphObject in the Response will contain a "custom_audience_third_party_id" property that represents the user as described above.
Returns
A Request that is ready to execute
getDefaultBatchApplicationId()

Gets the default Facebook application ID that will be used to submit batched requests. Batched requests require an application ID, so either at least one request in a batch must provide an access token or the application ID must be specified explicitly.

public static final String getDefaultBatchApplicationId()
Returns
The Facebook application ID to use for batched requests if none can be determined
setDefaultBatchApplicationId(String)

Sets the default application ID that will be used to submit batched requests if none of those requests specifies an access token. Batched requests require an application ID, so either at least one request in a batch must specify an access token or the application ID must be specified explicitly.

public static final void setDefaultBatchApplicationId(String applicationId)
ParameterDescription
applicationIdThe Facebook application ID to use for batched requests if none can be determined
toHttpConnection(GraphRequest)

Serializes one or more requests but does not execute them. The resulting HttpURLConnection can be executed explicitly by the caller.

public static HttpURLConnection toHttpConnection(GraphRequest requests)
ParameterDescription
requestsOne or more Requests to serialize
Returns
An HttpURLConnection which is ready to execute
toHttpConnection(Collection)

Serializes one or more requests but does not execute them. The resulting HttpURLConnection can be executed explicitly by the caller.

public static HttpURLConnection toHttpConnection(Collection requests)
ParameterDescription
requestsOne or more Requests to serialize
Returns
An HttpURLConnection which is ready to execute
toHttpConnection(GraphRequestBatch)

Serializes one or more requests but does not execute them. The resulting HttpURLConnection can be executed explicitly by the caller.

public static HttpURLConnection toHttpConnection(GraphRequestBatch requests)
ParameterDescription
requestsA RequestBatch to serialize
Returns
An HttpURLConnection which is ready to execute
executeAndWait(GraphRequest)

Executes a single request on the current thread and blocks while waiting for the response.

This should only be used if you have transitioned off the UI thread.

public static GraphResponse executeAndWait(GraphRequest request)
ParameterDescription
requestThe Request to execute
Returns
The Response object representing the results of the request
executeBatchAndWait(GraphRequest)

Executes requests on the current thread as a single batch and blocks while waiting for the response.

This should only be used if you have transitioned off the UI thread.

public static List executeBatchAndWait(GraphRequest requests)
ParameterDescription
requestsThe Requests to execute
Returns
A list of Response objects representing the results of the requests; responses are returned in the same order as the requests were specified.
executeBatchAndWait(Collection)

Executes requests as a single batch on the current thread and blocks while waiting for the responses.

This should only be used if you have transitioned off the UI thread.

public static List executeBatchAndWait(Collection requests)
ParameterDescription
requestsThe Requests to execute
Returns
A list of Response objects representing the results of the requests; responses are returned in the same order as the requests were specified.
executeBatchAndWait(GraphRequestBatch)

Executes requests on the current thread as a single batch and blocks while waiting for the responses.

This should only be used if you have transitioned off the UI thread.

public static List executeBatchAndWait(GraphRequestBatch requests)
ParameterDescription
requestsThe batch of Requests to execute
Returns
A list of Response objects representing the results of the requests; responses are returned in the same order as the requests were specified.
executeBatchAsync(GraphRequest)

Executes requests as a single batch asynchronously. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback.setCallback(Callback) method).

This should only be called from the UI thread.

public static GraphRequestAsyncTask executeBatchAsync(GraphRequest requests)
ParameterDescription
requestsThe Requests to execute
Returns
A RequestAsyncTask that is executing the request
executeBatchAsync(Collection)

Executes requests as a single batch asynchronously. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback.setCallback(Callback) method).

This should only be called from the UI thread.

public static GraphRequestAsyncTask executeBatchAsync(Collection requests)
ParameterDescription
requestsThe Requests to execute
Returns
A RequestAsyncTask that is executing the request
executeBatchAsync(GraphRequestBatch)

Executes requests as a single batch asynchronously. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback.setCallback(Callback) method).

This should only be called from the UI thread.

public static GraphRequestAsyncTask executeBatchAsync(GraphRequestBatch requests)
ParameterDescription
requestsThe RequestBatch to execute
Returns
A RequestAsyncTask that is executing the request
executeConnectionAndWait(HttpURLConnection, Collection)

Executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses.

This should only be called if you have transitioned off the UI thread.

public static List executeConnectionAndWait(HttpURLConnection connection, Collection requests)
ParameterDescription
connectionThe HttpURLConnection that the requests were serialized into
requestsThe requests represented by the HttpURLConnection
Returns
A list of Responses corresponding to the requests
executeConnectionAndWait(HttpURLConnection, GraphRequestBatch)

Executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses.

This should only be called if you have transitioned off the UI thread.

public static List executeConnectionAndWait(HttpURLConnection connection, GraphRequestBatch requests)
ParameterDescription
connectionThe HttpURLConnection that the requests were serialized into
requestsThe RequestBatch represented by the HttpURLConnection
Returns
A list of Responses corresponding to the requests
executeConnectionAsync(HttpURLConnection, GraphRequestBatch)

Asynchronously executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback.setCallback(Callback) method).

This should only be called from the UI thread.

public static GraphRequestAsyncTask executeConnectionAsync(HttpURLConnection connection, GraphRequestBatch requests)
ParameterDescription
connectionThe HttpURLConnection that the requests were serialized into
requestsThe requests represented by the HttpURLConnection
Returns
A RequestAsyncTask that is executing the request
executeConnectionAsync(Handler, HttpURLConnection, GraphRequestBatch)

Asynchronously executes requests that have already been serialized into an HttpURLConnection. No validation is done that the contents of the connection actually reflect the serialized requests, so it is the caller's responsibility to ensure that it will correctly generate the desired responses. This function will return immediately, and the requests will be processed on a separate thread. In order to process results of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback.setCallback(Callback) method)

This should only be called from the UI thread.

public static GraphRequestAsyncTask executeConnectionAsync(Handler callbackHandler, HttpURLConnection connection, GraphRequestBatch requests)
ParameterDescription
callbackHandlerA Handler that will be used to post calls to the callback for each request; if null, a Handler will be instantiated on the calling thread
connectionThe HttpURLConnection that the requests were serialized into
requestsThe requests represented by the HttpURLConnection
Returns
A RequestAsyncTask that is executing the request
Instance Methods
getGraphObject()

Returns the GraphObject, if any, associated with this request.

public final JSONObject getGraphObject()
Returns
The GraphObject associated with this request, or null if there is none
setGraphObject(JSONObject)

Sets the GraphObject associated with this request. This is meaningful only for POST requests.

public final void setGraphObject(JSONObject graphObject)
ParameterDescription
graphObjectThe GraphObject to upload along with this request
getGraphPath()

Returns the graph path of this request, if any.

public final String getGraphPath()
Returns
The graph path of this request, or null if there is none
setGraphPath(String)

Sets the graph path of this request.

public final void setGraphPath(String graphPath)
ParameterDescription
graphPathThe graph path for this request
getHttpMethod()

Returns the HttpMethod to use for this request.

public final HttpMethod getHttpMethod()
Returns
The HttpMethod
setHttpMethod(HttpMethod)

Sets the HttpMethod to use for this request.

public final void setHttpMethod(HttpMethod httpMethod)
ParameterDescription
httpMethodThe HttpMethod, or null for the default (HttpMethod.GET).
getVersion()

Returns the version of the API that this request will use. By default this is the current API at the time the SDK is released.

public final String getVersion()
Returns
The version that this request will use
setVersion(String)

Set the version to use for this request. By default the version will be the current API at the time the SDK is released. Only use this if you need to explicitly override.

public final void setVersion(String version)
ParameterDescription
versionThe version to use. Should look like "v2.0"
setSkipClientToken(boolean)

This is an internal function that is not meant to be used by developers.

public final void setSkipClientToken(boolean skipClientToken)
ParameterDescription
skipClientToken
getParameters()

Returns the parameters for this request.

public final Bundle getParameters()
Returns
The parameters
setParameters(Bundle)

Sets the parameters for this request.

public final void setParameters(Bundle parameters)
ParameterDescription
parametersThe parameters
getAccessToken()

Returns the access token associated with this request.

public final AccessToken getAccessToken()
Returns
The access token associated with this request, or null if none has been specified
setAccessToken(AccessToken)

Sets the access token to use for this request.

public final void setAccessToken(AccessToken accessToken)
ParameterDescription
accessTokenThe access token to use for this request
getBatchEntryName()

Returns the name of this requests entry in a batched request.

public final String getBatchEntryName()
Returns
The name of this requests batch entry, or null if none has been specified
setBatchEntryName(String)

Sets the name of this request's entry in a batched request. This value is only used if this request is submitted as part of a batched request. It can be used to specified dependencies between requests. See Batch Requests in the Graph API documentation for more details.

public final void setBatchEntryName(String batchEntryName)
ParameterDescription
batchEntryNameThe name of this requests entry in a batched request, which must be unique within a particular batch of requests
getBatchEntryDependsOn()

Returns the name of the request that this request entry explicitly depends on in a batched request.

public final String getBatchEntryDependsOn()
Returns
The name of this requests dependency, or null if none has been specified
setBatchEntryDependsOn(String)

Sets the name of the request entry that this request explicitly depends on in a batched request. This value is only used if this request is submitted as part of a batched request. It can be used to specified dependencies between requests. See Batch Requests in the Graph API documentation for more details.

public final void setBatchEntryDependsOn(String batchEntryDependsOn)
ParameterDescription
batchEntryDependsOnThe name of the request entry that this entry depends on in a batched request
getBatchEntryOmitResultOnSuccess()

Returns whether or not this batch entry will return a response if it is successful. Only applies if another request entry in the batch specifies this entry as a dependency.

public final boolean getBatchEntryOmitResultOnSuccess()
Returns
The name of this requests dependency, or null if none has been specified
setBatchEntryOmitResultOnSuccess(boolean)

Sets whether or not this batch entry will return a response if it is successful. Only applies if another request entry in the batch specifies this entry as a dependency. See Batch Requests in the Graph API documentation for more details.

public final void setBatchEntryOmitResultOnSuccess(boolean batchEntryOmitResultOnSuccess)
ParameterDescription
batchEntryOmitResultOnSuccessThe name of the request entry that this entry depends on in a batched request
getCallback()

Returns the callback which will be called when the request finishes.

public final Callback getCallback()
Returns
The callback
setCallback(Callback)

Sets the callback which will be called when the request finishes.

public final void setCallback(Callback callback)
ParameterDescription
callbackThe callback
setTag(Object)

Sets the tag on the request; this is an application-defined object that can be used to distinguish between different requests. Its value has no effect on the execution of the request.

public final void setTag(Object tag)
ParameterDescription
tagAn object to serve as a tag, or null
getTag()

Gets the tag on the request; this is an application-defined object that can be used to distinguish between different requests. Its value has no effect on the execution of the request.

public final Object getTag()
Returns
An object that serves as a tag, or null
executeAndWait()

Executes this request on the current thread and blocks while waiting for the response.

This should only be called if you have transitioned off the UI thread.

public final GraphResponse executeAndWait()
Returns
The Response object representing the results of the request
executeAsync()

Executes the request asynchronously. This function will return immediately, and the request will be processed on a separate thread. In order to process result of a request, or determine whether a request succeeded or failed, a callback must be specified (see the setCallback.setCallback(Callback) method).

This should only be called from the UI thread.

public final GraphRequestAsyncTask executeAsync()
Returns
A RequestAsyncTask that is executing the request
Constants
MAXIMUM_BATCH_SIZE
The maximum number of requests that can be submitted in a single batch. This limit is enforced on the service side by the Facebook platform, not by the Request class.
public static final int MAXIMUM_BATCH_SIZE
TAG
public static final String TAG