在JavaScript SDK里使用SoundCloud API
SoundCloud開發出了一款可被開發者使用的API，這款API能使開發者獲得他們想要的幾乎任何數據。但是該API的用法有些混亂，特別是對初學者來說，因為此時的SoundCloud API開發文檔和文檔示例使用的都是SDK(軟件開發工具箱)的不同版本。
SoundCloud介紹鏈接地址: http://baike.sogou.com/v128528573.htm
SoundCloud API和SoundCloud SDK之間有什么區別呢？從根本上說,SoundCloud API是一個URL的集合，它給開發者提供了從SoundCloud服務器獲取數據的權限， 而SoundCloud SDK是為查詢SoundCloud API提前寫好的庫(或者客戶端)。如果想了解更多關于這方面的內容,點擊以下鏈接：http://stackoverflow.com/questions/834763/difference-between-an-api-and-sdk
在這個教程里，我們將學到如何訪問SoundCloud API和如何簡化使用SoundCloud SDK的過程。我們將從SoundCloud上學習如何設置SoundCloud SDK，然后接著編寫JavaScript代碼來獲取SoundCloud數據，播放音頻和更多SoundCloud提供的功能。
入門指南
Promises介紹鏈接地址: http://www.oschina.net/translate/what-is-the-point-of-promises?print
了解HTTP和API的概念和工作方式對你學習本教程將會有幫助。如果你想了解更多關于API的信息,我推薦你看看:An Introduction to APIs(對API的一個介紹。鏈接地址:https://zapier.com/learn/apis/)。同時知道一點關于異步JavaScript，promises和回調函數對你學習本教程也是有幫助的。在本文我們的代碼示例中使用了jQuery，所以如果你了解jQuery的基本知識，那么你閱讀本文的代碼示例就不會那么痛苦。
為了使用JavaScript來開始查詢SoundClound API，我們需要下載由SoundClound提供的JavaScript SDK。就像在文章開頭提到的，這里共有兩個不同的SDK版本可以使用。
使用哪個版本的SDK呢?
這兩個版本的SDK的主要不同之處在于當一個異步請求產生并將請求發送給SoundClound API時它們返回數據的方式不同。***版本的SDK返回的是一個Promise，而另一個版本的SDK需要把一個回調函數作為一個參數返回。
我注意到一個問題，隨著文檔使用的SDK版本，在該版本的SDK用戶登錄功能界面上似乎有一個問題，這個問題就是彈出的登錄窗口不會自動關閉。
因此，為了簡單起見，并且因為老版本SDK更穩定，我們將在文章示例中使用老版本的SDK來貫穿本教程。此版本的SDK將需要為客戶端的異步請求返回一個回調函數。
使用SoundCloud API
設置一個基本的HTML文檔
我們創建一個基本的HTML頁面，該頁面用作我們的主頁。我們在這個頁面上<script>標簽的屬性src里包含進了SDK的地址，這樣我們就可以使用SDK的功能了。
- <!DOCTYPE html>
- <html>
- <head>
- <title>Include SDK - Using SoundCloud API</title>
- <script src="//connect.soundcloud.com/sdk.js"></script>
- </head>
- <body></body>
- </html>
注意:我們在HTML頁面里的<script>標簽的src里包含進去的SDK地址是SoundCloud的服務器地址。你也可以把SDK下載下來，然后像下面這樣引用:
- <script src="sdk.js"></script>
可以通過下面的方法步驟測試一下SoundCloud的SDK是否在你的網頁中被正確加載：
-
用瀏覽器打開這個頁面(建議使用谷歌的Chrome瀏覽器)。
-
在瀏覽器里打開開發者控制臺(在谷歌Chrome瀏覽器里打開開發者控制臺的快捷鍵是Ctrl+Shift+J)。
-
在開發者控制臺里輸入SC,然后按Enter鍵。SC就是剛剛我們在HTML頁面里包含的SDK創建的一個JavaScript對象。
如果出現了未知的錯誤，那就說明SoundCloud的SDK沒有被正確加載。試著刷新一下，同時確定你的SDK文件(也就是sdk.js文件)的路徑是正確的。
注冊一個SoundCloud App
去注冊一個SoundCloud app，你需要做的就是擁有一個SoundCloud賬戶。如果你還沒有一個SoundClound賬戶，就去創建一個。通過注冊一個 app，SoundCloud服務器就能夠驗證我們的請求，這樣其他人就不可能以我們的名義來發送一個請求了。
注意：如果我們不準備在我們自己的網站中使用SoundClound用戶登錄功能，我們可以跳過這一步。這將在下面的部分解釋。
-
打開SoundClound app頁面。在這個頁面上所有我們已經創建好的app都會被列出來。確保你登錄了你的SoundCloud賬戶。注意:你不用為了這個目的創建一個獨立的賬戶。你可以用同一個賬戶來為你的個人目的使用。
-
點擊注冊一個新應用按鈕。
-
給你的app起一個名字,然后點擊復選框接受SoundCloud的開發者政策條款。
-
點擊那個大大的”注冊”按鈕,來完成app的注冊。
在我們成功注冊之后，注冊頁面將直接跳轉到我們剛剛創建好的app設置頁面。在app設置頁面上，我們將看到我們的app客戶端ID，這個ID將會被用來驗證授權我們的請求。我們可以關掉該頁面,然后現在開始回調字段了。我們之后會用到這個客戶端ID的。
初始化客戶端
通過”初始化客戶端”，那也就是意味著我們使客戶端準備好在它和SoundCloud API之間做數據的交換。我們可以在我們之前創建的基本HTML文檔里來做初始化客戶端的工作，或者在一個內部js文件里來做初始化客戶端的工作。
JavaScript語法是這樣做的:
- SC.initialize({
- client_id: "CLIENT_ID",
- redirect_uri: "CALLBACK_URL"
- });
(代碼見原文)
讓我們分段來看它:
-
上面代碼中的CLIENT_ID會在我們注冊app的時候提供給我們。
-
上面代碼中的CALLBACK_URL是callback.html的URL,這個callback.html是用戶登錄后一個HTML文件的稱呼。我們很快就會創建它。
在初始化完成之后,現在我們可以準備查詢SoundCloud API了。讓我們看看在那之前我們可以做的一些例子。
示例
如果我們打開瀏覽器的控制臺并輸入”SC.”，然后與SC對象有關的方法就會列出來。SC.get(uri,callback)就是其中一個方法，這個方法用來向SoundCloud API產生GET請求。
獲得一份跟蹤列表
為了獲得跟蹤的隨機列表，我們可以使用SC.get()方法,像下面這樣:
- SC.get("/tracks", function(response) {
- for (var i = 0; i < response.length; i++) {
- $("ul").append("<li>" + response[i].title + "</li>");
- }
- });
(代碼見原文)
上面的代碼是干什么的，它是用來查詢/tracks端點并且在查詢完端點后返回一個回調函數的。響應數據是保存在回調響應參數里的，它是一個有著很 多屬性的JavaScript對象數組，title屬性就是眾多屬性中的一個。我們可以在代碼里寫:console.log(response[0])來 在控制臺日志輸出響應數據的***個，而不用循環遍歷所有的對象和對象所對應的屬性。然后,我們就會知道哪些屬性我們可以使用。
注意:在這個代碼示例中，我們在初始化的時候并沒有指定一個回調URL。這是因為我們指定不指定都不重要。不管怎樣我們的代碼都會執行。但是一旦我 們實現了用戶登錄功能，這就是必須的而且很重要了，因為當你指定一個回調URL后，其他人就不可能使用我們的Client ID。
嵌入一段跟蹤代碼
SC對象提供了其他的方法:SC.oEmbed(url,options,callback)。該方法把SoundCloud播放器嵌入我們的網站，并且允許我們播放我們選擇的軌跡。
- SC.oEmbed('https://soundcloud.com/username/complete-url-to-the-track', {maxheight: 200, auto_play: false}, function(res) {
- $("#player").html(res.html);
- });
我們分段來看它:
-
首先在該方法的***個參數里,我們給了一個完整的我們想要播放的跟蹤URL。
-
該方法的第二個參數是可選參數,在這個參數里,我們可以為播放器設置一些選項。如果想了解更多,點擊下面鏈接:https://developers.soundcloud.com/docs/api/reference#oembed
-
第三個參數是一個回調函數,在這個回調函數里,我們將我們頁面里的(id為player)的一個元素的內容用該播放器(res.html)的HTML代碼替換。
這個跟蹤路徑可以用來在一個網站里嵌入一首歌或者一首音樂。
實現用戶登錄
為了實現用戶登錄功能,我們需要有一個回調URL來達到驗證授權的目的。這是OAuth協議的要求。如果你想了解OAuth協議，這里有一個OAuth協議的簡單解釋:OAuth 2 Simplified(鏈接地址:https://aaronparecki.com/2012/07/29/2/oauth2-simplified)。因此讓我們在app設置里添加一個名為”callback.html”的回調URL，這個callback.html我們接下來就會創建。
OAuth協議介紹鏈接地址: http://menglimengwai.iteye.com/blog/496250
創建回調頁
在一個用戶登錄后，彈出式窗口會重定向到該文件。在我們的例子中，我們把該文件定義為”callback.html”，并且該文件和我們的主頁(index.html)保存在相同的目錄里。這個文件就是在我們的app設置里我們需要在回調字段里給定的文件。
我們需要在回調文件里使用的代碼在開發文檔里有提供。然而，開發文檔有點過時，因此我們需要稍微調整一下來滿足現在的開發需要標準。
你可以根據你個人的喜好來調整它的通知和設計,但是現在,我們使它越簡單越好:
- <!DOCTYPE html>
- <html lang="en">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <title>Connect with SoundCloud</title>
- </head>
- <body>
- <h4>This popup should automatically close in a few seconds</h4>
- <script>
- document.onload = function () {
- window.opener.setTimeout(window.opener.SC.connectCallback, 1);
- }
- </script>
- </body>
- </html>
用戶登錄
SC.connect(callback)就是實現用戶登錄功能的方法。它通過打開一個彈窗式的窗口,提醒用戶登錄他們的SoundCloud賬戶。基本的使用方法如下:
- SC.connect(function () {
- console.log("User has logged in");
- });
如下是更有趣的示例:
- SC.connect(function () {
- SC.get("/me", function (response) {
- console.log("Welcome" + response.username);
- });
- });
讓我們分段來看它:
-
在用戶完成登錄以后，用戶登錄頁面將會被重定向到我們之前創建的callback.html頁面。
-
然后隨著我們閱讀完callback.html里的代碼,彈出式窗口會自動關閉。
-
在那之后，我們的回調函數將獲得回調,該回調是在SC.get()方法里通過一個GET請求到”/me”端點獲得的。
-
當GET請求完成時，上述代碼的回調函數就會執行,然后在控制臺會輸出一條歡迎登陸的信息。
注意:請求”/me”返回的是當前登陸用戶的數據。因此，在用戶登錄之前請求該URL將產生一個錯誤的信息。
處理用戶數據
一旦用戶登錄完成，有很多事情我們可以做。為了演示一些功能,我在GitHub上創建了一個演示站點。你可以點擊這里查看源代碼: https://github.com/sitepoint-editors/SC_API,并且可以點擊這里看看它的執行效果: http://mustagheesbutt.github.io/SC_API/。
讓我們看看這兩個文件。在index.html里,有四個重要的div元素,它們在用戶完成登錄后將會填滿用戶的數據:
- <main>
- <div id="ui">
- <h2>Welcome <span></span></h2>
- <img id="avatar" />
- <div id="description"></div>
- </div>
- <!-- TRACKS -->
- <div id="tracklist">
- <h3>Your Tracks:</h3>
- <ul></ul>
- </div>
- <!-- PLAYLISTS -->
- <div id="playlists">
- <h3>Your Playlists:</h3>
- <ul></ul>
- </div>
- <div id="player"></div>
- </main>
第二個最重要的文件是script.js:所有的奇跡都發生在這個文件里。大部分代碼我們都很熟悉，但是我們還是快速地看看:
- // Initialization of SDK
- SC.initialize({
- client_id: "21832d295e3463208d2ed0371ae08791",
- redirect_uri: "http://mustagheesbutt.github.io/SC_API/callback.html"
- });
首先初始化我們的app。注意，這次我們用redirect_uri指定了我們的callback.html頁面。這個URL或者URI必須和我們在app設置里指定的一致。
- // Login handler
- var user_perma;
- $("#login").click(function () {
- SC.connect(function () {
- SC.get("/me", function (me) {
- user_perma = me.permalink;
- setUI(me.username, me.avatar_url, me.description);
- });
- if (SC.isConnected) {
- $("header, main").addClass("loggedIn");
- }
- getTracks();
- getPlaylists();
- });
- });
然后我們給標簽id為login的button添加一個點擊事件句柄。當該按鈕被點擊時，將會在點擊事件代碼里執行SC.connect(callback)代碼,該代碼執行后，將會彈出一個窗口提示用戶登錄。
當用戶登錄完成后，彈出的窗口會關閉。然后SC.connect()里的回調函數就會執行。在回調函數里，我們對”/me”端點發起一個GET請 求,而”/me”端點返回當前登錄用戶對象。在剛才我們發起的GET請求回調里，我們在變量user_perma里存儲用戶的***鏈接，該參數是在全局范 圍定義的，所以我們之后可以使用它。
setUI()方法，getTracks()方法和getPlaylists()方法的功能分別是，設置UI，列出用戶的跟蹤記錄和列出每個用戶的播放列表。這些功能在同一個文件里已經被定義了。
- //找點東西播放
- function play(uri) {
- url = "http://soundcloud.com/" + user_perma + "/" + uri;
- SC.oEmbed(url, {maxheight: 200}, function (resp) {
- $("#player").html(resp.html);
- });
- }
//當一個播放軌跡或者一個播放列表被檢查時,使用’play()’函數播放
- $("ul").on("click", function (e) {
- var title = e.target.innerHTML;
- if ( tracks.hasOwnProperty(title) ) {
- play(tracks[title]);
- } else if (playlists.hasOwnProperty(title)) {
- play("sets/" + playlists[title]);
- }
- });
當任何跟蹤路徑或者播放列表名被點擊，play()方法就會執行，該方法會為點擊的跟蹤路徑或者播放列表名通過SC.oEmbed()方法來在我們的頁面中嵌入一個音頻播放器。
我們能通過代碼做很多事情，例如獲取用戶類型或者更新用戶的信息，獲取用戶的頭像，接下來運行代碼看看SoundCloud服務器返回的信息里用戶是誰和他們的愛好是什么。
總結
-
如果老版本的SDK的用戶登錄功能可以使用，請使用老版本的SDK。因為老版本的SDK穩定，并且返回的數據使用回調函數返回。
-
如果老版本的用戶登錄功能不可用，可以使用SDK的新版本。新版本的SDK使用promises來返回數據。
-
通過一個簡單的GET請求就能訪問SoundCloud API獲取到數據。
-
用戶特有的數據可以通過”/me”端點獲取，但是只有在用戶使用他們的SoundCloud賬戶登錄我們的網站的情況下才有效。
從客戶端查詢一個API是一個很強大的工具，因為它在復雜的后端保存了我們的信息。SDK使我們的編程生活變得簡單很多。在學習了它的基礎用法后，我們甚至可以編寫出更加強大的和用戶更加友好的web應用。點擊查看一些示例(鏈接地址: http://codepen.io/search/pens?q=soundcloud&limit=all&type=type-pens),并且查看官方的SoundCloud文檔來學習更多關于這個強大的API的可以使用的方法。
我希望從你那里聽到你用SoundCloud SDK構建的應用的信息(或者正計劃構建的應用的信息)。請讓我看見你們的評論!
作者介紹：
Mustaghees Butt 是一名Web開發人員和作家
Mustaghees是一名自由的Web設計師和開發者，他有時也寫些文章和教程。
他的興趣包括計算機科學(包括機器人技術，AI人工智能和網絡技術)和文學藝術。
譯文鏈接：http://www.codeceo.com/article/javascript-sdk-soundcloud-api.html
英文原文：Using the SoundCloud API with the JavaScript SDK
