WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Explore the catalog with the Apple Music API

Explore the catalog with the Apple Music API

Audio & VideoMusicKitApple Music API
观看原视频

Highlight

Apple Music API 新增 /search/suggestions、relate、extend、关系视图和 Charts API 参数，让开发者可以更快获取搜索建议、关联资源、扩展属性和排行榜歌单。

核心内容

你做了一个音乐搜索页。用户输入 taylor，界面要立刻给出建议。

以前常见做法是调用 /search/hints 拿建议词。它能告诉你用户可能想搜什么，但不能直接给出艺人、歌曲这类结果。你还要等用户提交，再走常规 /search。输入联想页会慢一拍。

Apple 在 2021 年给 Apple Music API 加了 /search/suggestions。它替代 /search/hints，保留建议词，还能返回 top results（热门结果）。输入框下方可以直接出现艺人和歌曲。

搜索结果出来后，还有第二个问题。你可能只想从一首歌跳到它的专辑页。用 include 拉完整专辑会多拿很多字段。Apple 新增 relate，只返回关联资源的 ID、type 和 href。跳转够用，响应更轻。

有些字段又不能默认全给。比如歌曲的 artistUrl。它有用，但每次搜索都返回会拖慢响应或让对象模型变大。extend 让你按资源类型点名请求扩展属性。

产品页还有另一类数据。艺人页需要热门歌曲、热门 MV、单曲列表。它们更像页面模块。Apple 用 relationship views（关系视图）承载这类数据，开发者可以用 views 参数或 /view/{viewName} 路径请求。

最后，Charts API 可以直接取排行榜歌单。全球日榜和城市榜能通过 /charts 加 with 参数拿到，适合做发现页和本地趋势入口。

详细内容

用 /search/suggestions 返回搜索建议词

（01:25）

/search/suggestions 替代 /search/hints。如果你只需要旧的建议词能力，在请求里指定 kinds=terms。

GET /v1/catalog/us/search/suggestions?term=taylor&kinds=terms

关键点：

  • GET 表示读取 Apple Music 目录数据。
  • /v1/catalog/us 指定访问美国 storefront 的目录。
  • /search/suggestions 是新的搜索建议端点。
  • term=taylor 是用户当前输入的搜索词。
  • kinds=terms 要求返回建议搜索词。

这个响应会标明每条建议的 kind。它还区分用于搜索查询的词和展示给用户看的词。搜索框可以把展示文案做得更友好，同时把查询词交给后续搜索请求。

用 top results 驱动输入联想

（02:09）

输入联想常常需要直接显示艺人和歌曲。新的端点用 kinds=topResults 做这件事，还要指定想要的资源类型。

GET /v1/catalog/us/search/suggestions?term=taylor&kinds=topResults&types=artists,songs

关键点：

  • kinds=topResults 要求返回热门搜索结果。
  • types=artists,songs 把结果限制为艺人和歌曲。
  • top results 的资源放在响应的 content 键下。
  • 这个端点优先速度，结果可能和常规 /search 不同。
  • 常规 /search 仍然适合完整搜索结果页。

这类请求适合输入框下拉层。用户还没按回车，就能点进艺人或歌曲。

用 relate 只拿关联资源标识符

（03:47）

Apple Music API 的 resource identifier（资源标识符）包含 ID、type 和 href。relate 请求关系时，只返回这些标识符。

GET /v1/catalog/us/search/suggestions?term=taylor&kinds=topResults&types=artists,albums,songs&relate[songs]=albums

关键点：

  • types=artists,albums,songs 允许建议结果包含艺人、专辑和歌曲。
  • relate[songs]=albums 表示只对歌曲资源请求 albums 关系。
  • 返回的专辑关系只包含资源标识符。
  • 如果点击歌曲后只需要跳到专辑页，href 已经够用。
  • 相比请求完整关系对象，这种响应更快。

这解决了搜索页的常见浪费。列表页只需要跳转目标，不需要专辑名、封面和更多属性。

用 extend 请求扩展属性

（05:03）

资源默认包含 name、artwork 这类常用属性。某些属性计算成本更高，或使用频率更低，所以不默认返回。extend 用来点名请求这些扩展属性。

