Zing osapi v1.3.3

CÔNG TY VNG

ZING ME OPENSOCIAL API
VERSION 1.3.3
Nhóm Zing Me Open Social

TP. HCM
10/2010

1

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

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

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

<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

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

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

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

$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

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 =>
...
1 =>
...
2 =>
...

10

3 =>
...
4 =>
...
5 =>
...

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');

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

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');

*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

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

http://code.google.com/p/opensocial-php-
client/source/browse/trunk/src/examples/listFriends.php

5. Gadget

http://code.google.com/apis/gadgets/docs/ui.html

6. XML

http://code.google.com/apis/gadgets/docs/reference.html

Nhóm Zing Me Open Social

Nguy n H ng H i – Nguy n Thanh Tú

14

Zing osapi v1.3.3

More Related Content

Viewers also liked (8)

Similar to Zing osapi v1.3.3 (20)

Recently uploaded (10)

Zing osapi v1.3.3