Gray Liao: Facebook ActionScript Graph API ( 0 ) Graph API與Facebook官方文件介紹

Facebook Graph API今年五六月推出後，到現在已經慢慢成熟；而Flash 平台方面，很早就有人嘗試用透過URLLoader與javascript去使用Graph API了，在九月左右，Adobe也推出了由gskinner.com開發的官方版Adobe ActionScript 3 SDK for Facebook Platform API。它的名字好像很亂很不統一，大家知道我在講哪個東西就好。這個API在12月6號更新到1.5版，使用上更簡便，還多了mobile的部分。而使用時，必須先知道Graph API以及FQL等的呼叫方式，也常常需要查詢Facebook的官方文件。因此，一開始我們先不管ActionScript，而是先跟大家介紹Facebook官方文件上有哪些東西。

翻看Facebook開發人員說明文件應該是每個要開發Facebook應用的人都應該做的基本功。不過上面一堆名詞，文件之間又連來連去，對剛開始接觸的人來說實在不太容易搞懂。這邊就稍微整理說明一下各個名詞與重要的幾篇文件，順便說明Graph API基本的呼叫方式，以便我們之後使用ActionScript版的API。不過還是建議大家有了點概念之後再回去仔細看看Facebook的官方文件。

Authentication and Authorization：

簡介
認證與授權是使用OAuth 2.0 protocol，簡單來說，我們呼叫一個認證與授權網址：

https://graph.facebook.com/oauth/authorize

後面帶參數
client_id：App.的ID。
redirect_uri：完成後要轉回哪個網址。
client_secret：App.的secret，要登入成App的Administrator才需要傳送。
scope：需要同時取得Extended Permissions可以由此傳送，取得Extended Permissions目的是有些資料或操作是需要user額外同意，App.才能去取得或操作，例如：user_photos,user_videos,publish_stream。
display：這個授權頁要如何呈現，有page，popup，wap，touch四種。
呼叫完後最重要的是取得access_token，經由這個access_token，Facebook就知道呼叫它的user是誰，透過哪個App.，擁有哪些權限等等。

Graph API：

簡介
參考文件
這部分是現在Facebook的core API。每個user，page，photo，網址，......等等都被視為一個object，每個object都有個object ID。透過呼叫

https://graph.facebook.com/{object_ID}

來取得這個object的公開資料。object ID除了可以用一串數字的ID，也可以帶入user名字，page名稱等，甚至可以用me代替目前登入的user。
而跟每個object有關聯的東西叫做它的connection，例如我的相簿，我的朋友，"我"是object，而"相簿"與"朋友"是connection，可以這樣呼叫：

https://graph.facebook.com/{object_ID}/{connection}?access_token=xxxxxxxxx

通常要找某個object相關聯的資料時會牽涉到授權的問題，所以後面就需要帶我們之前取得的access_token。單純呼叫object時後面如果多帶access_token就可以取得更多的資料。回傳的資料格式是JSON格式。
更進階的呼叫，還有以下幾種：

Reading 讀取資料：
基本上使用GET呼叫，多帶一些參數，可以取得更符合我們需求的資料。
fields：指定我們需要的欄位，如fields=id,name,picture。
ids：一次取得多個object的資料，呼叫的方式在網址上就沒有object ID那一層，而是以ids參數，以逗號將多個object ID一次傳給Facebook，也就是像

https://graph.facebook.com?ids=obj_id1,obj_id2,obj_id3

picture：picture其實也不算參數，而是比較像connection的方式放在object ID後面，它是用來取得user，page，group，event，album等等有profile photo頭像縮圖用的，後面可以帶type參數，分為square(50x50)，small(50寬，高看比例)，large(200左右寬，高看比例)，例如：

https://graph.facebook.com/gray.liao/picture?type=large

呼叫完會直接轉向圖檔的連結。特別注意Flash如果用這種方式取得圖檔，由於是經過轉址才取得圖片，所以雖然可以讀進來，但卻無法對這張圖做pixel級的更動，例如使用BitmapData.draw()或一些濾鏡功能，都會出現安全性違規。即使設定了Loader.load()方法的第二個參數LoaderContext也沒有用，因為只會設定到轉址前的網址，而沒有真正設定到轉址後的圖片網址。感謝Jason提醒。
limit, offset:資料比數太多時希望做分頁，就可以代入limit(一次幾頁，數字)以及offset(第幾頁，數字)。
until, since：輸入unix timestamp或這些字串轉換的時間。
metadata：代入metadata=1可以看這個object有哪些connection可用。

