App Store Connect Swift SDK

用于通过 Apple 的 App Store Connect API 进行交互的 Swift SDK。

Platform Compatibility Dependency frameworks Twitter

API 快速入门信息

此 SDK 中包含的内容

请求 API 访问权限

要请求访问权限，请转到 App Store Connect 中“用户和访问”中的新“API 密钥”部分。请注意，您必须是注册为组织的开发团队的团队代理（法律角色）。对注册为个人的开发者的访问权限即将推出。

如何使用 SDK？

并非所有端点都可用，我们正在努力实现所有端点（请参阅 端点）。

1. 导入框架

import AppStoreConnect_Swift_SDK

2. 创建您的 API 配置

转到 https://appstoreconnect.apple.com/access/integrations/api 并创建您自己的密钥。这也是查找您的私钥 ID 和颁发者 ID 的页面。

下载私钥后，您可以打开包含私钥的 .p8 文件，它将显示如下内容

-----BEGIN PRIVATE KEY-----
FDFDGgEAMBMGByqGSM49AgEGCCqGSM49AwEHBHkwdwQgPaXyFvZfNydDEjxgjUCUxyGjXcQxiulEdGxoVbasV3GgCgYIKomokDj0DAQehRANCAAASffd/DU3TUWAoLmqE6hZL9A7i0DWpXtmIDCDiITRznC6K4/WjdIcuMcixy+m6O0IrffxJOablIX2VM8sHRpoiuy
-----END PRIVATE KEY-----

复制内容并删除空白行、-----BEGIN PRIVATE KEY----- 和 -----END PRIVATE KEY-----。

将此私钥与颁发者 ID 和私钥 ID 一起使用以创建您的配置文件

let configuration = APIConfiguration(issuerID: "<YOUR ISSUER ID>", privateKeyID: "<YOUR PRIVATE KEY ID>", privateKey: "<YOUR PRIVATE KEY>")

或者，您可以传递 .p8 文件的路径

let configuration = APIConfiguration(issuerID: "<YOUR ISSUER ID>", privateKeyID: "<YOUR PRIVATE KEY ID>", privateKeyURL: URL(fileURLWithPath: "~/AuthKey_<YOUR PRIVATE KEY ID>.p8"))

这两种方法也都接受一个可选的 expirationDuration 参数，该参数默认为 20 分钟，这是 API 允许的最大持续时间。在某些情况下，指定较短的秒数值以考虑可能的时钟偏差可能很有用

APIConfiguration(issuerID: "<YOUR ISSUER ID>", privateKeyID: "<YOUR PRIVATE KEY ID>", privateKey: "<YOUR PRIVATE KEY>", expirationDuration: "<OPTIONAL EXPIRATION DURATION>"))
APIConfiguration(issuerID: "<YOUR ISSUER ID>", privateKeyID: "<YOUR PRIVATE KEY ID>", privateKeyURL: URL(fileURLWithPath: "~/AuthKey_<YOUR PRIVATE KEY ID>.p8"), expirationDuration: "<OPTIONAL EXPIRATION DURATION>")

您甚至可以省略 privateKeyID，因为它可以通过 .p8 文件的名称推断出来。

3. 创建一个 APIProvider 并执行请求

在使用您的 APIConfiguration 创建 APIProvider 实例后，您可以开始执行您的第一个请求。

let request = APIEndpoint
    .v1
    .apps
    .get(parameters: .init(
        sort: [.bundleID],
        fieldsApps: [.appInfos, .name, .bundleID],
        limit: 5
    ))
let apps = try await self.provider.request(request).data
print("Did fetch \(apps.count) apps")

处理分页响应

如果 API 请求的响应可以分多个页面传递，您可以使用 AsyncSequence 迭代所有页面，或者单独请求跟随当前页面的下一页。

let request = APIEndpoint
    .v1
    .apps
    .get(parameters: .init(
        sort: [.bundleID],
        fieldsApps: [.appInfos, .name, .bundleID],
        limit: 2
    ))

// Demonstration of AsyncSequence result of APIProvider.paged(_)
var allApps: [App] = []
for try await pagedResult in provider.paged(request) {
    allApps.append(contentsOf: pagedResult.data)
}
print("There are \(allApps.count) apps in total")

// Demonstration of APIProvider.request(_:isPagedResponse:) and APIProvider.request(_: pageAfter:)
let firstPageResult = try await provider.request(request)
let firstPageApps = firstPageResult.data
print("The first page of results has \(firstPageApps.count) apps")

if provider.request(request, isPagedResponse: firstPageResult) {
    if let nextPage = try await provider.request(request, pageAfter: firstPageResult) {
        let secondPageApps = nextPage.data
        print("The second page of results has \(secondPageApps.count) apps")
    }
}

处理错误

每当请求返回错误时，您可以通过如下方式捕获错误来获取详细信息

do {
    print(try await self.provider.request(requestWithError).data)
} catch APIProvider.Error.requestFailure(let statusCode, let errorResponse, _) {
    print("Request failed with statuscode: \(statusCode) and the following errors:")
    errorResponse?.errors?.forEach({ error in
        print("Error code: \(error.code)")
        print("Error title: \(error.title)")
        print("Error detail: \(error.detail)")
    })
} catch {
    print("Something went wrong fetching the apps: \(error.localizedDescription)")
}

错误标题和详细信息应有助于您解决失败。有关错误的更多信息，请参阅：Apple 文档中的 解析错误响应代码。

安装

Swift Package Manager

Swift Package Manager 是一种用于自动分发 Swift 代码的工具，它集成到 swift 编译器中。它还处于早期开发阶段，但此 SDK 确实支持在其支持的平台上使用它。

设置好 Swift 包后，将 SDK 添加为依赖项就像将其添加到 Package.swift 的 dependencies 值一样容易。

dependencies: [
    .package(url: "https://github.com/AvdLee/appstoreconnect-swift-sdk.git", .upToNextMajor(from: "2.0.0"))
]

开发

为了帮助开发此存储库，您需要遵循以下步骤

更新 OpenAPI 生成的代码

安装 jq

brew install jq

运行以下命令

$ make update

这将尝试从 Apple 下载 App Store Connect 的 OpenAPI 规范，并重新运行 CreateAPI 生成器以生成更新的源代码。

或者，您可以单独运行 make download 和 make generate。

沟通

使用该 SDK 的应用程序

许可证

App Store Connect Swift SDK 根据 MIT 许可证提供，并使用来自开源项目的源代码。 有关更多信息，请参见 LICENSE 文件。

作者

该项目最初由 Antoine van der Lee 创建，但有很多 优秀的贡献者。我们欢迎任何形式的贡献，以使该项目变得更好。