Apple Music API 和 MusicKit 简介

Justin Rennell: 大家好 欢迎来到 WWDC 我是 Justin 是 Apple Music 开发团队的工程师 今天我将介绍 MusicKit 重点介绍使用 Apple Music API 的基础知识 在本期讲座中 我将概述 MusicKit 客户端框架 以及它们如何与 Apple Music API web 服务集成 我将解释如何作为开发人员 获得访问权限 以及使用 Apple Music API 的 具体细节 包括 请求内容和资源 使用限制和分页来处理大型资源集合 以及如何使用搜索端点 在目录中查找内容 最后 我将介绍一些可供 Apple Music 订阅者使用的个性化功能 以及如何在您的 App 中 提供对它们的访问权限

我先简单介绍一下 MusicKit 和 Apple Music API MusicKit 于 2017 年 在 WWDC 首次发布 从那以后 我们进行了改进 使得与 Apple Music 的集成 更加容易 并继续添加对附加功能的支持 MusicKit 是客户端框架 和 Apple Music API 的组合 两者一起使用 可以将 Apple Music 功能 添加到您的 App 中 您可以从 Apple Music 中 发现和获取内容 包括艺术家 专辑 播放列表等 并具有搜索目录 和浏览流行排行榜的功能 在用户同意的情况下 MusicKit 和 Apple Music API 允许您验证订阅者播放可用内容 并提供对个性化功能的访问 包括他们的音乐库 推荐 和最近播放的历史记录 MusicKit 客户端框架提供了 对订阅者进行身份验证 以及在设备上 开始和控制播放所需的 API 客户端框架可用于 Apple 平台上的 App 使用 Javascript 的 网页 App 和使用可用 SDK 的 Android App

Apple 平台上的 MusicKit 拥有将 Apple Music 集成到 App 中所需的一切 订阅者可以在您的 App 中 进行身份验证或注册 以开始和控制播放 并访问其他个性化功能 可用的 API 通过 对资源和分页的原生支持 加速了从 Apple Music 中 发现和访问内容的调用 后面涉及的许多关于 直接访问 Apple Music API 和向 Apple Music API 发出请求的主题 都由 Apple 平台上的 MusicKit 自动处理 我们鼓励为 Apple 平台 编写 App 的开发人员 观看讲座 “Meet MusicKit for Swift” 以了解这些 API 并观看讲座 “Explore more content with MusicKit” 以了解更多功能

Web 上的 MusicKit 使您可以 使用 Javascript 轻松地 将 Apple Music 引入您的App 您可以发现 Apple Music 内容 让订阅者登录以访问个性化功能 并直接在您的网站上播放内容 完全访问 Apple Music API 让您能够 创造独特的音乐体验 MusicKit 提供了一组 内置的 web 组件 包括一个全功能的媒体播放器 这些组件使入门变得容易 并且可以根据您的体验 进行灵活定制

Android 版的 MusicKit 可以让您 将 Apple Music 集成到 您的 Android App中 支持对 Apple Music 订阅者 进行身份验证 控制内容播放 对 Apple Music API 的完全访问 让您能够构建丰富的音乐体验

Apple Music API 是常见的 JSON web 服务 提供对发现功能 和 Apple Music 目录内容的访问 经过认证的用户 可以访问个性化功能 包括他们的音乐库 推荐 和最近播放的历史记录 接下来 我将解释如何获得访问权限 要向 Apple Music API 发出请求 您需要一个开发者令牌 对于 Apple 平台上的 App 您可以通过为您的 App 启用 MusicKit 服务 来利用自动令牌管理的优势 这项服务可以 在 Apple Developer Portal 的 App ID 部分找到

