Meet Apple Music API and MusicKit [WWDC 2022]

WWDC에서 소개한 MusicKit 관련 영상에 대한 글을 작성해보겠습니다.

---

Apple Music API 사용에 관련된 기본 사항을 중심으로 MusicKit에 대해 알아보겠습니다.

• MusicKit 클라이언트 프레임워크에 대한 개요 및 Apple Music API 웹 서비스와 통합하는 방법
• 개발자로서 액세스 권한을 얻는 방법과 Apple Music API 사용에 관한 구체적인 정보
• 콘텐츠 및 리소스 요청
• 대규모 리소스 컬렉션 작업 시 제한 및 페이지네이션 사용하기
• 검색 엔드포인트를 활용하여 카탈로그에서 콘텐츠 찾는 방법
• Apple Music 구독자가 사용할 수 있는 몇 가지 개인화된 기능과 앱에서 이러한 기능에 대한 액세스를 제공하는 방법

위와 같은 순서로 진행하겠습니다.

---

MusicKit overview

MusicKit 및 Apple Music API에 대한 간략한 소개부터 시작하겠습니다.

MusicKit은 2017년 WWDC에서 처음 발표되었고, 그 이후로 Apple Music과 더 쉽게 통합할 수 있도록 개선되었으며 추가 기능에 대한 지원이 계속 추가되고 있습니다

• MusicKit은 클라이언트 프레임워크와 Apple Music API의 조합입니다.
• 카탈로그를 검색하고 인기 차트를 탐색하는 기능을 사용하여 Apple Music에서 콘텐츠를 검색하고 가져올 수 있습니다.
• 사용자의 동의하에 MusicKit 및 Apple Music API를 사용하여 구독자를 인증하여 사용 가능한 콘텐츠를 재생할 수 있습니다.
• 음악 라이브러리, 추천, 최근 재생 기록을 비록한 개인화된 기능에 대한 액세스를 제공할수 있습니다.

• MusicKit 클라이언트 프레임워크는 구독자를 인증하고 장치에서 재생을 시작 및 제어하는데 필요한 API를 제공합니다.
• 클라이언트 프레임 워크는 Apple 플랫폼의 앱 Javascript를 사용하는 웹 응용 프로그램 및 사용 가능한 SDK를 사용하는 Android 응용 프로그램에 사용할 수 있습니다.

• Apple 플랫폼의 MusicKit에는 Apple Music을 앱에 통합하는 데 필요한 모든 것이 있습니다.

• 구독자는 앱 내에서 인증하거나 가입하여 재생을 시작 및 제어하고 기타 개인화된 기능에 액세스 할 수 있습니다.

• 사용 가능한 API는 리소스 및 페이지네이션에 필요한 기본 지원을 통해 Apple Music에서 콘텐츠를 검색하고 접근을 위한 호출을 가속화합니다.
  

• MusicKit on the Web을 사용하면 Javascript를 사용하여 Apple Music을 앱에 쉽게 가져올 수 있습니다.

• Apple Music 콘텐츠를 검색하고, 구독자가 로그인하여 개인화된 기능에 액세스하고 웹 사이트에서 직접 콘텐츠를 재생하도록 할 수 있습니다.

• Apple Music API에 대한 전체 액세스 권한을 제공하여 독특한 음악 경험을 만들 수 있습니다.

• MusicKit은 모든 기능을 갖춘 미디어 플레이어를 포함한 빌트인 웹 구성 요소 컬렉션을 제공합니다.

• 이러한 구성요소는 시작이 간편하며 사용자 환경에 맞게 유연하게 커스터 마이징 할 수 있습니다.

• Android용 MusicKit을 사용하면 Apple Music을 Android 애플리케이션에 통합할 수 잇습니다.
• Apple Music 구독자 인증, 콘텐츠 재생과 제어, Apple Music API에 대한 전체 액세스 지원을 통해 풍부한 음악 경험을 구축할 수 있습니다.

• Apple Music API는 검색 기능 및 Apple Music 카탈로그 콘텐츠에 필요한 액세슬르 제공하는 일반적인 JSON 웹 서비스 입니다.
• 인증된 가입자는 음악 라이브러리, 추천 및 최근 재생 기록을 포함한 개인화된 기능에 액세스 할 수 있습니다.

---

Getting access

이제 액세스 방법에 대해 알아보겠습니다.

