Apple Music APIとMusicKitの紹介

WWDCへようこそ Apple Music Development teamのJustinです 今日はApple Music APIの 基本に焦点を当て MusicKitについて お話しします ここではMusicKitクライアント フレームワークについてと Apple Music API web サービスとの統合について デベロッパとしての アクセス方法と Apple Music APIの 詳細について そして コンテンツとリソースの リクエストや limitsとページネーションでの 大量のリソースの処理や searchエンドポイントでの 検索についてお話しします 最後にサブスクリプション登録者に 用意されている個別機能と それらの提供方法について お話しします

まずはMusicKitとApple Music APIについてです MusicKitは2017年に WWDCで登場しました それ以来 Apple Musicとの統合を さらに簡単になるよう 改善を加え さらなる機能も 追加されました MusicKitは クライアントフレームワークと Apple Music APIの 組み合わせです これらが組み合わさって AppにApple Musicの機能が 追加できます カタログ検索や チャートのブラウズ機能で Apple Musicから アーティストやアルバム プレイリストなどの コンテンツを呼び込めます ユーザーの許可を得て サブスクリプションを認証し ライブラリやおすすめ 再生履歴などの 個別の機能にアクセスし App内でコンテンツを 再生できます MusicKitクライアント フレームワークは 認証およびデバイスにおける 再生コントロールに必要な APIを提供します クライアントフレームワークは Appleのプラットフォームや Javascriptを使用した Web App SDKを使用したAndroid Appで利用できます

Appleプラットフォームの MusicKitで簡単に Apple MusicをAppに 統合できます App内でサブスクリプション の認証および登録ができ 再生やさまざまな リソースとページネーションの ネイティブサポートで コンテンツの発見と アクセスが加速します 後にお話しする Apple Music APIへの アクセスなどに関しては Appleプラットフォームの MusicKitで 自動的に処理されます Appleプラットフォームの デベロッパは 「Meet MusicKit for Swift」で APIについて学び 「Explore more content with MusicKit」で 機能について学ぶことができます

MusicKit on the Webを使うことで JavascriptのAppに Apple Musicを 簡単に取り込めます Apple Musicのコンテンツを発見でき サインインして個別の機能にアクセスし Webで直接 コンテンツを再生できます Apple Music APIへの フルアクセスで ユニークな音楽体験を 創造できます MusicKitではフル機能の Media Playerなど ビルトインの ウェブ要素を提供し 体験をカスタマイズできる 柔軟性が得られます

MusicKit for Androidでは Apple Musicを Android Appに取り込みます Apple Music登録者の サブスクリプションの認証や コンテンツの再生 Apple Music APIへの フルアクセスなど リッチな体験を創造できます

Apple Music APIは 発見機能やコンテンツに アクセスを提供する JSON web サービスです 認証済みの サブスクリプション登録者は ライブラリやおすすめ 再生履歴など 個別の機能に アクセスできます 次に アクセスの方法です Apple Music APIは Developerトークンが必要です Appleプラットフォーム向けの Appの場合 MusicKitを有効にすることで トークンの自動管理 を利用できます このサービスは Apple Developerポータルの 「App ID」セクションにあります

他のプラットフォーム向けの Appの場合 MusicKitデベロッパ として登録すれば Developerトークンを 得ることができ そこからプライベートキーを ダウンロードできます そしてJSON Webトークンを 作成し ダウンロードしたプライベートキーで 署名してください JSON Webトークンは ２部分あります まずはHeaders 署名アルゴリズム "alg": "ES256"と キーIDの "kid"が含まれ プライベートキーのダウンロード に含まれています ２つ目はClaimsです Apple Music APIは ３つのClaimを要します issuer IDの“iss”は Developerポータルの 「Membership」セクションにある Team IDです issued at timeの"iat"は Epochからの秒数を示し expiration timeの"exp"は issued timeと同じ 時間形式です トークンは発行から 最大６カ月まで 有効です Web Appの場合 origin claimで あなたのサイトのみ有効な トークンを発行することをお勧めします