对于其他平台上的 App 您可以通过在 Apple Developer Portal 上注册 成为 MusicKit 开发者 来获取开发者令牌 从那里 您可以请求和下载私钥 您将需要生成一个 JSON Web 令牌 并使用您下载的私钥对其进行签名 JSON Web 令牌分为两部分 第一部分是必需的标头 包括签名算法 alg 它必须是 ES256 以及密钥标识符 kid 它包含在您的私钥下载中 令牌的第二部分是声明 Apple Music API 有三个必需的声明 发布者 ID “iss” 这是您的团队 ID 可以在 Apple Developer portal 的 会员部分找到 发布时间为 iat 由自 Epoch 以来的秒数表示 以及到期时间 exp 这与发布时间的时间格式相同 生成的令牌最长 可在发行后六个月内到期 对于 网页 App 我们鼓励提供来源声明 这将颁发一个 仅对您的网站有效的令牌

必须在授权标头中 为 Apple Music API 的所有请求 提供有效的签名令牌 在 Apple 平台上为您的App 启用 MusicKit 服务后 这将自动完成 必须使用您生成的令牌 配置 Web 上的 MusicKit 来向 Apple Music API 发出请求 有关生成 JSON Web 令牌的 更多信息 请参阅 Apple Music API 文档 现在我将向您展示如何 使用 Apple Music API 请求资源 资源对 Apple Music 内容进行建模 例如艺术家 专辑 歌曲 播放列表等 每个都有自己对应的类型 可以通过搜索等发现功能 或使用它们的标识符 从 Apple Music API 端点获取资源 下面是一个使用其标识符 从 API 获取播放列表资源的 示例请求 URL Apple Music API 在 api.music.apple.com 上托管 URL 的路径使用 RESTful 模式 代表资源或功能的位置 位置中的第一个元素是 API 的版本 当前是版本 1 当引入重大更改时 可能会出现新版本 版本与现有调用保持向后兼容性 即使对资源和新功能进行了增强 对于 Apple Music 目录中的请求 该位置的下一部分表示 要从中获取的特定目录 Apple Music 是一项全球流媒体服务 内容可能因地区而异 我们将其称为店面

有关店面和内容可用性的信息 请观看题为“Cross reference content with the Apple Music API”的讲座 在这个例子中 我将从美国店面的目录中 获取一个播放列表 用两个字母的国家代码 us 表示 该位置的最后一部分是资源的标识 由后面跟有标识符的 类型播放列表表示

由于 Apple Music 在许多地区都可用 因此可以使用可选的 语言标签查询参数 L 来支持本地化 在这里 我为英语指定了 语言标签 en-US 要获取以西班牙语本地化的内容 我可以指定标签 es-MX 为了简单起见 我不会在这些示例中指定语言标签 这会导致店面的默认本地化 可以通过访问店面引用端点 找到 Apple Music 所在的店面及其支持的本地化 更多细节可以在 Apple Music API 文档中找到

下面看一下 对播放列表发出 GET 请求 这将返回一个包含播放列表资源的 “数据”数组的资源收集响应 资源对象用 ID 值和类型 指示内容的身份 ID 和类型的组合代表了 资源的唯一身份 href 值指示 API 中 可以获取资源的位置 在这种情况下 请注意该位置 与我们请求的路径相同 内容的元数据值 可在资源的属性映射中找到 在关系图中可以找到 与其他资源的直接连接 例如此播放列表 curator 和曲目

下面是属性映射的详细介绍 其中包含播放列表的元数据值 我将介绍一个在右侧小部件中 使用其中一些属性的示例 该小部件使用播放列表的名称 curator 名称和描述属性 playParams 是许多资源类型的 通用属性 它指示内容何时可以 流式传输给订阅者 这可用于确定是否应启用播放控制 因为没有 playParams 的内容 不可用于播放 Artwork 是许多资源类型的 另一个常见属性 它包含图像的最大宽度和高度值 以及可以从中加载图像的 url