Searching 搜尋：
就像是Facebook首頁上的搜尋框，我們也可以透過Graph API來搜尋資料，搜尋格式為：

https://graph.facebook.com/search?q=QUERY&type=OBJECT_TYPE

q就是代入關鍵字，type是要搜尋的object類別，例如post，user，page等等。
而讀取朋友的News Feed最新動態則有個特別的搜尋法：

https://graph.facebook.com/{object_id}/home?q=facebook

object_ID要代入目前user的朋友才讀的到東西，因為我們通常只能看到朋友的動態訊息啊。

Publishing 發布、寫入資料：
發布塗鴉牆post，對某post按讚，回復某post等等，都需要寫入資料到Facebook，這時候需要改用POST來傳遞資料。例如呼叫

https://graph.facebook.com/{post_id}/comments

同時用POST方法傳送access_token與message，就可對一個post留言。官方文件裡有完整的列表，這邊就不多介紹了。

Deleting 刪除：
利用DELETE方式來刪除資料，無法使用DELETE的程式，例如JavaScript或ActionScript，可以用POST，而呼叫的網址後面多帶?method=delete，例如

https://graph.facebook.com/{post_id}/likes?method=delete

同時用POST傳送access_token就可以對一個post取消讚。

Analytics 取得分析資料：
可以透過Graph API取得Insight上面的分析資料。要使用這部分則必須是App的Administrator才行。呼叫法請自行參閱官方文件。

Social plugins：

簡介
使用簡單的html tag，就可以在網站上崁入幾個Facebook提供的plugins，例如Like Button，Login Button，Live Stream等等。使用方法請參考官方文件。

Open Graph protocol：

簡介
在一般網站上面加入一些meta tag，就可以讓這個網站也成為Facebook social graph裡的一個object，使用Graph API時也就可以查看這個object相關的資料了。詳細請參閱官方文件。

JavaScript SDK：

參考文件
前面提到，Graph API是core API，而在各個程式語言或平台則有各自的SDK，讓我們更方便的呼叫Graph API。使用JavaScript時，自然是要用JavaScript SDK。而我們之後要介紹的ActionScript SDK有部分是透過JavaScript SDK去呼叫Graph API，因此這邊稍微介紹一下下。使用前在我們的html上面必須加兩個東西，第一個要先include js檔案：

src="http://connect.facebook.net/en_US/all.js"

中文版可以改成：

src="http://connect.facebook.net/zh_TW/all.js"

第二個是要在body裡面加入一個div tag：

文件上沒有解釋很清楚，不過IE8如果沒加這個tag會有問題，所以請大家乖乖加一下。其他應用我們就不詳細去探討了，有興趣的請看官方文件，也可以看小綠分享的這篇。

其他SDK：

其他還有PHP SDK，Python SDK，iOS SDK for iPhone, iPod touch, and iPad，Android SDK，有需要的自行翻閱官方文件。

Platform Dialogs：

參考文件
彈出對話視窗，例如feed或stream.publish等會彈出發布到塗鴉牆的對話視窗。使用這個方法不需要額外的permission，因為這個dialog會要求使用者跟他互動，也就是最後一定是使用者按下確認或送出之類的按鈕。如果瀏覽器處於還沒登入Facebook的狀態，那麼這個dialog也會先處理登入的部分。所以相當好用。
基本上是呼叫

http://www.facebook.com/dialog/

這個網址，例如我們如果要發布一個信息到塗鴉牆，可以呼叫：

http://www.facebook.com/dialog/feed?app_id=xxxxxxxxxxxxxx&redirect_uri=http://www.example.com/response/&display=popup

後面是帶app_id，redirect_uri(處理完後轉址)，以及display，display是dialog呈現的方式，用popup則是強制用彈出視窗方式。其他可用page或iframe，手機有touch與wap。

Graph Realtime API：

簡介
Facebook建議我們把user的公開資料記錄在我們自己的server，以減少呼叫Facebook Server的次數。而當user資料有更新時，則我們可以請Facebook更新到我們的server，這樣可以確保我們Server上的資料是最新的，又可以減少呼叫Facebook Server的次數。詳細請看官方文件。

Facebook Query Language (FQL)：

