[iOS 11] Apple Music APIにアクセスするために必要な作業について #WWDC17

はじめに

こんばんは。モバイルアプリサービス部の平屋です。

本記事では、Apple Music APIにアクセスするために必要な作業を紹介します。

Apple Music APIは、Apple Musicに関する各種情報の取得などを行うためのWeb APIです。WWDC 17で紹介されたMusicKitを構成する要素の1つでもあります。

[iOS 11] Apple Musicとの連携を行うための「MusicKit」について #WWDC17

本記事は Apple からベータ版として公開されているドキュメントを情報源としています。 そのため、正式版と異なる情報になる可能性があります。ご留意の上、お読みください。

検証環境

• Mac
  • macOS Sierra 10.12.5
  • Xcode Version 9.0 beta 2 (9M137d)
  • Python 2.7.13
  • pip 9.0.1
• iPhone 7
  • iOS 11.0 (15A5304i)

目次

• Tokenについて
• Music IDを作成する
• MusicKit private keyを作成する
• Developer Tokenを作成する
• Music User Tokenを作成する
• リクエストを実行する

Tokenについて

Apple Music APIにアクセスするために必要なのは、以下の2種類のTokenを作成することです。

• Developer Token
  • アプリの開発者が以下を満たすことを証明するために存在する
    • 信頼された開発者であること
    • Apple Developer Programのメンバーであること
• Music User Token
  • アプリのユーザーが以下を満たすことを証明するために存在する
    • Apple Musicのメンバーであること

Apple Music Catalogに関するリクエストの場合は、Developer Tokenのみ必要です。

• 例
  • アルバム取得
  • 曲取得
  • アーティスト取得

ユーザー固有のデータに関するリクエストの場合は、Developer TokenとMusic User Tokenの両方が必要です。

• 例
  • 最近再生したアルバムの取得
  • レコメンドの取得
  • レーティングの編集

次の「Music IDを作成する」から、Tokenを作成する作業に入ります。

Music IDを作成する

アプリを識別するための「Music ID」を作成します。

• developer.apple.com > Account > Certificates, Identifiers & Profiles を開く
• Identifiers > Music IDsを開き、「+」ボタンをクリックする
• Descriptionにアプリ名を、IdentifierにMusic IDを入力し、「Continue」をクリックする
  • Descriptionに入力した値は、Apple Musicへのリクエストを行う際にユーザーに対して表示される
    • 例: AppleMusicAPISample
  • Identifierに入力するMusic IDは、文字列「music」で始まる逆ドメイン形式の文字列にする
    • 例: music.com.example
• 入力内容を確認し、「Register」をクリックする
• 「Done」をクリックする

MusicKit private keyを作成する

Music IDに対応する「MusicKit private key」を作成します。

• developer.apple.com > Account > Certificates, Identifiers & Profiles を開く
• Keys > Allを開き、「+」ボタンをクリックする
• private keyに関する情報の入力・選択を行う
  • Key Descriptionにprivate keyの名前を入力する
  • Key Servicesの「MusicKit」にチェックを入れ、「Configure」をクリックする
    • private keyに紐付けるMusic ID(先ほど作成したID)を選択し、「Configure」をクリックする
• 情報の入力・選択が完了したら「Configure」をクリックする
• 内容を確認し、「Confirm」をクリックする
• 「Download」をクリックする
  • 拡張子が「.p8」のテキストファイルがダウンロードされる
  • このファイルには秘密鍵が含まれているので、安全な場所で保管するようにする

Key IDを確認する

「Key ID」の値を確認します。

Key IDは、MusicKit private keyに割り当てられるIDです。「Developer Token」を作成する際に使用しますので、このタイミングでKey IDを確認しておきましょう。

• developer.apple.com > Account > Certificates, Identifiers & Profiles を開く
• Keys > Allを開く
• 対象のMusicKit private keyをクリック
  • Key IDを確認できる

Developer Tokenを作成する

「Developer Token」を作成します。

このTokenは以下の情報から作成します。

• MusicKit private key
• Key ID
• Apple DeveloperアカウントのTeam ID

また、Developer Tokenは「JWT(JSON Web Token)」という仕様に準拠している必要があります。

JWTに準拠したTokenはこちらで紹介されている各種ライブラリを使用して作成できます。Apple Music APIはES256形式で作成されたTokenのみをサポートするので、ES256形式に対応しているライブラリを使用しましょう。

「apple-music-token-generator」を使用してDeveloper Tokenを作成する

今回はPythonで書かれたapple-music-token-generatorというツールを使用してDeveloper Tokenを作成してみました。

このツールはjpadilla/pyjwtを使用してJWTを作成します。

pyjwtとcryptographyをインストールする

必要に応じて、pipをインストールします

• get-pip.pyをhttps://pip.pypa.io/en/stable/installing/からダウンロードする
• $ sudo python get-pip.pyを実行する

pyjwtとcryptographyをインストールします

• $ sudo pip install pyjwtを実行する
• $ sudo pip install cryptographyを実行する

music_token.pyを編集する

apple-music-token-generatorをダウンロードして、music_token.pyを任意のエディタで開きます。

secretの値を設定

secretの値を自分のMusicKit private keyの値に置き換えます。値は「MusicKit private keyを作成する」でダウンロードした「*.p8」ファイルを任意のエディタで開くと確認できます。

secret = """-----BEGIN PRIVATE KEY-----
REPLACE-THIS-WITH-YOUR-OWN-PRIVATE-KEY
-----END PRIVATE KEY-----"""

keyIdとteamIdの値を設定

