Spotify Web APIの使い方

事業開発部の酒匂です。
弊社ブログの下記記事を見て以来、私も何か書かねば！と思い、Spotifyについて書くことにいたしました。

オープンな音楽データベース「MusicBrainz」のマッシュアップサービスを作るための使い方まとめ

Spotifyとは

音楽のストリーミング配信サービスです。
https://www.spotify.com/jp/

同様のサービスにApple MusicやAmazon Music Unlimited‎などがありますね。

私は使いたいときに使える音楽視聴機だと思って利用しております。

Spotify for Developers

Spotifyは、Web API、AndroidやiOS向けのSDKなどを公開をしております。

https://beta.developer.spotify.com/documentation/

APIがあるとなると、とりあへず叩いてみたくなります。

Spotify Web APIの始め方

Spotify Web APIの概要

• RESTfulなWeb APIで、Spotifyが保持している音楽アーティスト、 アルバム、 トラック情報などのやりとりを行うことができます。
  
  https://beta.developer.spotify.com/documentation/web-api/より抜粋

• 各リソースへの操作は、以下のHTTPメソッドにて行います。

• Spotify URIやSpotify IDなど、Spotify特有のパラメータ情報をリクエスト、レスポンス時に扱うことがあります。

• レート制限に引っかかるとステータスコード429が返却される。これが返ってきた場合は、Retry-Afterヘッダーの値を確認し、そこに記載されている秒の間はAPIをコールすることができない。

• レスポンスデータは、JSON Object形式で取得します。

• タイムスタンプはUTC zero offset形式（YYYY-MM-DDTHH:MM:SSZ）

• 一部のAPIではページネーションをサポート（offset、limitパラメータで指定）

• 多くのAPIでは、クライアント側でレスポンスデータのキャッシュを行うためのヘッダー情報が付与される。

• レスポンスステータスコードは、RFC 2616 と RFC 6585に則って2xx、3xx、4xx、5xxを返す。

• レスポンスデータのエラー表現には、下記2種類のフォーマットを使用する。

  • Authentication Error Object
  • Regular Error Object

• APIをコールするにはOAuthアクセストークンが必要。

アカウントのセットアップを行う

Web APIを使用するには、Spotifyのユーザーアカウント(Premium or Free)を作成する必要があります。
アカウントを持っていない場合は、下記から行います。
https://www.spotify.com/jp/

すでにアカウントを持っている場合は、ダッシュボードページに行ってログインを行い、サービス利用に許諾します。
https://beta.developer.spotify.com/dashboard/

クライアントアプリケーションの登録を行う

Spotify Web APIをコールするクライアントアプリケーションをダッシュボードページから登録します。
"CREATE AN APP"をクリックします。

下記の画面が表示されますので、該当する方を選択します。
今回は商用ではないので、"No"を選択します。

下記の画面が表示されますので、クライアントアプリケーション名、その説明を入力し、同意事項にチェックを付けて"CREATE"を選択します。

下記の画面が表示されれば、クライアントアプリケーションの登録は完了です。

画面上の"SHOW CLIENT SECRET"をクリックして、値を確認しておきます。（Web APIへアクセスするために必要）

クライアントアプリケーションがWeb APIへアクセスするためには許可が必要

クライアントアプリケーションが、Spotifyのデータや機能にアクセスするには、それを行う許可が与えられている必要があります。

https://beta.developer.spotify.com/documentation/general/guides/authorization-guide/より抜粋

許可が誰に、どのように、与えられるかと言いますと、下記の2種類のパターンがあります。

• App Authorization
  • システム（Spotify）が、クライアントアプリケーションに、Spotify Platform (APIs, SDKs and Widgets)へアクセスすることを許可します。

• User Authorization
  • エンドユーザー（Spotifyのエンドユーザー）が、クライアントアプリケーションに、エンドユーザーが所有するデータへアクセスすることを許可します。

というわけで、繰り返しになりますが、クライアントアプリケーションがSpotify Platformへの許可されたリクエストを作成するには、データにアクセスする権限が与えられている必要があります。RFC-6749によると、この権限を得るプロセスには下記の関係者が関与します。