Apple Music APIは authorization headerで 有効でサイン済みの トークンが必要です Appleプラットフォームで MusicKitサービスが有効であれば 自動的に処理されます Web上のMusicKitは 作成したトークンで設定し Apple Music APIに リクエストしてください JSON Webトークンに 関する詳細は Apple Music APIの ドキュメントをご覧ください 次はApple Music APIで リソースをリクエストします アーティストやアルバムなど コンテンツがリソースとして モデルとなります それぞれが異なるタイプであり Apple Music API エンドポイントから 検索やIDなどで 発見できます これはIDを使い プレイリストを引き出す リクエストURLの例です Apple Music APIのホストは api.music.apple.comです URLのパスは RESTfulパターンを使い その場所を示します 最初の要素は APIのバージョンで 現在はバーション１です 大きな変更があれば 新しいバージョンになります リソースや機能に 向上が加えられても 後方互換性が維持されます Apple Musicカタログ内の リクエストの場合 次のセクションが カタログの場所を示します Apple Musicは 世界的サービスですので 地域のストアフロントによって コンテンツが違います

ストアフロントと利用できる コンテンツに関する詳細は 以下のビデオをご覧ください この例ではアメリカの ストアフロントのカタログから プレイリストを呼び込みます アメリカは“us”で示されます 最後のセクションは リソースのIDです "playlists"の後に identifierが続きます

Apple Musicは多くの地域で 利用できるので ローカライゼーションは language tag query parameterの"L"で可能です ここでは"en-US"で 英語を選んでいます スペイン語のコンテンツなら “es-MX”です 簡潔にするため この例では定義しませんので ストアフロントの デフォルトになります ストアフロントと サポートされている 言語などの詳細は ストアフロントのリファレンス エンドポイントにあります 詳細はAPIのドキュメントを ご覧ください

これはプレイリストの GETリクエストの例です プレイリストのリソースを含む "data”配列が返ってきます リソースオブジェクトが コンテンツのIDを示します idとtypeが リソースのIDを示します href valueはリソースは 引き出された場所を示します この例ではパスがリクエスト された場所と同じです メタデータはリソースの attributesにあります このプレイリストのキュレーターや トラックなどとの コネクションは relationshipsにあります

このattributesには プレイリストのメタデータが 含まれています 右にあるウィジェットで attributesを使う例を お見せします nameとcuratorName descriptionを使います playParamsは よくあるattributeで いつコンテンツが ストリーム可能かを示します playParamsなしでは 再生できないので 再生コントロールを可能にするか を決めるのに使われます artworkも よくあるattributeで イメージを引き出した URLに加え イメージの最大サイズを 含んでいます

Appleではデベロッパの意見を 大切にしています みなさまからの意見は APIやサービスの向上に役立ちます 今年 リクエストの 最も多かった機能を 追加します Apple Music APIでArtist artworkが 取得できるようになりました これにより シルエットは 過去のものとなりました artist resourcesの artwork attributeで これらのイメージを 追加することができます Artist artworkの取り込みは 他のコンテンツと同様です ここに先ほど見ていた プレイリストの artwork URLの例があります 横幅の"w"と縦幅の"h"が 青でハイライトされています このartworkを取り込むには これらのトークンを 希望の解像度に 設定してください playlist artworkは 正方形なので 縦横同じ数値です これは400x400の 解像度の例 300x300 そして200x200です イメージはディスプレイの サイズに応じて 小さければファイルサイズも 小さくなります

どのリソースもデフォルトの attributesがあり そのリソースの 基本メタデータを示します リソースによっては さらにattributesを取り込み 「extended attributes」と 呼ばれます そのリクエストにはextend query parameterを使います Apple Musicプレイリストの トラックは 歌かミュージックビデオです そのトラックの種類を 知りたいなら trackTypes extended attributeをリクエストし デフォルト属性と共に attributesに現れます プレイリストのトラックが ミュージックビデオなら 再生ボタンをカスタマイズして ユーザーに知らせることができます

relationshipsを 見てみると 他のリソースに 直接つながりがあります 多くのリソースは automatic relationshipsで コンテンツを直接リクエスト すると返ってきます プレイリストの場合 curatorとtracksです relationshipsの名前は そのコネクションを示し この場合 curatorです relationshipを直接読み込む href locationと 関連するリソースコレクションの データ配列があります プレイリストではcurator relationshipが自動的に紐づけられ 関連リソースの IDのみが存在することになります IDとhrefを使ってリソースを 簡単にリンクできるのです プレイリストにはcuratorが attributeとして含まれるため curator関連のメタデータは 必要ありません リソースIDを使って curator名をリンク化することができ ユーザーをcuratorに導いて 追加コンテンツをの発見を促せます プレイリストでcuratorの さらなる情報を見せたいなら curatorのメタデータを 取り込む必要があります includeパラメータで relationshipsを特定し 関連するメタデータを 取り込みます デフォルトで含まれていない さらなるrelationshipsも このパラメータで リクエストできます ただrelationshipsを増やすと 応答のサイズが大きくなり Appのスピードに 影響しかねません 希望する関連リソースの値は すでにattributesとして あるかもしれません 最高のパフォーマンスを保つため 必要なrelationshipsと メタデータのみ含むべきです リソースタイプと attributesの詳細は Apple Music APIドキュメントを ご覧ください extended attributesや relationshipsのうちviewsと呼ばれる special relationshipsに関しては 以下のビデオをご覧ください 再度 このプレイリストの relationshipsを見てみると プレイリストのtracksは 自動的に含まれ 関連するリソースの attribute metadataも 応答に現れます 右のウィジェットのように artworkやメタデータを使い トラックリストの表示に attributesを 使用することができます 先ほどトラックの カタログから リソースを取り込む例を お見せしました 今から大量のリソースの relationshipsの場合を お見せします relationshipの関連リソース はデータ配列に現れます 関連リソースの数が少ないと すべてが１つの応答に 現れます １つの応答により多くの 関連リソースがある場合は いくつにも分けられ pagesと呼ばれます

