SpotifyAPI

Spotify网络API的Swift库

特性

支持所有的[Spotify网络API端点][24]，包括播放内容、创建播放列表和获取专辑。
使用Apple的Combine框架，使链接异步请求变得轻而易举
支持三种不同的授权方法
在必要时自动刷新访问令牌

阅读完整的[文档][1]并查看[这个示例iOS应用][14]和这个[示例命令行应用][23]。

赞助商

bbauman1

支持的平台
安装
快速入门
使用带有授权码交换证明密钥的授权码流程进行授权
使用授权码流程进行授权
使用客户端凭证流程进行授权
[将授权信息保存到持久存储][16]
[使用播放器端点][26]
[处理分页结果][27]
[调试][28]
[运行单元测试][29]

支持的平台

Swift 5.6+
iOS 13+
macOS 10.15+
tvOS 13+
watchOS 6+
Linux

安装

在Xcode中，打开你想要添加此包的项目。
从菜单栏中，选择文件 > Swift包 > 添加包依赖...
将此仓库的URL粘贴到搜索栏中。
选择SpotifyAPI库。
按照提示添加包。

快速入门

首先，前往[Spotify开发者仪表板][2]并创建一个应用。你将收到一个客户端ID和客户端密钥。然后，点击"编辑设置"并添加一个重定向URI。通常，这应该是一个重定向到你的应用中某个位置的自定义URL方案。不要在重定向URI的末尾添加斜杠。

下一步是授权你的应用。无论是否需要[授权范围][5]，对Spotify网络API的所有请求都需要授权。此库支持三种授权方法：

带有授权码交换证明密钥的授权码流程：这是移动和桌面应用程序的最佳选择，因为在这些应用中存储客户端密钥是不安全的。与授权码流程相比，它提供了额外的安全层。如果你需要访问/修改用户数据，这需要[授权范围][5]，请使用此方法。它要求用户在浏览器/网页视图中登录他们的Spotify账户并批准你的应用。在[Spotify网络API参考][15]中阅读更多内容。
授权码流程：如果你需要访问/修改用户数据，这需要[授权范围][5]，请使用此方法。它要求用户在浏览器/网页视图中登录他们的Spotify账户并批准你的应用。在[Spotify网络API参考][3]中阅读更多内容。
客户端凭证流程：如果你不需要访问/修改用户数据，请使用此方法。换句话说，你无法访问需要[授权范围][5]或代表用户颁发的访问令牌的端点。这种方法的优势是它不需要任何用户交互。在[Spotify网络API参考][4]中阅读更多内容。

另请参阅[其他授权方法][25]。

在创建使用此库的应用程序时，你可能希望将授权信息保存到持久存储，这样用户就不必在每次应用程序退出并重新启动时都重新登录。有关如何执行此操作的指南，请参阅[将授权信息保存到持久存储][16]。

使用带有授权码交换证明密钥的授权码流程进行授权

创建一个SpotifyAPI实例，并将AuthorizationCodeFlowPKCEManager实例分配给authorizationManager属性：

import SpotifyWebAPI

let spotify = SpotifyAPI(
    authorizationManager: AuthorizationCodeFlowPKCEManager(
        clientId: "你的客户端ID"
    )
)

在每次身份验证请求之前，你的应用应该生成一个代码验证器和一个代码挑战。代码验证器是一个长度在43到128个字符之间的加密随机字符串。它可以包含字母、数字、下划线、句点、连字符和波浪号。

为了生成代码挑战，你的应用应该使用SHA256算法对代码验证器进行哈希处理。然后，[base64url][19]编码你生成的哈希。不要包含任何=填充字符（无论是否进行百分比编码）。

你可以使用String.randomURLSafe(length:using:)或String.randomURLSafe(length:)来生成代码验证器。你可以使用String.makeCodeChallenge(codeVerifier:)实例方法从代码验证器创建代码挑战。

例如：

let codeVerifier = String.randomURLSafe(length: 128)
let codeChallenge = String.makeCodeChallenge(codeVerifier: codeVerifier)

// 可选，但强烈推荐
let state = String.randomURLSafe(length: 128)

如果你使用自己的方法创建这些值，可以使用此[PKCE生成器工具][18]进行验证。另请参阅Data.base64URLEncodedString()和String.urlSafeCharacters。

接下来，创建将在浏览器（或网页视图）中打开的授权URL。打开时，它会向用户显示权限对话框。然后用户可以选择授权或拒绝授权你的应用程序。

let authorizationURL = spotify.authorizationManager.makeAuthorizationURL(
    redirectURI: URL(string: "你的重定向URI")!,
    codeChallenge: codeChallenge,
    state: state,
    scopes: [
        .playlistModifyPrivate,
        .userModifyPlaybackState,
        .playlistReadCollaborative,
        .userReadPlaybackPosition
    ]
)!

请参阅[makeAuthorizationURL(redirectURI:showDialog:codeChallenge:state:scopes:)][20]的完整文档。

重定向URI需要已在你使用[Spotify开发者仪表板][2]注册应用程序时指定的重定向URI白名单中输入。不要在重定向URI的末尾添加斜杠。

每个端点的文档列出了所需的[授权范围][5]。如果需要，你始终可以为不同的范围再次授权你的应用程序。然而，这不是一个累加过程。每次创建授权URL时，你必须指定所有需要的范围。

你可以决定如何打开URL。如果你正在创建iOS应用，最简单的方法是使用UIApplication.shared.open(authorizationURL)在浏览器中打开URL。