また、Web APIをコールするには、スコープを指定する必要があります。
スコープを使用すると、ユーザーがクライアントアプリケーションを使用して特定のAPIエンドポイントにアクセスできるようになります。 Web APIコールで渡すスコープのセットによって、ユーザーが付与する必要のあるアクセス許可が決まります。

クライアントアプリケーションが許可を得るための3つの方法

Spotifyでは下記の3つの方法が用意されております。

• Refreshable user authorization: Authorization Code
  • このフローでは、エンドユーザーはクライアントアプリケーションがリソースへアクセスすることを1度だけ許可します。そのため長期間稼働させるアプリケーションに適しています。 アプリケーションにはリフレッシュ可能なアクセストークンを提供されます。ちなみにトークン交換には秘密鍵の送信が含まれるため、ブラウザやモバイルアプリなどのクライアントからではなく、バックエンドサービスなどの安全な場所でこれを実行します。

• Temporary user authorization: Implicit Grant
  • このフローは、JavaScriptを使用するため、リソース所有者のブラウザで実行されるクライアントアプリケーション向けです。サーバー側のコードを使用する必要はありません。リクエストのレート制限は改善されていますが、リフレッシュトークンは提供されていません。このフローはRFC-6749で定義されています。

• Refreshable app authorization: Client Credentials Flow
  • このフローは、サーバー間認証で使用されます。エンドユーザー情報にアクセスしないエンドポイントのみにアクセスが可能です。

それぞれ、できること、できないことがあります。

今回は、Client CredentialsのパターンでWeb APIをコールしてみます。

Client Credentials Flowでアクセストークンを取得

まずは、Client IDとClient SecretをBase64でエンコードした値を取得します。

Macならばターミナル上で下記を実行します。

echo -n {client_id}:{Client_Secret} | base64

出力された値を「ZjM4ZjAw...WY0MzE=」とした場合、以下のようにリクエストを実行します。

curl -X "POST" -H "Authorization: Basic ZjM4ZjAw...WY0MzE=" \
-d grant_type=client_credentials https://accounts.spotify.com/api/token

以下のような結果が返ってくるので、アクセストークンを控えておきます。

{
  "access_token": "NgCXRKc...MzYjw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": ""
}

試しに以下のようにAPIをコールしてみると・・・

curl -H "Authorization: Bearer NgCXRKc...MzYjw"  \
GET https://api.spotify.com/v1/artists/1O8CSXsPwEqxcoBE360PPO

見事に結果が返ってきました！

{
  "external_urls": {
    "spotify": "https://open.spotify.com/artist/1O8CSXsPwEqxcoBE360PPO"
  },
  "followers": {
    "href": null,
    "total": 179434
  },
  "genres": [
    "finnish metal",
    "gothic metal",
    "hard rock",
    "melodic death metal",
    "metal",
    "neo classical metal",
    "power metal",
    "progressive metal",
    "speed metal"
  ],
  "href": "https://api.spotify.com/v1/artists/1O8CSXsPwEqxcoBE360PPO",
  "id": "1O8CSXsPwEqxcoBE360PPO",
  "images": [
    {
      "height": 768,
      "url": "https://i.scdn.co/image/7cb6d4e48dac26e74eba682212b3b3ecd4836d23",
      "width": 512
    },
    {
      "height": 300,
      "url": "https://i.scdn.co/image/e63f29b1a8cde872666bb0c3b702280a3bd45ff8",
      "width": 200
    },
    {
      "height": 96,
      "url": "https://i.scdn.co/image/d4a5047c0c96ab65ea3fbe539cd19779d753bcf6",
      "width": 64
    }
  ],
  "name": "Stratovarius",
  "popularity": 59,
  "type": "artist",
  "uri": "spotify:artist:1O8CSXsPwEqxcoBE360PPO"
}

おわりに

私が担当しておりますprismatixもそうですが、Web APIで様々なシステムやサービスと組み合わせることができるのは面白いことです。 今後も面白そうなサービスを見つけていきたいと思います。

参考情報

• Web API
• Web API Tutorial
• Authorization Guide
• Web API Reference