Meet Apple Music API and MusicKit
System & Services 进阶 20m

认识 Apple Music API 和 MusicKit

Meet Apple Music API and MusicKit

2022年6月6日

在 Apple 官方观看视频

一句话判断

如果你想在自己的应用里集成 Apple Music 的搜索、播放和个人推荐功能，这场 Session 是完整的入门指南——覆盖 Apple 平台、Web 和 Android 三端。

这场 Session 讲了什么

Apple Music 开发团队的 Justin Rennell 全面介绍了 MusicKit 和 Apple Music API 的基础用法。MusicKit 是客户端框架和 Apple Music API 的组合，让开发者可以在自己的应用中集成 Apple Music 功能。

内容覆盖四个方面：MusicKit 的整体架构和各平台支持情况、开发者认证和 Token 管理、API 资源请求和分页处理、以及个性化功能（用户音乐库、推荐、最近播放）的接入方法。

MusicKit 支持三大平台：Apple 平台（原生 Swift/ObjC）、Web（JavaScript）和 Android（SDK），它们都通过统一的 Apple Music API JSON 服务进行数据交互。

值得深挖的点

三端统一的 API 设计。 Apple Music API 是一个 JSON Web 服务，三端客户端框架都围绕它构建。Apple 平台上 MusicKit 提供了原生资源类型和自动分页支持，Web 端提供了内置组件（包括完整的媒体播放器），Android 端也提供了完整的功能覆盖。

Developer Token 的获取方式。 Apple 平台可以通过启用 MusicKit 服务获得自动 Token 管理，不需要手动处理。Web 和 Android 端需要手动生成 JWT：用 ES256 算法签名，包含 iss（团队 ID）、iat（签发时间）和 exp（过期时间）三个必需声明。Token 最长有效期 6 个月。

分页和限制参数。 API 默认返回有限数量的结果。使用 limit 参数控制每页数量（不同端点有不同上限），使用响应中的 next URL 获取下一页。Apple 平台的 MusicKit 原生框架自动处理分页。

个性化功能需要用户授权。 获取用户音乐库、推荐和最近播放记录需要 Apple Music 订阅者的授权。在 Apple 平台上，MusicKit 处理认证流程；Web 和 Android 端需要通过 MusicKit SDK 提供的认证接口。

代码片段

import MusicKit

// Apple 平台：请求音乐授权
func requestMusicAccess() async {
    let status = await MusicAuthorization.request()
    switch status {
    case .authorized:
        // 获取用户授权，可以访问个性化功能
        await fetchPersonalRecommendations()
    default:
        // 处理未授权情况
        break
    }
}

// 搜索 Apple Music 目录
func searchCatalog(query: String) async throws {
    var request = MusicCatalogSearchRequest()
    request.searchTerm = query
    request.types = [Song.self, Album.self, Playlist.self]
    
    let response = try await request.response()
    for song in response.songs {
        print("歌曲: \(song.title) - \(song.artistName)")
    }
}

// 获取用户的最近播放记录
func fetchRecentlyPlayed() async throws {
    let request = MusicRecentlyPlayedContainerRequest()
    let response = try await request.response()
    for item in response.items {
        if let album = item as? Album {
            print("专辑: \(album.title)")
        }
    }
}
// Web 端：配置 MusicKit
MusicKit.configure({
  developerToken: 'your-jwt-token',
  app: {
    name: '我的音乐应用',
    build: '1.0.0'
  }
});

// 搜索目录
const music = MusicKit.getInstance();
const results = await music.api.search('周杰伦', {
  types: 'songs,albums',
  limit: 10
});

最佳实践

  • Apple 平台优先使用 MusicKit 原生框架，它自动处理认证、Token 管理和分页
  • Web 端使用内置的媒体播放器组件可以快速搭建播放界面
  • API 请求中通过 l 参数指定语言标签获取本地化内容（如 en-US、es-MX）
  • 注意不同 storefront（地区商店）的目录内容可能不同，通过 storefront 端点查询可用地区
  • JWT Token 的有效期最长 6 个月，Web 端建议包含 origin 提高安全性
  • 使用 limit 参数控制返回数量，避免一次请求过多数据

还有什么值得关注

  • “Meet MusicKit for Swift” Session 提供了 Apple 平台 API 的更深入介绍
  • “Explore more content with MusicKit” 展示了更多功能如排行榜浏览
  • “Cross reference content with Apple Music API” 讲解了跨地区内容匹配的问题
  • Apple Music API 当前版本为 v1，保持向后兼容，但未来可能推出新版本
WWDC 2022