在用户批准或拒绝你的应用授权后，Spotify将重定向到你在创建授权URL时指定的重定向URI，并附加查询参数。将此URL传递给[requestAccessAndRefreshTokens(redirectURIWithQuery:codeVerifier:state:)][21]以请求访问和刷新令牌：

spotify.authorizationManager.requestAccessAndRefreshTokens(
    redirectURIWithQuery: url,
    // 必须与创建授权URL时用于生成代码挑战的代码验证器匹配。
    codeVerifier: codeVerifier,
    // 必须与创建授权URL时使用的值匹配。
    state: state
)
.sink(receiveCompletion: { completion in
    switch completion {
        case .finished:
            print("成功授权")
        case .failure(let error):
            if let authError = error as? SpotifyAuthorizationError, authError.accessWasDenied {
                print("用户拒绝了授权请求")
            }
            else {
                print("无法授权应用程序：\(error)")
            }
    }
})
.store(in: &cancellables)

一旦此发布者成功完成，你的应用程序就获得了授权，你可以开始向Spotify网络API发出请求。确保在进行另一次授权请求之前为状态参数、代码验证器和代码挑战生成新值。访问令牌将在必要时自动刷新。例如：

import SpotifyExampleContent

let playbackRequest = PlaybackRequest(
    context: .uris(
        URIs.Tracks.array(.faces, .illWind, .fearless)
    ),
    offset: .uri(URIs.Tracks.fearless),
    positionMS: 50_000
)

spotify.play(playbackRequest)
    .sink(receiveCompletion: { completion in
        print(completion)
    })
    .store(in: &cancellables)

所有端点的完整文档可以在[这里][8]找到。我们还建议你阅读[Spotify网络API参考][12]。

使用授权码流程进行授权

创建一个SpotifyAPI实例，并将AuthorizationCodeFlowManager实例分配给authorizationManager属性：

import SpotifyWebAPI

let spotify = SpotifyAPI(
    authorizationManager: AuthorizationCodeFlowManager(
        clientId: "你的客户端ID", clientSecret: "你的客户端密钥"
    )
)

接下来，创建将在浏览器（或网页视图）中打开的授权URL。打开时，它会向用户显示权限对话框。用户可以选择授权或拒绝授权您的应用程序。

let authorizationURL = spotify.authorizationManager.makeAuthorizationURL(
    redirectURI: URL(string: "您的重定向URI")!,
    showDialog: false,
    scopes: [
        .playlistModifyPrivate,
        .userModifyPlaybackState,
        .playlistReadCollaborative,
        .userReadPlaybackPosition
    ]
)!

查看[makeAuthorizationURL(redirectURI:showDialog:state:scopes:)][6]的完整文档。

重定向URI需要已在您使用[Spotify开发者控制台][2]注册应用程序时指定的重定向URI白名单中输入。不要在重定向URI的末尾添加斜杠。

每个端点的文档列出了所需的[授权范围][5]。如果需要，您可以随时为不同的范围重新授权您的应用程序。但这不是累加过程。每次创建授权URL时，您必须指定所需的所有范围。

您可以决定如何打开URL。如果您正在创建iOS应用，最简单的方法是使用UIApplication.shared.open(authorizationURL)在浏览器中打开URL。

用户批准或拒绝您的应用程序的授权后，Spotify将重定向到您在创建授权URL时指定的重定向URI，并附加查询参数。将此url传入[requestAccessAndRefreshTokens(redirectURIWithQuery:state:)][7]以请求访问令牌和刷新令牌：

spotify.authorizationManager.requestAccessAndRefreshTokens(
    redirectURIWithQuery: url
)
.sink(receiveCompletion: { completion in
    switch completion {
        case .finished:
            print("成功授权")
        case .failure(let error):
            if let authError = error as? SpotifyAuthorizationError, authError.accessWasDenied {
                print("用户拒绝了授权请求")
            }
            else {
                print("无法授权应用程序：\(error)")
            }
    }
})
.store(in: &cancellables)

一旦此发布者成功完成，您的应用程序就获得授权，您可以开始向Spotify Web API发出请求。在进行另一个授权请求之前，请确保为状态参数生成新值。访问令牌将在必要时自动刷新。例如：

spotify.currentUserPlaylists()
    .extendPages(spotify)
    .sink(
        receiveCompletion: { completion in
            print(completion)
        },
        receiveValue: { results in
            print(results)
        }
    )
    .store(in: &cancellables)

此授权过程在这个[示例应用][22]中完全实现。所有端点的完整文档可以在[这里][8]找到。我们也鼓励您阅读[Spotify Web API参考][12]。

使用客户端凭证流进行授权

创建SpotifyAPI的实例，并将ClientCredentialsFlowManager的实例分配给authorizationManager属性：

import SpotifyWebAPI

let spotify = SpotifyAPI(
    authorizationManager: ClientCredentialsFlowManager(
        clientId: "您的客户端ID", clientSecret: "您的客户端密钥"
    )
)

要授权您的应用程序，调用authorize()：

spotify.authorizationManager.authorize()
    .sink(receiveCompletion: { completion in
        switch completion {
            case .finished:
                print("成功授权应用程序")
            case .failure(let error):
                print("无法授权应用程序：\(error)")
        }
    })
    .store(in: &cancellables)

查看[authorize][13]的完整文档。

一旦此发布者成功完成，您的应用程序就获得授权，您可以开始向Spotify Web API发出请求。访问令牌将在必要时自动刷新。例如：

spotify.search(query: "Pink Floyd", categories: [.track])
    .sink(
        receiveCompletion: { completion in
            print(completion)
        },
        receiveValue: { results in
            print(results)
        }
    )
    .store(in: &cancellables)