Opensocial.DataRequest (v0.9)
NeedsBetterExamples
opensocial.DataRequest
Used to request social information from the container. This includes data for friends, profiles, app data, and activities. All apps that require access to people information should send a DataRequest. Here's an example of creating, initializing, sending, and handling the results of a data request:
function requestMe() {
var req = opensocial.newDataRequest();
var fetchPersonRequest =
req.newFetchPersonRequest( opensocial.IdSpec.PersonId.VIEWER);
req.add(fetchPersonRequest, "viewer");
req.send(handleRequestMe);
};
function handleRequestMe(data) {
var viewer = data.get("viewer");
if (viewer.hadError()) {
/* Handle error using viewer.getError()... */
return;
}
/* No error. Do something with viewer.getData()... */
}
See also: opensocial.newDataRequest()
Methods
opensocial.DataRequest.add
;add(request, opt_key)
Parameters
NameTypeDescription |
request |
Object |
Specifies which data to fetch or update |
opt_key |
String |
A key to map the generated response data to |
Description
Adds an item to fetch (get) or update (set) data from the server. A single DataRequest object can have multiple items. As a rule, each item is executed in the order it was added, starting with the item that was added first. However, items that can't collide might be executed in parallel.
opensocial.DataRequest.newCreateAlbumRequest
;Object newCreateAlbumRequest(An, album)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups to create an album for. |
album |
opensocial.Album |
The album to create. |
Returns
TypeDescription |
Object |
A request object |
Description
Creates a new album and returns the ID of the album created. Containers implement restrictions - like allowing a viewer to create albums for only him/herself.
opensocial.DataRequest.newCreateMediaItemRequest
;Object newCreateMediaItemRequest(An, albumId, mediaItem)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups own the album. |
albumId |
string |
The album to add the media item to. |
mediaItem |
opensocial.MediaItem |
The MediaItem to add to the album. |
Returns
TypeDescription |
Object |
A request object |
Description
Creates a new media item in the album and returns the ID of the album created. Containers implement restrictions.
opensocial.DataRequest.newDeleteAlbumRequest
;Object newDeleteAlbumRequest(An, albumId)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups own the album. |
albumId |
string |
The album to delete. |
Returns
TypeDescription |
Object |
A request object |
Description
Deletes the album specified. Containers implement restriction.
opensocial.DataRequest.newFetchActivitiesRequest
;Object newFetchActivitiesRequest(idSpec, opt_params)
Parameters
NameTypeDescription |
idSpec |
opensocial.IdSpec |
An IdSpec used to specify which people to fetch. See also IdSpec. |
|
opt_params |
Map.<opensocial.DataRequest.ActivityRequestFields |
Object> |
Additional parameters to pass to the request; not currently used |
Returns
TypeDescription |
Object |
A request object |
Description
Creates an item to request an activity stream from the server. When processed, returns a Collection<Activity>.
opensocial.DataRequest.newFetchAlbumsRequest
;Object newFetchAlbumsRequest(An, opt_params)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups to fetch albums from. |
|
opt_params |
Map.<string |
string> |
opt_params can specify the following: opensocial.Album.Field.ID - an array of album Ids to fetch (fetch all albums if empty, subject to pagination) opensocial.Album.Field.MEDIA_TYPE - an array of MediaItem.TYPE values to specify the kind of Albums to fetch. opensocial.DataRequest.AlbumRequestFields.FIRST - The first item to fetch. opensocial.DataRequest.AlbumRequestFields.MAX - The maximum number of items to fetch. |
Returns
TypeDescription |
Object |
A request object |
Description
The newFetchAlbumsRequest() creates an object for DataRequest to request albums.
opensocial.DataRequest.newFetchMediaItemsRequest
;Object newFetchMediaItemsRequest(An, albumId, opt_params)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups to fetch media items from. |
|
albumId |
string |
The id of the album to fetch MediaItems from. |
|
opt_params |
Map.<string |
string> |
opt_params can specify the following: opensocial.MediaItem.Field.ID - an array of media item ids to selectively fetch (fetch all items if empty, subject to pagination) opensocial.MediaItem.Field.MEDIA_TYPE - an array of MediaItem.TYPE values to specify the types of MediaItems to fetch opensocial.DataRequest.MediaItemRequestFields.FIRST - The first item to fetch. opensocial.DataRequest.MediaItemRequestFields.MAX - The maximum number of items to fetch. |
Returns
TypeDescription |
Object |
A request object |
Description
The newFetchMediaItemsRequest() creates an object for DataRequest to request mediaItems.
opensocial.DataRequest.newFetchPeopleRequest
;Object newFetchPeopleRequest(idSpec, opt_params)
Parameters
NameTypeDescription |
Returns
TypeDescription |
Object |
A request object |
Description
Creates an item to request friends from the server. When processed, returns a Collection < Person > object.
opensocial.DataRequest.newFetchPersonAppDataRequest
;Object newFetchPersonAppDataRequest(idSpec, keys, opt_params)
Parameters
NameTypeDescription |
idSpec |
opensocial.IdSpec |
An IdSpec used to specify which people to fetch. See also IdSpec. |
|
keys |
Array.<String> |
String |
The keys you want data for; this can be an array of key names, a single key name, or "*" to mean "all keys" |
opt_params |
Map.<opensocial.DataRequest.DataRequestFields |
Object> |
Additional params to pass to the request |
Returns
TypeDescription |
Object |
A request object |
Description
Creates an item to request app data for the given people. When processed, returns a Map< PersonId, Map<String, Object>> object. All of the data values returned will be valid json.
opensocial.DataRequest.newFetchPersonRequest
;Object newFetchPersonRequest(id, opt_params)
Parameters
NameTypeDescription |
id |
String |
The ID of the person to fetch; can be the standard person ID of VIEWER or OWNER |
|
opt_params |
Map.<opensocial.DataRequest.PeopleRequestFields |
Object> |
Additional parameters to pass to the request; this request supports PROFILE_DETAILS |
Returns
TypeDescription |
Object |
A request object |
Description
Creates an item to request a profile for the specified person ID. When processed, returns a Person object.
opensocial.DataRequest.newRemovePersonAppDataRequest
;Object newRemovePersonAppDataRequest(keys)
Parameters
NameTypeDescription |
keys |
Array.<String> |
String |
The keys you want to delete from the datastore; this can be an array of key names, a single key name, or "*" to mean "all keys" |
Returns
TypeDescription |
Object |
A request object |
Description
Deletes the given keys from the datastore for the current VIEWER. When processed, does not return any data.
opensocial.DataRequest.newUpdateAlbumRequest
;Object newUpdateAlbumRequest(An, albumId, fields)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups to own the album. |
|
albumId |
string |
The album to update. |
|
fields |
Map<opensocial.Album.Field |
object> |
The Album Fields to update.The following fields cannot be set: MEDIA_ITEM_COUNT, OWNER_ID, ID. Containers implement restrictions. |
Returns
TypeDescription |
Object |
A request object |
Description
Updates the fields specified in the params.The following fields cannot be set: MEDIA_ITEM_COUNT, OWNER_ID, ID. Containers implement restrictions.
opensocial.DataRequest.newUpdateMediaItemRequest
;Object newUpdateMediaItemRequest(An, albumId, mediaItemId, fields)
Parameters
NameTypeDescription |
An |
opensocial.IdSpec |
IdSpec used to specify which people/groups own the album/media item. |
|
albumId |
string |
The album containing the media item to update. |
|
mediaItemId |
string |
The media item to update. |
|
fields |
Map<opensocial.MediaItem.Field |
object> |
The Album Fields to update.The following fields cannot be set: ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS. Containers implement restrictions. |
Returns
TypeDescription |
Object |
A request object |
Description
Updates the fields specified in the params.The following fields cannot be set: ID, CREATED, ALBUM_ID, FILE_SIZE, NUM_COMMENTS. Containers implement restrictions.
opensocial.DataRequest.newUpdatePersonAppDataRequest
;Object newUpdatePersonAppDataRequest(key, value)
Parameters
NameTypeDescription |
key |
String |
The name of the key. This may only contain alphanumeric (A-Za-z0-9) characters, underscore(_), dot(.) or dash |
value |
Object |
The value, must be valid json |
. Returns
TypeDescription |
Object |
A request object |
Description
Creates an item to request an update of an app field for the current VIEWER. When processed, does not return any data. App Data is stored as a series of key value pairs of strings, scoped per person, per application.
opensocial.DataRequest.send
;send(opt_callback)
Parameters
NameTypeDescription |
opt_callback |
Function |
The function to call with the data response generated by the server. The callback function will not be called until after the existing callstack has completed execution. |
Description
Sends a data request to the server in order to get a data response. Although the server may optimize these requests, they will always be executed as though they were serial.
opensocial.DataRequest.ActivityRequestFields
The values needed to handle activity paging.
opensocial.DataRequest.ActivityRequestFields.FIRST
<static> Member of: opensocial.DataRequest.ActivityRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number.
opensocial.DataRequest.ActivityRequestFields.MAX
<static> Member of: opensocial.DataRequest.ActivityRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20.
opensocial.DataRequest.AlbumRequestFields
The values needed to handle activity paging.
opensocial.DataRequest.AlbumRequestFields.FIRST
<static> Member of: opensocial.DataRequest.AlbumRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number.
opensocial.DataRequest.AlbumRequestFields.MAX
<static> Member of: opensocial.DataRequest.AlbumRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20.
opensocial.DataRequest.DataRequestFields
opensocial.DataRequest.DataRequestFields.ESCAPE_TYPE
<static> Member of: opensocial.DataRequest.DataRequestFields.ESCAPE_TYPE How to escape person data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType. This field may be used interchangeably with the string 'escapeType'. Use of this function is deprecated in favor of us using the ESCAPE_TYPE request field.
opensocial.DataRequest.FilterType
The filters available for limiting person requests.
opensocial.DataRequest.FilterType.ALL
Retrieves all friends. This field may be used interchangeably with the string 'all'.
opensocial.DataRequest.FilterType.HAS_APP
<static> Member of: opensocial.DataRequest.FilterType.HAS_APP Retrieves all friends that use this application. Note: Containers may define "use" in any manner they deem appropriate for their functionality, and it is not expected that this field will have the exact same semantics across containers. This field may be used interchangeably with the string 'hasApp'.
opensocial.DataRequest.FilterType.IS_FRIENDS_WITH
<static> Member of: opensocial.DataRequest.FilterType.IS_FRIENDS_WITH Will filter the people requested by checking if they are friends with the given idSpec. Expects a filterOptions parameter to be passed with the following fields defined: - idSpec The idSpec that each person must be friends with. This field may be used interchangeably with the string 'isFriendsWith'.
opensocial.DataRequest.FilterType.TOP_FRIENDS
<static> Member of: opensocial.DataRequest.FilterType.TOP_FRIENDS Retrieves only the user's top friends as defined by the container. Container support for this filter type is OPTIONAL. This field may be used interchangeably with the string 'topFriends'.
opensocial.DataRequest.MediaItemRequestFields
The values needed to handle activity paging.
opensocial.DataRequest.MediaItemRequestFields.FIRST
<static> Member of: opensocial.DataRequest.MediaItemRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number.
opensocial.DataRequest.MediaItemRequestFields.MAX
<static> Member of: opensocial.DataRequest.MediaItemRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20.
opensocial.DataRequest.PeopleRequestFields
opensocial.DataRequest.PeopleRequestFields.APP_DATA
<static> Member of: opensocial.DataRequest.PeopleRequestFields.APP_DATA An array of strings, specifying the app data keys to fetch for each of the Person objects. This field may be used interchangeably with the string 'appData'.
opensocial.DataRequest.PeopleRequestFields.ESCAPE_TYPE
<static> Member of: opensocial.DataRequest.PeopleRequestFields.ESCAPE_TYPE How to escape Person fields and app data returned from the server; defaults to HTML_ESCAPE. Possible values are defined by EscapeType. This field may be used interchangeably with the string 'escapeType'.
opensocial.DataRequest.PeopleRequestFields.FILTER
<static> Member of: opensocial.DataRequest.PeopleRequestFields.FILTER How to filter the people objects; defaults to ALL. Possible values are defined by a:FilterType. This field may be used interchangeably with the string 'filter'.
The following example returns the owner's friends who have the current application installed:
function response(data) {
output(data.get("req").getData().size());
gadgets.window.adjustHeight();
};
function request() {
var req = opensocial.newDataRequest();
var idspec = opensocial.newIdSpec({'userId':'OWNER', 'groupId':'FRIENDS'});
var params = {
'filter' : 'hasApp'
};
req.add(req.newFetchPeopleRequest(idspec, params), "req");
req.send(response);
};
request();
opensocial.DataRequest.PeopleRequestFields.FILTER_OPTIONS
<static> Member of: opensocial.DataRequest.PeopleRequestFields.FILTER_OPTIONS Additional options to be passed into the filter, specified as a Map<String, Object>. This field may be used interchangeably with the string 'filterOptions'.
opensocial.DataRequest.PeopleRequestFields.FIRST
<static> Member of: opensocial.DataRequest.PeopleRequestFields.FIRST When paginating, the index of the first item to fetch; specified as a number. This field may be used interchangeably with the string 'first'.
Use this to page through groups of friends. The following example starts fetching from the 20th friend:
function response(data) {
output(data.get("req").getData().size());
gadgets.window.adjustHeight();
};
function request() {
var req = opensocial.newDataRequest();
var idspec = opensocial.newIdSpec({'userId':'OWNER', 'groupId':'FRIENDS'});
var params = {
'first' : 20
};
req.add(req.newFetchPeopleRequest(idspec, params), "req");
req.send(response);
};
request();
opensocial.DataRequest.PeopleRequestFields.MAX
<static> Member of: opensocial.DataRequest.PeopleRequestFields.MAX The maximum number of items to fetch, specified as a number; defaults to 20. If set to a larger number, a container may honor the request, or may limit the number to a container-specified limit of at least 20. This field may be used interchangeably with the string 'max'.
Use this to page through groups of friends. The following example sets the page size to 5:
function response(data) {
output(data.get("req").getData().size());
gadgets.window.adjustHeight();
};
function request() {
var req = opensocial.newDataRequest();
var idspec = opensocial.newIdSpec({'userId':'OWNER', 'groupId':'FRIENDS'});
var params = {
'max' : 5
};
req.add(req.newFetchPeopleRequest(idspec, params), "req");
req.send(response);
};
request();
opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS
<static> Member of: opensocial.DataRequest.PeopleRequestFields.PROFILE_DETAILS An array of opensocial.Person.Field specifying what profile data to fetch for each of the person objects. The server will always include ID, NAME, and THUMBNAIL_URL. This field may be used interchangeably with the string 'profileDetail'.
opensocial.DataRequest.PeopleRequestFields.SORT_ORDER
<static> Member of: opensocial.DataRequest.PeopleRequestFields.SORT_ORDER A sort order for the people objects; defaults to TOP_FRIENDS. Possible values are defined by SortOrder. This field may be used interchangeably with the string 'sortOrder'.
opensocial.DataRequest.SortOrder
The sort orders available for ordering person objects.
opensocial.DataRequest.SortOrder.NAME
When used will sort people alphabetically by the name field. This field may be used interchangeably with the string 'name'.
opensocial.DataRequest.SortOrder.TOP_FRIENDS
<static> Member of: opensocial.DataRequest.SortOrder.TOP_FRIENDS When used will sort people by the container's definition of top friends. This field may be used interchangeably with the string 'topFriends'.
{{ JsApiAlphaList_(v0.9) }}