• Apple Music API에 요청하려면 개발자 토큰이 필요합니다.
• Apple 플랫폼의 애플리케이션의 경우 앱에 MusicKit 서비스를 활성화하여 자동 토큰 관리를 활용할 수 잇습니다.

MuscKit 서비스는 아래 사진에 보이듯 Apple 개발자 포털 앱 ID 섹션에서 찾을 수 있습니다.

• 다른 플랫폼의 애플리케이션의 경우 Apple 개발자 포털에서 MusicKit 개발자로 등록하여 개발자 토큰을 얻을 수 있습니다.
• 개인 키를 요청하고 다운로드 할 수 있습니다.
• JSON 웹 토큰을 생성한 후 다운로드한 개인 키로 서명(보안 인증)해야 합니다.

• JSON 웹 토큰은 두 부분으로 나뉘는데, 첫 번째 부분은 필수 헤더로 ES256이어야 하는 서명 알고리즘 alg와 개인 키 다운로드의 일부로 포함된 키 식별자 kid를 포함합니다.
• 토큰의 두 번째 부분은 클레임으로 Apple Music API에는 세 가지 필수 클레임이 있습니다.
• 발급자 ID iss는 Apple 개발자 포털의 멤버십 섹션에서 찾을 수 있는 팀 ID입니다.
• 발급 시간을 표시하는 iat는 Epoch 이후 경과 시간을 초단위로 표시합니다.
• 그리고 만료 시간을 나타내는 exp는 발행된 시간과 동일한 시간 형식입니다 .
• 토큰은 발행일로부터 최대 6개월까지 만료되도록 생성할 수 있습니다.
• 웹 애플리케이션의 경우 웹사이트에만 유효한 토큰을 발급하는 출처 클레임(origin)을 제공하는 것이 좋습니다.

• Apple Music API에 대한 모든 요청은 인증 헤더에 유효하고 서명된 토큰을 제공해야 합니다.
• Apple 플랫폼의 응용 프로그램에 대해 MusicKit 서비스를 활성화하면 이 작업이 자동으로 수행됩니다.
• 웹용 MusicKit은 Apple Music API에 요청하기 위해 생성한 토큰으로 구성해야 합니다.
• JSON 웹 토큰 생성에 대한 자세한 내용은 Apple Music API 설명서에서 찾을 수 있습니다

---

Requesting resources

이제 Apple Music API를 사용하여 리소스를 요청하는 방법을 알아 보겠습니다.

• 리소스는 아티스트, 앨범, 노래, 재생 목록 등과 같은 Apple Music 콘텐츠를 모델링합니다.
• 각각에 해당되는 유형이 있습니다.
• 리소스는 검색과 같은 검색 기능이나 식별자를 사용하여 Apple Music API 엔드 포인트에서 가져올 수 있습니다.

다음은 식별자를 사용하여 API에서 재생 목록 리소스를 가져오기 위한 Request URL의 예시입니다.

• Apple Music API는 api.music.apple.com에서 호스팅됩니다.
• URL의 경로는 RESTful 패턴을 사용하며 리소스 또는 기능의 위치를 나타냅니다.
• 위치의 첫 번째 요소 v1는 현재 버전 1인 API 버전입니다.
• 버전은 리소스 및 새로운 기능에 대한 개선 사항이 제공되는 경우에도 기존 호출과의 역호환성을 유지합니다
• Apple Music 카탈로그 내 요청의 경우 위치의 다음 섹션은 가져올 특정 카탈로그를 나타냅니다(catalog/us).
• 콘텐츠는 지역에 따라 다를 수 있으며 이를 스토어프론트라고 합니다.
• 이 예에서는 두 글자로 된 국가 코드 us로 표시된 미국 매장의 카탈로그에서 재생 목록을 가져옵니다.
• 이 위치의 마지막 부분은 playlists 유형 다음에 해당 식별자로 표시되는 리소스의 ID입니다(playlists/p1.2b0e6e332fdf4).
• Apple Music은 많은 지역에서 사용할 수 있으므로 선택적 언어 태그 쿼리 매개변수 L을 사용하여 현지화 지원이 가능합니다.
• 여기서는 영어를 지원하는 en-US라는 언어 태그를 지정합니다
• 언어 태그를 지정하지 않으면, 스토어프론트의 기본 현지화가 됩니다.
• Apple Music을 사용할 수 있는 매장 및 지원되는 현지화는 스토어프론트 참조 엔드 포인트에 액세스하여 찾을 수 있습니다.
• 자세한 내용은 Apple Music API 설명서에서 찾을 수 있습니다