參考文件
另一個我們要比較關注的內容。FQL是為了去查詢一些Graph API沒有提供的欄位而存在的方法，而之前提到圖片不是直接網址的問題，也可以透過FQL來抓到正確的網址。簡單說，Facebook上有很多的資料庫table，而我們可以用類似SQL的資料庫查詢與法來查詢這些table，以獲取我們的資料。基本上，我們要呼叫這個網址：

https://api.facebook.com/method/fql.query?query=QUERY

QUERY就是我們依據想要查詢的資料，拼湊出FQL語法後代入。
這個語法基本的架構大概是：

SELECT [fields] FROM [table] WHERE [conditions]

fields：要查詢的欄位，用逗號隔開，例如name, id。
table：要查詢的table，FQL只能一次查詢一個table。
conditions：查詢條件，例如uid=me()。me()相當於目前登入user的id。其他特殊的function還有now()，strlen()，substr()，strpos()。
另外也可以使用AND，OR，NOT，ORDER BY，LIMIT等等SQL語法。也可以在SELECT與WHERE裡使用IN來做多重的查詢，例如：

SELECT uid, name, pic_square FROM user WHERE uid = me() OR uid IN (SELECT uid2 FROM friend WHERE uid1 = me())

這個可以撈出自己跟朋友的uid, name, pic_square三個欄位的資料。
發出request時後面可以帶參數format，可選擇回傳資料的格式是XML或JSON。

查詢每個table可能需要一些extended permissions，要注意一下文件上的說明。

Facebook Markup Language (FBML)：

要被移除的東西，就不要再用了。

Old REST API：

參考文件
一個比較麻煩的東西。這邊主要是舊版的Facebook Connect API的一些方法，使用Graph APi的方式去呼叫。麻煩的地方在於，這裡面的東西也準備要被移除了，但有些替代的方法Graph API還沒有提供！所以使用時請注意說明文件右邊上面，如果已經有替代方法，那麼它會告訴我們應該用Graph API或FQL的哪個Object或Table來查詢；有些則是快要被移除但還沒有替代方法，那麼還是只能用它，不過要隨時注意Facebook公布的相關訊息；如果都沒寫，那就是暫時不會被移除，也還沒有替代方法，那麼還是只能先用它，並且注意Facebook相關的訊息。
呼叫的方法為：

https://api.facebook.com/method/{method_name}?access_token=xxxxx&arg0=value0&arg1=value1

使用這類API的原則是：當我們用Graph API跟FQL都湊不出想要的功能時，先來這邊看看有沒有適合的方法，找到那個方法後，先看畫面右上方有沒有剛剛提到的訊息，如果有提示我們Graph API哪些方法可以取代，就再回去找Graph API；否則，只好先用Old REST API，但要隨時注意Facebook是否有將這個方法刪除。

Old JavaScript Client Library：

要被移除的東西，就不要再用了。

Tools 工具：

Facebook上有些工具可以在開發時使用。
Live Status：如果Facebook連不上，可查看Server的狀況。
Insights：查看App.的分析資料。
Test Users：前陣子才出來的功能，可以開幾個Test Users來測試App.。
JavaScript Test Console：可以測試JavaScript SDK。點它的Examples也有很多範例程式碼可以參考。
URL Linter：應該是用來查看有加入Open Graph protocol的meta tag的網站。

Gray Liao

2010年12月31日星期五

Facebook ActionScript Graph API ( 0 ) Graph API與Facebook官方文件介紹

Authentication and Authorization：

Graph API：

Social plugins：

Open Graph protocol：

JavaScript SDK：

其他SDK：

Platform Dialogs：

Graph Realtime API：

Facebook Query Language (FQL)：

Facebook Markup Language (FBML)：

Old REST API：

Old JavaScript Client Library：

Tools 工具：

See Also 其他：

3 則留言:

2010年12月31日 星期五

Facebook ActionScript Graph API ( 0 ) Graph API與Facebook官方文件介紹

Authentication and Authorization：

Graph API：

Social plugins：

Open Graph protocol：

JavaScript SDK：

其他SDK：

Platform Dialogs：

Graph Realtime API：

Facebook Query Language (FQL)：

Facebook Markup Language (FBML)：

Old REST API：

Old JavaScript Client Library：

Tools 工具：

See Also 其他：

3 則留言:

2010年12月31日星期五