keyIdとteamIdも自分のものに置き換えます。keyIdには「Key IDを確認する」で確認した値を、teamIdにはApple DeveloperアカウントのTeamのIDを指定します。

keyId = "9876543210"
teamId = "0123456789"

time_expiredの値を設定

time_expiredには6ヶ月以内の有効期限を指定します。

# 24時間を指定する場合
time_expired = datetime.datetime.now() + datetime.timedelta(hours=24)

music_token.pyを実行

編集が終わったら、music_token.pyを実行します。

200文字くらいの長さのトークンと、curlのサンプルが出力されます。

$ python music_token.py
----TOKEN----
[developer token]
----CURL----
curl -v -H 'Authorization: Bearer [developer token]' "https://api.music.apple.com/v1/catalog/us/artists/36954"

Developer Tokenの扱いについて

WWDC 17のセッションIntroducing MusicKitによると、Developer Tokenは以下のように扱うべきだそうです。

• Security
  • Protect your MusicKit private key
  • Recommend dynamically generating developer tokens

Music User Tokenを作成する

Music User Tokenは、StoreKitフレームワークのSKCloudServiceControllerを使って取得できます。

Token取得を実行する前に、以下の3つの作業を行う必要があります。

• Info.listにNSAppleMusicUsageDescriptionキーと値を追加する
• ミュージックライブラリへのアクセス許可を要求する
• Apple Musicのメンバーであることを確認する

Info.listにNSAppleMusicUsageDescriptionキーと値を追加する

...

<plist version="1.0">
<dict>
    <key>NSAppleMusicUsageDescription</key>
    <string>ミュージックライブラリへのアクセスの目的をここに入れる</string>

    ...
</dict>
</plist>

ミュージックライブラリへのアクセス許可をリクエストする

SKCloudServiceControllerのrequestAuthorization(_:)メソッドを使用して許可をリクエストします。

SKCloudServiceController.requestAuthorization { status in
    guard status == .authorized else { return }

    // 後続の処理 ...
}

Apple Musicのメンバーであることを確認する

SKCloudServiceControllerのrequestCapabilities(completionHandler:)メソッドを使用して、ミュージックライブラリに関するCapabilitiesをリクエストします。

capabilitiesに.musicCatalogPlaybackが含まれることを確認します。

self.cloudServiceController.requestCapabilities { capabilities, error in
    guard capabilities.contains(.musicCatalogPlayback) else { return }

    // 後続の処理 ...
}

Music User Tokenをリクエストする

SKCloudServiceControllerのrequestUserToken(forDeveloperToken:completionHandler:)メソッドを使用してMusic User Tokenをリクエストします。

1つめの引数には「Developer Tokenを作成する」で作成したTokenを指定します。

let developerToken = "[Developer Token]"

self.cloudServiceController.requestUserToken(forDeveloperToken: developerToken, completionHandler: { token, error in
    guard let token = token else { return }

    print("Music User Token:", token)
})

「Apple Musicのメンバーに加入済みのApple ID」でログインしているiOS端末で上記実装を実行すると、Music User Tokenを取得できます。

Music User Token: [Music User Token]

Music User Tokenの扱いについて

WWDC 17のセッションIntroducing MusicKitによると、Music User Tokenは以下のように扱うべきだそうです。

• You should cache the token, but don’t transfer it across devices
• Refetch if you get a “Forbidden” status code (403) from Apple Music API

リクエストを実行する

ここまでの作業でDeveloper TokenとMusic User Tokenを作成できたかと思います。

APIへのリクエストを実行してみましょう。

Apple Music Catalogに関するリクエストの場合

リクエストヘッダにDeveloper Tokenを入れます。

例えば「チャート情報」は以下の実装で取得できます。

func fetchCharts() {
    let developerToken = "[Developer Token]"

    let chartsURL = URL(string: "https://api.music.apple.com/v1/catalog/jp/charts?types=albums")!
    var request = URLRequest(url: chartsURL)

    // Developer Tokenをヘッダに入れる
    request.setValue("Bearer \(developerToken)",
        forHTTPHeaderField: "Authorization")

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // ...
    }
    task.resume()
}

ユーザー固有のデータに関するリクエストの場合

リクエストヘッダにDeveloper TokenとMusic User Tokenの両方を入れます。

例えば「ユーザーが最近再生したアイテム」は以下の実装で取得できます。

func fetchRecentlyPlayed() {
    let developerToken = "[Developer Token]"
    let musicUserToken = "[Music User Token]"

    let recentlyPlayedURL = URL(string: "https://api.music.apple.com/v1/me/recent/played")!
    var request = URLRequest(url: recentlyPlayedURL)

    // Developer Tokenをヘッダに入れる
    request.setValue("Bearer \(developerToken)",
        forHTTPHeaderField: "Authorization")

    // Music User Tokenをヘッダに入れる
    request.setValue(musicUserToken,
                     forHTTPHeaderField: "Music-User-Token")

    let task = URLSession.shared.dataTask(with: request) { data, response, error in
        // ...
    }
    task.resume()
}

さいごに

本記事では、Apple Music API使用時に必要なTokenの作成方法を紹介しました。

これからApple Music APIを触ってみようと思っている方の参考になれば幸いです。

参考資料

• Apple Music API Reference
• MusicKit
• StoreKit

その他

• JWTによるJSONに対する電子署名と、そのユースケース ｜ Developers.IO
• JWT(JSON Web Token)を使った認証を試みる | 69log
• JWTについて簡単にまとめてみた - hiyosi's blog