GET /v1/catalog/us/search/suggestions?term=taylor&kinds=topResults&types=artists,albums,songs&relate[songs]=albums&extend[songs]=artistUrl

关键点：

  • 这个请求沿用前面的搜索建议和 relate。
  • extend[songs]=artistUrl 表示只为歌曲资源请求 artistUrl 扩展属性。
  • artistUrl 可以用于把用户带到 Apple Music 上的艺人页面。
  • 扩展属性按需返回，避免默认响应变慢或变大。

一个实际用法是搜索结果里的“打开艺人页”按钮。只有这个按钮存在时，才请求 artistUrl。

用 relationship views 构建艺人页模块

（06:16）

views（视图）适合产品页面。它比 relationships（关系）更松散，可以带自己的标题和数据。演讲给出的例子是艺人的 Top Songs 视图。

GET /v1/catalog/us/artists/159260351?views=top-songs

关键点：

  • /artists/159260351 直接获取一个艺人资源。
  • views=top-songs 要求响应里包含热门歌曲视图。
  • views 只能在直接资源获取时请求。
  • 其他例子包括 Top Music Videos 和 singles。
  • 某个资源类型支持哪些视图，需要查 Apple Music API 文档。

同一个视图也可以用路径方式请求。

GET /v1/catalog/us/artists/159260351/view/top-songs

关键点：

  • /view/top-songs 放在资源 ID 后面。
  • 这种写法只请求一个视图。
  • 它适合页面模块懒加载，比如用户滚动到“热门歌曲”区域时再发请求。

用 Charts API 获取排行榜歌单

（06:59）

Apple Music 支持世界、storefront 和城市级排行榜歌单。用户可以把这些歌单加入资料库，歌单会自动更新。现在开发者可以直接从 /charts 获取它们。

GET /v1/catalog/us/charts?types=playlists&with=dailyGlobalTopCharts,cityCharts

关键点：

  • /charts 是排行榜端点。
  • types=playlists 指定要返回歌单类型的排行榜。
  • with=dailyGlobalTopCharts,cityCharts 请求全球日榜和城市榜。
  • with 参数可以只传其中一个集合，也可以两个都传。
  • 返回结果适合放到音乐发现页。

核心启发

  1. 做什么：给音乐 App 做即时搜索下拉层。 为什么值得做：/search/suggestions 可以同时返回建议词和热门结果，适合 typeahead。 怎么开始：监听输入框文本变化，调用 GET /v1/catalog/{storefront}/search/suggestions?term={text}&kinds=topResults&types=artists,songs，把 content 下的艺人和歌曲渲染为可点击项。

  2. 做什么：在歌曲搜索结果里加“查看专辑”快捷入口。 为什么值得做：relate[songs]=albums 只返回专辑资源标识符，拿到 href 就能跳转。 怎么开始：搜索建议请求加入 relate[songs]=albums，在歌曲结果中读取专辑关系的 href，点击后再获取专辑详情页数据。

  3. 做什么：给搜索结果加“在 Apple Music 打开艺人”按钮。 为什么值得做：extend[songs]=artistUrl 可以按需拿到歌曲对应的艺人链接，不必让所有请求默认携带扩展属性。 怎么开始：只有当界面需要外链按钮时，在请求上追加 extend[songs]=artistUrl，再把返回的 artistUrl 绑定到按钮。

  4. 做什么：做一个艺人详情页的“热门歌曲”模块。 为什么值得做：relationship views 专门服务产品页模块，top-songs 直接表达这个页面需求。 怎么开始：进入艺人页时请求 /v1/catalog/{storefront}/artists/{id}?views=top-songs，把视图数据渲染成歌曲列表；如果模块在首屏外，可以改用 /view/top-songs 懒加载。

  5. 做什么：做城市音乐趋势页。 为什么值得做：Charts API 可以用 with=cityCharts 获取城市榜歌单，适合展示本地流行内容。 怎么开始：调用 /v1/catalog/{storefront}/charts?types=playlists&with=cityCharts，把返回的 chart playlists 作为入口，点击后进入歌单详情。

关联 Session

评论

GitHub Issues · utterances