다음은 재생 목록에 대한 GET 요청을 만드는 방법입니다.

• 리소스 컬렉션 응답을 반환하면 재생 목록 리소스와 함께 data 어레이를 받아옵니다.
• 리소스 개체는 id 값 및 type으로 콘텐츠의 ID를 나타냅니다. id와 type의 조합은 리소스의 고유한 ID를 나타냅니다.
• href 값은 리소스를 가져올 수 있는 API의 위치를 나타냅니다. 이 경우 위치는 우리가 요청한 경로와 동일합니다.
• 콘텐츠에 대한 메타데이터 값은 리소스의 attributes 맵에서 찾을 수 있습니다.
• 이 재생 목록 curator 및 tracks와 같은 다른 리소스와의 직접 연결은 relationships 맵에서 찾을 수 있습니다.

다음으로 재생 목록에 대한 메타데이터 값이 포함된 속성 맵을 자세히 살펴보겠습니다.

• 재생 목록의 이름(name), 큐레이터 이름(curatorName) 및 설명(description) 속성을 사용하는 오른쪽 위젯에서 이러한 속성 중 일부를 사용하는 예를 살펴보겠습니다.
• playParams는 구독자가 콘텐츠를 스트리밍할 수 있는 시기를 나타내는 많은 리소스 유형의 공통 속성입니다.
• playParams가 없는 콘텐츠는 재생할 수 없으므로 재생 제어의 활성화 여부를 결정하는 데 사용할 수 있습니다.
• 아트워크는 이미지를 로드할 수 있는 URL과 함께 이미지의 최대 너비 및 높이 값을 포함하는 많은 리소스 유형에 대한 또 다른 공통 속성입니다.

Apple에서 개발자 피드백은에서 가장 많이 요청된 기능 중 추가된 것을 알려드리겠습니다.

• 이제 Apple Music API에서 아티스트 아트워크를 사용할 수 있습니다.
• 모든 신규 및 기존 앱은 아티스트 리소스에 추가된 아트워크 속성을 찾아 이미지에 대한 지원을 추가할 수 있습니다.
• 아티스트 아트워크는 다른 콘텐츠 유형의 아트워크와 동일한 방식으로 로드할 수 있습니다

다음은 조금 전에 봤던 재생 목록에 대한 아트워크 URL의 축약된 예입니다

• 아트워크 URL에는 파란색으로 강조 표시된 w 너비 및 h 높이 토큰이 포함됩니다.
• 이 URL을 사용하여 아트워크를 로드하려면 이 토큰을 원하는 디스플레이 해상도로 바꿔야 합니다.
• 재생 목록 아트워크는 정사각형이므로 너비와 높이 모두에 동일한 해상도를 사용합니다.

다음은 400 x 400, 300 x 300, 200 x 200의 해상도를 요청하는 예입니다.

• w, h에 원하는 값을 넣으면 됩니다.
• 이미지는 각 해상도에서 표시할 수 있는 크기이며 더 작은 이미지의 경우 파일 크기가 줄어듭니다.
  

• 모든 리소스 유형에는 해당 리소스에 대한 공통 또는 기본 메타데이터를 나타내는 기본 속성 집합이 있습니다.
• 일부 리소스에는 "확장된 속성"이라고 하는 가져올 수 있는 추가 속성이 있습니다.
• 이러한 확장 속성은 확장 쿼리 매개변수를 사용하여 요청할 수 있습니다.
• 예를 들어 Apple Music 재생 목록의 트랙은 노래이거나 뮤직 비디오입니다. 재생 목록에 포함된 트랙 유형을 알고 싶다면 trackTypes 확장 속성을 요청할 수 있습니다

확장 속성은 기본 속성과 함께 리소스의 속성 맵에 나타납니다.

재생 목록의 트랙이 노래가 아닌 뮤직 비디오인 경우 재생 버튼을 사용자 지정하여 시청자에게 알릴 수 있습니다. (버튼 비교)

이제 relationships을 살펴보면 이 재생 목록에서 다른 리소스와의 몇 가지 직접 연결이 표시됩니다.

