1. CÔNG TY VNG
ZING ME OPENSOCIAL API
VERSION 1.3.3
Nhóm Zing Me Open Social
TP. HCM
10/2010
1
2. M CL C
1 Gi i thi u ............................................................................................................................ 3
2 Mô hình ho t ñ ng c a ng d ng trên Zing Me theo chu n Open Social ........................... 3
3 Các th XML mà Zing OS c n h tr .................................................................................. 4
3.1 <Module> ..................................................................................................................... 4
3.2 <ModulePrefs> ............................................................................................................. 4
3.3 <Content> .................................................................................................................... 4
3.4 <Require> .................................................................................................................... 5
4 JS API................................................................................................................................. 5
4.1 Danh m c hàm ............................................................................................................. 5
4.1.1 Gadgets ................................................................................................................... 5
5 REST API ........................................................................................................................... 7
5.1 Quy ñ nh chung ............................................................................................................ 7
5.1.1 Quy ñ nh v vi c tr d li u v ................................................................................. 7
5.1.2 Vi c c p quy n cho Application & ki m tra quy n .................................................... 8
5.2 Danh m c các API h tr ............................................................................................. 8
5.2.1 GET /social/rest/people/{guid}/@self........................................................................ 8
5.2.2 GET /social/rest/people/@me/@self .......................................................................10
5.2.3 GET /social/rest/people/{guid}/@friends .................................................................10
5.2.4 POST /social/rest/activities/@me/@self/@app .......................................................11
5.2.5 POST /social/rest/mediaitems/@me/@self .............................................................11
6 B ng chú gi i .....................................................................................................................13
7 Tham kh o: ........................................................................................................................13
2
3. 1 Gi i thi u
B API này g m các hàm c a Zing Open API phiên b n 1.0, ñã ñư c ñi u ch nh ñ tương thích
v i RESTful Protocol Specification v0.9, và b sung b JS API ñ ph c v cho Gadget theo mô
hình ho t ñ ng c a Open Social.
2 Mô hình ho t đ ng c a ng d ng trên Zing Me theo chu n Open Social
Gadget
(OS App Front-End)
1. JS API
5. JS API
gadget.io
callback
makeRequest()
2. OAuth
phone home
request
3. REST API
Home Server GET/POST
(OS App OAuth Zing Me Container
Back-End) Reserve
phone home
4. respond
OS App
Database
Hình 1: Mô hình ho t ñ ng c a OS App
3
4. Chú gi i:
• Open Social App có th g m Gadget + Home Server ho c ch là Gadget. OS quy ñ nh
quy n c a Gadget và Home Server ñ i v i Open Social data là gi ng nhau.
• Gadget giao ti p v i Home Server thông qua trung gian là Zing Me Container, s d ng
JS API (namespace gadget.io). B ng cách này, thông qua cơ ch 2 Legged OAuth
HomeServer ch c ch n các request nh n ñư c là ñ n t Gadget c a Home Server ñó,
và Zing Me Container bi t ñư c request là ñ n t User nào (Owner).
• Home Server cũng có th giao ti p Server – Server v i Zing Me Container thông qua
REST API.
3 Các th XML mà Zing OS c n h tr
3.1 <Module>
Là th g c
3.2 <ModulePrefs>
Ch a các thông tin mô t Gadget
Thu c tính Mô t
title Tên c a Gadget, s ñư c hi n tr trên màn hình.
description Mô t v Gadget.
author Tên tác gi
3.3 <Content>
Ch a mã ngu n c a Gadget
Thu c tính Mô t
type ”html”
view V trí mà Gadget ñư c hi n th
preferred_height Chi u cao m c ñ nh c a Gadget (pixel)
preferred_width Chi u r ng m c ñ nh c a Gadget (pixel)
Mã ngu n c a Gadget ñư c ñ t trong th CDATA:
<![CDATA[ source_code ]]>
VD:
4
5. <Content view="home">
<![CDATA[
Hello, home view!
]]>
</Content>
3.4 <Require>
Khai báo Gadget s s d ng các thư vi n JS nào
Thu c tính Mô t
feature Tên thư vi n
Các thư vi n h tr
Tên thư vi n Mô t
flash H tr nhúng Flash vào Gadget
tabs H tr t o Tab cho giao di n c a Gadget
4 JS API
4.1 Danh m c hàm
4.1.1 Gadgets
Mô t : ñ i tư ng h tr cho Gadget
4.1.1.1 io
Mô t : ñ i tư ng h tr truy v n và nh n d li u t Home Server
4.1.1.1.1 makeRequest
1. Mô t : Kh i t o Request ñ n HomeServer
2. Vào
Tên tham s Ki u d li u Mô t
url String url c a HomeServer
callback Function Hàm s nh n d li u tr v
3. Ra
Không
5
6. 4. Ví d :
function makeRequest() {
var params = {};
var url = "http://graargh.returnstrue.com/buh/fetchme.php";
gadgets.io.makeRequest(url, response);
};
function response(obj) {
//obj.text contains the text of the response
output(obj.text);
};
makeRequest();
4.1.1.2 Flash
Mô t : ð i tư ng h tr vi c nhúng Flash vào Gadget
4.1.1.2.1 embedFlash
1. Mô t : Nhúng file Flash vào Gadget
2. Vào
Tên tham s Ki u d li u Mô t
swfUrl String url c a file Flash
swfContainer String ID c a DOM s ch a Flash
swfVersion Number Phiên b n FlashPlayer t i
thi u c n có
opt_params Object Các ñ i tư ng ch a tham s
c a HTML
3. Ra
Không
4. Ví d :
gadgets.flash.embedFlash(url, "flashcontainer", {
swf_version: 6,
id: "flashid",
width: 300,
height: 250
})
6
7. 5 REST API
5.1 Quy đ nh chung
5.1.1 Quy đ nh v vi c tr d li u v
1. Các ñ i tư ng d li u tr v (Person, Activity, MediaItem,…) ñư c bi u di n dư i ñ nh
d ng JSON, theo như quy ñ nh trong ph n “Data Representations” c a RESTful
Protocol Specification v0.9.
2. ð i tư ng g c (root element) ph i ch a các giá tr sau (theo ñ c t c a OpenSearch):
Tên Mô t
startIndex V trí c a item ñ u tiên c a k t qu tr v c a l n g i hàm
này trong result set.
VD: truy v n có result set g m 10 k t qu , startIndex=5 t c
là item ñ u tiên trong l n g i hàm này là v trí th 5 trong
10 k t qu ñó.
itemsPerPage S item th c s ñư c tr v trong l n g i hàm này.
totalResults T ng c ng các k t qu c a truy v n n u b qua vi c phân
trang k t qu (t c là t ng s k t qu trong result set.
entry Ch a k t qu tr v
Có d ng m ng các item ho c 1 item tùy theo quy ñ nh lúc
g i hàm.
M i item là m t ñ i tư ng d li u.
VD:
{
"startIndex" : 1,
"itemsPerPage" : 10,
"totalResults" : 100,
"entry" : [
{...first item...},
{...second item...}
...
]
}
Trư ng h p ch tr v 1 item:
{
"startIndex" : 1,
"itemsPerPage" : 10,
"totalResults" : 100,
"entry" : {...only item...}
}
Ngoài ra có th ch a thêm các giá tr khác tùy ch n.
7
8. 3. N u xu t hi n l i, thì tr v mã l i tương ng như sau:
# Tên l i Mã l i
1 G i hàm sai cú pháp 400 Bad Request
2 Quá trình ch ng th c OAuth 401 Unauthorized
có l i, ho c App không ñư c
c p quy n
3 App không ñư c c p quy n 403 Forbidden
ñ th c hi n hành vi này
4 Không tìm th y ñ i tư ng 404 Not Found
ñư c yêu c u
5 Hàm chưa ñư c Zing h tr 501 Not Implemented
6 L i không xác ñ nh 500 Internal Server Error
5.1.2 Vi c c p quy n cho Application & ki m tra quy n
Hi n t i ZingMe chưa h tr User c p quy n cho t ng Application mà User ñã cài vào.
Do ñó quy n c a Application s căn c vào quy n m c ñ nh c a h th ng c p cho Application
ñó & các Permission do User c u hình trong trang “cài ñ t quy n riêng tư”.
Vi c ki m tra quy n (Authorization) ñư c tuân theo giao th c Two-legged OAuth.
5.2 Danh m c các API h tr
ði u ki n b o m t chung: User g i request ph i là OWNER, và OWNER ph i ñang ñăng nh p
vào Zing Me.
5.2.1 GET /social/rest/people/{guid}/@self
1. Mô t : l y thông tin c a User d a trên ID.
2. ði u ki n b o m t: {guid} ph i là ID c a OWNER ho c b n c a OWNER.
3. Input:
Tên tham s Mô t
{guid} Id c a User
4. Output: ð i tư ng People
VD: cách l y thông tin c a m t user
// t o ñ i tư ng osapi
$consumerKey = "c969713e3048fa919202961e1b9eb9c7";
$consumerSecret = "bc192fd03531094a78b60a91df93d5c7";
$userId = $_GET[“ownerId”]; // tham s này t có khi makeRequest Gadget
8
9. $storage = new osapiFileStorage('/tmp/osapi');
$provider = new osapiZingMeProvider();
$auth = new ZM_osapOAuth($consumerKey, $consumerSecret, $userId);
$osapi = new osapi($provider, $auth);
// ti n hành l y thông tin user
$extrafields = array( 'thumbnailUrl');
$self_request_params = array(
'userId' => "tunguyen.it", // ID c a user (tương ng v i user name c a Zing Me).
'groupId' => '@self', // l y thông tin c a user
'fields' => $extrafields // các trư ng b sung thêm
);
$batch->add($osapi->people->get($self_request_params), 'self');
$result = $batch->execute(); //ch y request và nh n v k t qu
- K t qu :
object(osapiPerson)[12]
public 'displayName' => string 'Nguy n Thanh Tú' (length=18)
public 'gender' => string 'male' (length=4)
public 'id' => string 'tunguyen.it' (length=11)
public 'name' =>
array
'familyName' => string 'Nguy n Thanh' (length=14)
'givenName' => string 'Tú' (length=3)
'formatted' => string 'Nguy n Thanh Tú' (length=18)
public 'isOwner' => boolean true
public 'isViewer' => boolean true
9
10. 5.2.2 GET /social/rest/people/@me/@self
1. Mô t : L y thông tin profile c a OWNER
2. Vào: không có
3. Ra
ð i tư ng Person c a OWNER
VD: tương t như ví d trư c, thay userId b ng @me
5.2.3 GET /social/rest/people/{guid}/@friends
1. Mô t : L y danh sách các b n c a user
2. ði u ki n b o m t: {guid} ph i là ID c a OWNER.
3. Vào:
Tên tham s Mô t
{guid} Id c a User
4. Ra:
Các ñ i tư ng Person
VD: l y danh sách b n bè c a 1 user
$extrafields = array( 'thumbnailUrl');
$friends_request_params = array(
'userId' => "@me", // used id.
'groupId' => '@friends', // @friends dùng ñ l y danh sách b n bè.
'fields' => $extrafields, // các trư ng b sung thêm.
'count' => 10, // s lư ng c n l y
'startIndex' => 0 // v trí b t ñ u
);
$batch->add($osapi->people->get($friends_request_params), 'friends');
$result = $batch->execute();
- K t qu :
object(osapiCollection)[49]
public 'list' =>
array
0 =>
object(osapiPerson)[13]
...
1 =>
object(osapiPerson)[14]
...
2 =>
object(osapiPerson)[15]
...
10
11. 3 =>
object(osapiPerson)[16]
...
4 =>
object(osapiPerson)[17]
...
5 =>
object(osapiPerson)[18]
...
5.2.4 POST /social/rest/activities/@me/@self/@app
1. Mô t : G i ñi 1 activity (~Feed c a Zing).
2. Vào:
Tên tham s (trong ph n body Mô t
c a request)
titleId Zing template bundle id
templateParams M ng các tham s có d ng
<key, value>
3. VD
- T o 1 feed trên Zing Me:
$createData = array();
$createData['message'] = "Hello message form testos.me.zing.vn";
$createData['actionLink'] = array(array(
'text' => "Action link title",
'href' => "http://testos.me.zing.vn")
);
$activity = new osapiActivity();
$activity->setId(195);
$activity->setField('createData', $createData);
$createParams = array(
"userId" => "tunguyen.it", // tư ng nhà c a user c n t o feed
"groupId" => '@self',
"activity" => $activity,
);
$batch->add($osapi->activities->create($createParams), 'createActivity');
$result = $batch->execute();
K t qu : tr v feed id n u thao tác thành công, ngư c l i thì thao tác v l i.
5.2.5 POST /social/rest/mediaitems/@me/@self
1. Mô t : T i 1 hình lên album m c ñ nh c a user ñang ñăng nh p.
11
12. 2. Vào:
Tên tham s (trong ph n body Mô t
c a request)
Content-Type ð nh d ng file hình (vd:
“image/png” hay
“image/gif”,…)
mediaItem D li u nh phân c a hình
3. Ra
N u upload thành công thì tr v ñ i tư ng MediaItem
VD:
- T i 1 hình lên Zing Photo:
$data = file_get_contents('test.png');
$user_params = array(
'userId' => '@me',
'groupId' => '@self',
//'albumId' => '', // zing photo không c n tham s albumId
'type' => 'IMAGE',
'mediaItem' => $data,
'contentType' => 'image/jpg'
);
$batch->add($osapi->mediaItems->uploadContent($user_params), 'upload_mediaItem');
$result = $batch->execute();
*Note: vì Zing Photo không cho phép ñưa tham s album id nên param ñưa vào s không có
tham s này.
- K t qu : tr v ñ i tư ng MediaItem
array
'albumId' => int 39861
'id' => int 335711957
'mimeType' => string 'image/jpg' (length=9)
'thumbnailUrl' => string 'http://img1-
photo.me.zing.vn/upload/original/2010/08/12/18/1281611819762494268_182_0.jpg' (length=88)
'type' => string 'IMAGE' (length=5)
'url' => string 'http://img1-
photo.me.zing.vn/upload/original/2010/08/12/18/1281611819762494268.jpg' (length=82)
12
13. 6 B ng chú gi i
Tên khái ni m Ý nghĩa
OS Open Social
Open Social Application/ App/ OS App ng d ng m ng xã h i theo chu n Open
Social
Zing OS API Các hàm API c a chu n Open Social mà Zing
Me ñã h tr
Connection Hai user trong Zing g i là có “connection” v i
nhau n u:
- Có m i quan h Friend
- Có m i quan h Fan
Activity Tương ñương Feed c a Zing
Item ð i tư ng d li u chu n ñư c mô t trong
RESTful Protocol Specification v0.9 (VD:
Person, Activity, MediaItem,…)
OWNER User s h u App hi n th i ñang ch y
VIEWER User ñang s d ng, hi n Zing ch cho phép
OWNER=VIEWER
7 Tham kh o:
1. OpenSocial Specification v0.9 & JS Function
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/OpenSocial-
Specification.html
2. OpenSocial RESTful Protocol Specification v0.9
http://www.opensocial.org/Technical-Resources/opensocial-spec-v09/REST-API.html
3. OAuth
Two-legged OAuth:
http://sites.google.com/site/oauthgoog/2leggedoauth/2opensocialrestapi
https://www.google.com/gadgets/directory/verify
http://wiki.opensocial.org/index.php?title=Validating_Signed_Requests
http://developer.constantcontact.com/book/export/html/279
4. Opensocial-php-client
13
