在JavaScript SDK裡使用SoundCloud API

2016-04-19    分類：WEB開發、程式設計開發、首頁精華1人評論發表於2016-04-19
JavaScriptCloudAPI

本文由碼農網 – 唐李川原創翻譯，轉載請看清文末的轉載要求，歡迎參與我們的付費投稿計劃！

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賬戶。注意:你不用為了這個目的建立一個獨立的賬戶。你可以用同一個賬戶來為你的個人目的使用。
  • 點選註冊一個新應用按鈕。
    Screenshot of the SoundCloud application dashboard
  • 給你的app起一個名字,然後點選核取方塊接受SoundCloud的開發者政策條款。
    Screenshot of choosing a name for the SoundCloud App
  • 點選那個大大的”註冊”按鈕,來完成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設定裡我們需要在回撥欄位裡給定的檔案。

Screenshot of setting the redirect URL

我們需要在回撥檔案裡使用的程式碼在開發文件裡有提供。然而，開發文件有點過時，因此我們需要稍微調整一下來滿足現在的開發需要標準。

你可以根據你個人的喜好來調整它的通知和設計,但是現在,我們使它越簡單越好:

<!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

Mustaghees Butt 是一名Web開發人員和作家

Mustaghees是一名自由的Web設計師和開發者，他有時也寫些文章和教程。

他的興趣包括電腦科學(包括機器人技術，AI人工智慧和網路技術)和文學藝術。

譯文連結：http://www.codeceo.com/article/javascript-sdk-soundcloud-api.html
英文原文：Using the SoundCloud API with the JavaScript SDK
翻譯作者：碼農網 – 唐李川
[ 轉載必須在正文中標註並保留原文連結、譯文連結和譯者等資訊。]

相關文章