在 Apple 开发者的反馈非常重要 它可以帮助我们为每个人 改进我们的 API 和服务 今年 我们很高兴地宣布 添加了我们最受欢迎的一个功能 艺术家作品现在可在 Apple Music API 中使用 让简单的剪影成为过去 所有新的和现有的 App 都可以 通过查找添加到艺术家资源的 艺术品属性来添加对这些图像的支持 这是我们之前查看的播放列表的 艺术作品 url 的缩写示例 艺术品 url 包含以蓝色突出显示的 宽度 w 和 高度 h 来标记 要使用此 URL 加载插图 请将这些标记替换为 您的显示器所需的分辨率 由于播放列表图片是方形的 我将使用相同的宽度和高度分辨率 下面是请求分辨率为 400x400 300x300 和 200x200 的示例 图像会以每种分辨率缩放显示 对于较小的图像 文件大小会减小

所有资源类型都有一组默认属性 代表该资源的通用或基本元数据 某些资源具有可以获取的附加属性 称为扩展属性 可以使用扩展查询参数 来请求这些扩展属性 例如 Apple Music 播放列表中的曲目 要么是歌曲 要么是音乐视频 如果您想知道播放列表 包含的曲目类型 可以请求 trackTypes 扩展属性 扩展属性与它们的默认属性 一起出现在资源的属性图中 如果播放列表的曲目 是音乐视频而不是歌曲 也许您可以自定义播放按钮 以通知查看者

现在看一下关系图 可以看到从这个播放列表 到其他资源的几个直接连接 许多资源具有自动关系 在直接请求某些内容时 会返回这些关系 播放列表的自动关系 是其 curator 和曲目 命名关系是为了表明连接是什么 例如此播放列表的 curator 它们有一个可以 直接获取关系的 href 位置 和一个用于相关资源集合的数据数组 对于播放列表 策展人关系是自动关联的 这意味着只会出现相关资源的身份 这允许使用其标识或 href 轻松链接到此资源 由于播放列表已经包含 curator 的姓名作为属性 因此可能不需要包含 相关 curator 资源的其他元数据 资源的身份可以用来 将 curator 命名为一个链接 让人们可以根据自己的意愿 导航到 curator 以发现其他内容 如果您想通过播放列表 显示 curator 的其他信息 例如其艺术作品 您将需要获取 curator 的元数据 使用 include 参数指定 您想要相关资源元数据的关系 某些资源类型具有默认情况下 未包含的其他关系 也可以使用此参数请求这些关系 请注意 包含关系会增加响应的大小 并对 App 的速度产生负面影响 许多可能需要从相关资源中 获得的有用值 可以直接作为原始资源的属性找到 为了获得最佳性能 我们建议 仅包含响应中所需的关系和元数据 资源类型及其可用属性和关系的 详细信息可以在 Apple Music API 文档中找到 有关扩展属性 关系 和称为视图的特殊关系的更多信息 请观看讲座 “Explore the catalog with the Apple Music API” 重新访问示例播放列表的关系 播放列表的曲目被自动包含在内 这意味着相关曲目资源的属性元数据 出现在响应中 相关曲目的属性可用于 显示播放列表的曲目列表 使用它们的插图和右侧小部件中 显示的其他元数据 在之前的部分 我展示了 一个从包含曲目的目录中 获取播放列表资源的示例 在这个部分 我将解释如何处理 与大量资源的关系 关系的相关资源出现在其数据数组中 当相关资源数量较少时 所有资源将出现在单个响应中 必须在称为页面的多个部分中 获取具有比单个响应中更多的 相关资源的关系