これは大きいプレイリストの tracks relationshipです デフォルトとして最初の 100トラックが含まれます playlistに 100トラック以上あれば 続くpagesにトラックを 取り込まねばなりません これが100トラック以上の 返答の例です 先ほど同様 hrefと resource collection dataが 応答に現れます このプレイリストには さらにトラックがあるため 次のロケーションが データの兄弟として現れます 次のロケーションに 残りのリソースを 取り込むことになります これがdirect relationship fetchとなり relationshipの collection dataを 引き続き取り込みます どのページにもデフォルトの 限度が適用されます limit parameterを設定し サイズを選んでください 限度は１から 資料で指定されている relationshipの 最大サイズまで 設定できます relationshipのcollectionが ページの限度より 多いリソースを含む場合 そのデータの兄弟として 次のロケーションが現れます そこですべてが収まれば 次は現れません ただし次のロケーションは ページサイズを反映しません デフォルト以外のサイズを 使用したい場合 それぞれlimit parameterを 設定してください そして常に応答からの 次のロケーションを 使用してください 自分で相殺を 計算しようとすると ロケーションの無効や 重複になりかねません 次にApple Music APIを使い Apple Musicカタログ内で どうコンテンツを検索するか お見せします Apple Music APIは 検索語を使ってカタログ内を 検索する機能があります /searchをロケーション 検索語をparameterとして catalog resource requestと 非常に似ています types parameterで検索する コンテンツのタイプを指定し limitを使って結果の上限を 設定できます 限度以上の結果が見つかると paginationを使って 検索が続行されます これは"pop"でアルバムと 曲を検索した結果です タイプごとに グループ分けされ 結果が戻ってきました アルバムと曲の両方で マッチがありました

また関連性に基づいて グループ分けされた meta objectも 含まれています これは同時に いくつものタイプを 検索できるようにするのに 理想的です いずれも結果を引き出した hrefがあり 検索語に関連性のある リソースを含んだ resource collection data arrayもあります 結果が限度を越えたならば 次のロケーションに 結果が続きます 設定された数値に基づき 検索結果が 次のロケーションに続きます 最後にApple Music APIで 個別情報に アクセスする方法に ついてです

Apple Music APIと MusicKitを通して 個別化された機能に アクセスできます サブスクライバーが ライブラリを閲覧や 検索することが できるようになり コンテンツを追加したり プレイリストを作成できます また個人の好みによる おすすめも表示できます また 最近聴いていた 音楽の続きを聴けるなど 新しい体験を提供できます

これらの機能は サブスクライバーにのみ 提供できます これにはMusicKitで Appを通して認証を行い music dataにアクセスする 許可を取らねばなりません 許可されるとMusic User トークンが得られます これはmusic-user-token headerでAPIに追加され 個別データへのアクセスの 認証となります

このトークンはユーザーの デバイスとAppのみ有効です デバイスごとの許可ですので デバイス間での トークンの共有はできません サブスクリプションや パスワードの変更 アクセス権の取り消しで トークンは無効になります また時間で無効にもなります サインインを促し アクセス権の許可を得て 再認証することもできます Appleプラットホームと WebのMusicKitでは これらは自動的に 処理されます フレームワークに 基づいた資料を ご参照ください 今日はMusicKitと Apple Music APIで Apple MusicをAppに 統合することについて クライアントフレームワークの プラットフォーム コンテンツへのアクセスと 検索方法について そして個別機能へのアクセス についてお話ししました Appleプラットフォームでの MusicKitの最新化については Explore more content with MusicKitをご覧ください 今年のWWDCを どうぞお楽しみください