• 많은 리소스에는 일부 콘텐츠를 직접 요청할 때 반환되는 자동 관계가 있습니다. 재생 목록의 자동 관계는 큐레이터와 트랙입니다.
• 관계 이름은 이 재생 목록의 curator와 같이 연결이 무엇인지 나타내기 위해 지정됩니다.
• 관계를 직접 가져올 수 있는 href 위치와 관련 리소스 컬렉션에 대한 data 어레이가 있습니다.
• 재생 목록의 경우 큐레이터 관계가 자동으로 관련되어 관련 리소스의 id만 표시됩니다.
• 이를 통해 해당 id 또는 href를 사용하여 이 리소스에 쉽게 연결할 수 있습니다.
• 재생 목록에는 이미 큐레이터의 이름이 속성으로 포함되어 있으므로 관련 큐레이터 리소스에 대한 다른 메타데이터를 포함할 필요가 없습니다.
• 리소스의 ID를 사용하여 큐레이터 이름을 링크로 만들어 사람들이 원하는 경우 큐레이터를 탐색하여 추가 콘텐츠를 찾을 수 있습니다.

• 아트워크에 재생 목록과 큐레이터에 대한 추가 정보를 표시하려면 큐레이터의 메타데이터를 가져와야 합니다.
• include 매개변수를 사용하여 관련 리소스 메타데이터의 원하는 관계를 지정합니다.
• 일부 리소스 유형에는 기본적으로 추가관계가 포함되어 있고 이 매개변수로도 요청할 수 있습니다.
• 관계를 포함하면 응답 크기가 증가하고 앱 속도에 부정적인 영향을 줄 수 있습니다.
• 관련 리소스가 원하는 많은 수의 유용한 값은 원래 리소스의 속성으로 직접 찾을 수 있습니다.
• 최상의 성능을 위해 응답에 필요한 관계와 메타데이터만 포함하는 것이 좋습니다.

예제 재생 목록에 대한 관계를 다시 살펴보겠습니다.

• 재생 목록에 대한 트랙이 자동으로 포함됩니다. 이는 관련 트랙 리소스에 대한 속성 메타데이터가 웅답에 표시된다는 것을 뜻합니다.
• 관련 트랙의 속성은 오른쪽 위젯에 표시된 아트워크 및 기타 메타데이터를 사용하여 재생 목록의 트랙 목록을 표시하는 데 사용할 수 있습니다.

---

Limits and pagination

이번에는 많은 리소스와의 관계를 처리하는 방법에 대해 알아보겠습니다.

• 관계에 대한 관련 리소스는 데이터 배열에 나타납니다.
• 관련 리소스의 수가 적으면 모든 리소스가 단일 응답으로 나타납니다.
• 단일 응답에 나타나는 것보다 더 많은 관련 리소스가 있는 관계는 페이지라고 하는 여러 부분에서 가져와야 합니다.

큰 재생 목록의 트랙 관계를 예로 들어 보겠습니다.

• 재생 목록의 처음 100개 트랙만 기본적으로 포함됩니다.
• 재생 목록에 100개 이상의 트랙이 있는 경우 후속 페이지에서 추가 트랙을 가져와야 합니다

다음은 100개 이상의 트랙이 있는 재생 목록에 대한 응답의 예입니다

• 트랙 관계에 대한 href 및 리소스 컬렉션 데이터는 앞에서 본 것처럼 응답에 나타납니다.
• 이 재생 목록에는 응답에 포함된 것보다 더 많은 트랙이 있으므로 다음 위치는 데이터의 형제로 나타납니다.
• 다음 위치(next)는 컬렉션의 나머지 리소스를 가져올 수 있는 위치를 나타냅니다

• 다음 위치를 가져오면 직접 관계를 가져오고 제공된 오프셋(offset)에서 시작하여 관계의 리소스 컬렉션 데이터를 반환합니다.
• 관계에 대한 기본 제한은 각 페이지에 적용됩니다.
• 제한(limit) 매개변수를 제공하여 고유한 페이지 크기를 선택할 수 있습니다.
• 페이지 크기 제한은 1과 특정 관계가 지정한 최대 페이지 크기 사이일 수 있으며 관계에 대한 리소스 컬렉션에 페이지에서 반환된 리소스 외에 추가 리소스가 포함된 경우 다음 위치(next)는 계속해서 데이터의 형제로 나타납니다.
• 리소스 컬렉션이 소진되면 다음 위치가 표시되지 않습니다.
• 다음 위치는 요청에 대해 선택한 페이지 크기를 반영하지 않습니다.
• 기본값과 다른 페이지 크기를 사용하려는 경우 각 요청에 제한 매개변수를 제공해야 합니다.
• 리소스 컬렉션을 통해 페이지에 대한 응답에서 항상 다음 위치를 사용합니다.
• 자체 오프셋을 계산하려고 하면 잘못된 위치 또는 중복 결과 문제가 발생할 수 있습니다.