我将以大型播放列表的轨道关系为例 默认情况下 仅包含播放列表的前 100 首曲目 如果播放列表的曲目超过 100 个 则必须在后续页面中获取额外的曲目 以下是包含 100 多首曲目的 播放列表的示例响应 如前所述 跟踪关系的 href 和资源收集数据出现在响应中 由于此播放列表的曲目 多于响应中包含的曲目 因此下一个位置显示为数据的同级 下一个位置表示可以获取集合中 剩余资源的位置 获取下一个位置会直接获取关系 并从提供的偏移量 开始返回关系的资源集合数据 关系的默认限制将应用于每个页面 您可以通过提供限制参数 来选择自己的页面大小 页面大小限制可以介于 1 和特定关系的最大页面大小之间 这可以在文档中找到 如果关系的资源集合 包含页面中 返回的资源之外的其他资源 则下一个位置 将继续显示为数据的同级 当资源集合用尽时 下一个位置将不会显示 请注意 下一个位置不反映 请求选定的页面大小 如果您希望使用 与默认不同的页面大小 则需要为每个请求 提供一个限制参数 始终使用响应中的下一个位置 来给资源集合分页 尝试计算您自己的偏移量 可能会导致 位置无效或结果重复的问题 在下一个部分 我将展示 如何使用 Apple Music API 在 Apple Music 目录中 搜索 fof 内容 Apple Music API 提供了 使用搜索词 在目录中查找内容的功能 搜索请求类似于目录资源请求 以 /search 作为位置 以搜索词作为参数 您可以使用 type 参数 指定您感兴趣的内容类型 并使用限制指定每种类型 要包含的最大结果数 当找到了更多的结果 超过请求的限制时 可以使用分页来继续搜索 这是搜索带有“流行音乐”一词的 专辑和歌曲的响应 搜索端点返回带有结果对象的响应 其中包含每个请求类型的组 和匹配的内容 对于此请求 找到了匹配的专辑和歌曲

该响应还包括一个元对象 其中包含基于相关性 为结果组推荐的顺序 如果您正在构建 一次处理多种内容类型的 搜索体验 这可能会有所帮助 每个结果组都有一个 href 和一个资源集合数据数组 其中包含与搜索项 相关类型的匹配资源 如果结果组有更多匹配可用 则该组将包含下一个位置 可以在该位置获取更多匹配 请求下一个位置会返回 从偏移量开始的 所选类型的更多结果 在最后一个部分 我将讨论 访问 Apple Music API 中的 个性化功能

Apple Music API 和 MusicKit 提供 对特定用户的个性化功能的访问 这些功能让您可以支持订阅者 查看和搜索 其 Apple Music 资料库中的内容 包括添加他们喜欢的内容 和创建新播放列表的功能 个性化推荐可以基于 个人的音乐品味来呈现 您还可以让人们重新发现 他们最近一直在听的音乐 以便从上次中断的地方 重新开始或提供全新的体验

个性化功能可供 积极订阅 Apple Music 的人使用 要支持这些功能 您必须首先 使用 MusicKit 对您的 App 用户进行身份验证 并请求访问他们音乐数据的权限 授予权限后 Music User Token 将是可用的 这个令牌被添加到 Apple Music API 请求的 music-user-token 标头中 并用于验证对个性化数据的访问

Music User Token 是特定于 您的 App 和用户进行身份验证的 此令牌不得跨设备共享 因为一次只能为一台设备授予权限 令牌可能会因 个人订阅或密码的更改而失效 或者如果他们撤销了 对您的 App 的访问权限 它也可能会随着时间的推移而过期 可以通过提示他们重新登录 并为您的 App 授予权限 来刷新身份验证 请注意 此令牌 由 Apple 平台上的 MusicKit 和 Web 上的 MusicKit 自动管理 更多相关的详细信息 请参阅您正在使用的 框架的文档 在今天的讲座中 我展示了如何使用 MusicKit 和 Apple Music API 将 Apple Music 集成到您的 App 中 快速了解支持 MusicKit 客户端框架的平台 以及如何使用 Apple Music API 访问和查找目录中的内容 以及一些可供订阅者使用的 个性化功能 有关今年 Apple 平台上 MusicKit 更新的更多信息 请查看讲座 使用 MusicKit 探索更多内容 感谢收看 我们希望您享受 今年余下的 WWDC 之旅