呼叫Yahoo! API 介紹

先前介紹了Yahoo! OAuth導入分享，在其中Step 4 取得xoauth_yahoo_guid後，就可以拿來使用在其他Yahoo! API上了，而這邊以呼叫Yahoo! Contacts API為範例來介紹如何運用。

相關文件請參考Contact online documentation。

從文件中所述，要與Contacts API溝通，是對下面這個網址
http://social.yahooapis.com/v1/user/{guid}/contacts
以GET、POST、PUT的方式呼叫，使用GET只有讀取的權限，POST跟PUT則可以寫入。

呼叫的方式，文件上是用JSON的方式送值，不過我測試的結果，也可以用一般QueryString的方式去送GET/POST，所以我就介紹這個方式。

呼叫的參數基本上跟OAuth使用的一樣，所以就不特別介紹了，值得一提的是，呼叫Yahoo! API時，使用的oauth_signature_method不能是明碼，所以我使用的是HMAC-SHA1加密，這邊稍微介紹一下，HMAC-SHA1加密時是以一段BaseText為被加密的本體，一段Key為加密金鑰，在Yahoo! API的呼叫上，BaseText與Key有其特定的規則。



BaseText : http method&Link&Parameter
KeyText : Cunsumer_Secret&Token_Secret

需注意的是，BaseText除了用來分隔的兩個&之外，都必須符合RFC3986 URI的規範(如果懶得自己寫可以參考Yammyy寫好的code)，而Link的部分不能有問號，Parameter須按照字母順序排列。

KeyText部分比較單純，Cunsumer_Secret後面接&，再接上Token_Secret，如果沒有Token Secret就不用，但&還是要。

範例如下
BaseText

GET&http%3A%2F%2Fsocial.yahooapis.com%2Fv1%2Fuser%2Fyour_yahoo_guid%2Fcontacts&count%3Dmax%26oauth_consumer_key%3Ddjaabbccddeff%26oauth_nonce%3D12345%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp%3D1122334455%26oauth_token%3Dyour_oauth_token%26oauth_version%3D1.0

KeyText

cacacdcaccfcac123grfwccdacasdacacacadsdw&

編碼後的結果

z/qfMm99XVkI6przEHM/IZDOd4g=

實際上呼叫時的整串連結為

http://social.yahooapis.com/v1/user/your_yahoo_guid/contactsoauth_token=your_oauth_token&oauth_consumer_key=djaabbccddeff&oauth_signature_method=HMAC-SHA1&oauth_nonce=12345&oauth_timestamp=1122334455&oauth_version=1.0&count=max&oauth_signature=z%2fqfMm99XVkI6przEHM%2fIZDOd4g%3d

如果之前有用過OAuth的話，你會發現我在呼叫的參數中多了一個count，這是因為在預設上，Yahoo! Contact只會傳回前十個聯絡人的資訊，使用start/count等參數可以控制回傳的聯絡人數量與範圍，詳情可以看線上的說明。


用我上面的方式呼叫Yahoo! Contact API後，Yahoo!會傳回這個使用者XML格式的的聯絡人資訊，因為都是個人資訊所以就沒貼出範例，可以參考Contact online documentation的Example XML Response for GET Contacts的段，基本上是一樣的東西。


拿到Yahoo! Contact的Response後，就可以按照各人需求去取得所需資料來運用了，有一點要注意的是，每個聯絡人資訊所擁有的欄位不見得一致，像是你想要拿到email，但不見得所有聯絡人都有email這個欄位，取值的時候要注意一下，最好找個Yahoo聯絡人多的人來測會比較好。