---

Search the catalog

다음 섹션에서는 Apple Music API를 사용하여 Apple Music 카탈로그에서 콘텐츠를 검색하는 방법을 알아보겠습니다.

• Apple Music API는 검색어를 사용하여 카탈로그에서 콘텐츠를 찾는 기능을 제공합니다.

• 검색 요청은 위치로 /search를 사용하고 매개변수로 검색어를 사용하는 카탈로그 리소스 요청과 유사합니다.

• types 매개변수를 사용하여 관심 있는 콘텐츠 유형과 limit를 사용하면 각 유형에 포함할 최대 결과 수를 지정할 수 있습니다.

• 요청한 제한을 초과하여 더 많은 결과가 발견되면 페이지네이션을 사용하여 검색을 계속할 수 있습니다

  다음은 pop이라는 용어가 포함된 앨범 및 노래 검색에 대한 응답입니다.

• 검색 엔드포인트는 일치하는 콘텐츠가 있는 요청된 각 유형에 대한 그룹을 포함하는 결과 개체와 함께 응답을 반환합니다.
• 이 요청의 경우 앨범(albums) 및 노래(songs)에 대한 일치 항목이 발견되었습니다.
• 응답에는 관련성을 기반으로 하는 결과 그룹에 대한 권장 순서(order)가 포함된 메타(meta) 개체도 포함됩니다.
• 이는 한 번에 여러 콘텐츠 유형을 처리하는 검색 환경을 구축하는 경우에 유용할 수 있습니다.
• 각 결과 그룹에는 결과를 가져온 href와 검색어에 대한 관련 유형과 일치하는 리소스를 포함하는 리소스 컬렉션 data 배열이 있습니다.
• 결과 그룹에 대해 더 많은 일치 항목을 사용할 수 있는 경우 그룹에는 추가 일치 항목을 가져올 수 있는 next가 포함됩니다.

다음 위치를 요청하면 offset에서 시작하여 선택한 유형에 대해 더 많은 결과가 반환됩니다.

---

Personalized features

마지막 섹션에서는 Apple Music API의 개인화된 기능에 액세스하는 방법에 대해 알아보겠습니다.

• Apple Music API 및 MusicKit은 특정 사용자에게 개인화된 기능에 대한 액세스를 제공합니다.
• 이러한 기능을 통해 가입자가 즐기는 콘텐츠를 추가하고 새로운 재생 목록을 생성하는 기능을 포함하여 Apple Music 보관함에서 콘텐츠를 보고 검색할 수 있도록 지원을 추가할 수 있습니다.
• 개인의 음악 취향에 따라 맞춤 추천이 표시될 수 있습니다 또한 사람들이 최근에 들었던 음악을 다시 찾아 중단한 부분부터 다시 시작하거나 완전히 새로운 경험을 제공할 수 있습니다.

• Apple Music을 구독 중인 사용자는 개인화된 기능을 사용할 수 있습니다.
• 이러한 기능을 지원하려면 먼저 MusicKit을 사용하여 앱으로 사용자를 인증하고 음악 데이터에 액세스할 수 있는 권한을 요청해야 합니다.

• 권한이 부여되면 음악 사용자 토큰을 사용할 수 있습니다.
• 이 토큰은 music-user-token 헤더의 Apple Music API 요청에 추가되며 개인화된 데이터에 대한 액세스를 인증하는 데 사용됩니다.

• 음악 사용자 토큰은 앱과 사용자가 인증한 기기에 따라 다릅니다.
• 이 토큰은 한 번에 단일 장치에 권한이 부여되므로 장치 간에 공유해서는 안 됩니다.
• 토큰은 개인의 구독이나 비밀번호 변경에 따라 또는 앱에 대한 액세스 권한을 취소하는 경우 무효화될 수 있습니다 시간이 지나면 만료될 수도 있습니다.
• 다시 로그인하고 앱에 대한 권한을 부여하라는 메시지를 표시하여 인증을 새로 고칠 수 있습니다.
• 이 토큰은 Apple 플랫폼의 MusicKit 및 웹의 MusicKit에서 자동으로 관리됩니다. 자세한 내용은 사용 중인 프레임워크에 대한 설명서를 참조하세요.

---

참고
https://developer.apple.com/videos/play/wwdc2022/10148/