App Store Connect

一个 Swift 库，用于访问 Apple 的 App Store Connect API 和 Enterprise Program API。

import AppStoreConnect
import AppStoreAPI

let privateKey = try JWT.PrivateKey(contentsOf: URL(filePath: "..."))
let client = AppStoreConnectClient(
    authenticator: JWT(
        keyID: "...",
        issuerID: "...",
        expiryDuration: 20 * 60, // 20 minutes
        privateKey: privateKey
    )
)

let apps = try await client.send(Resources.v1.apps.get())
print(apps)

本项目支持 Swift 5.9 及更高版本，最低要求为 iOS 16、macOS 13、tvOS 16 和 watchOS 9。它致力于完全支持 Swift.org 平台支持页面 中列出的所有其他平台上的部署，例如各种 Linux 版本和 Windows。支持 App Store Connect API 3.8 版本和 Enterprise Program API 1.0 版本。

该软件包定义了两个产品：AppStoreConnect 和 EnterpriseProgram。每个产品都提供 AppStoreConnect 模块，其中包含客户端和身份验证逻辑，以及 AppStoreAPI 或 EnterpriseAPI 模块，分别对应于 App Store Connect 和 Enterprise Program。要与 App Store Connect 集成，您可以添加对 "AppStoreConnect" 产品的依赖项。要使用 Enterprise Program API，请添加 "EnterpriseProgram" 产品作为目标依赖项。最后，这两个产品可以作为同一目标的依赖项，而不会产生重大冲突。有关此方面的粗略示例，请参见 invite_user 示例。

要在您的项目中使用 AppStoreConnect，请将以下行添加到您的 Package.swift 文件中的依赖项中

.package(url: "https://github.com/aaronsky/asc-swift", from: "1.0.0"),

然后，将 "AppStoreConnect" 作为您目标的依赖项包含

.target(name: "<target>", dependencies: [
    .product(name: "AppStoreConnect", package: "AppStoreConnect"),
]),

最后，将 import AppStoreConnect 添加到您的代码中以导入客户端，并将 import AppStoreAPI 添加到您的代码中以导入 API 绑定。

该项目可在 Bazel Central Registry 上找到。与那里的其他模块非常相似，添加依赖项所需的只是将以下行插入到您的 MODULE.bazel 中。请注意，这需要您的项目使用 Bzlmod。

bazel_dep(name = "asc_swift", version = "<version>")

可以在 Examples/bzlmod 中找到如何设置此示例。

App Store Connect API 和 Enterprise Program API 都没有任何允许未经授权的请求的方法。为了便于使用 App Store Connect 进行身份验证，此库提供了上述的 JWT 类型，以便在 JSON Web Tokens 过期时自动处理签名和轮换。例如

import AppStoreConnect

let privateKey = try JWT.PrivateKey(contentsOf: URL(filePath: "..."))
let client = AppStoreConnectClient(
    authenticator: JWT(
        keyID: "...",
        issuerID: "...",
        expiryDuration: 20 * 60, // 20 minutes
        privateKey: privateKey
    )
)

您可以通过 为 App Store Connect API 创建 API 密钥 在 Apple 的文档页面上了解有关为 App Store Connect API 创建必要凭据的更多信息，或者在此处的相应的 Enterprise Program API 文档 here。所有 App Store Connect 和 Enterprise Program API 都限定于预配置密钥的凭据，因此您不能使用此 API 对整个 App Store 进行查询。

在 API 将响应错误的许多情况下，API 将包含一个 ErrorResponse 对象，详细描述故障。如果问题是由于格式错误的请求引起的，则此对象还包含可用于诊断问题根本原因的属性。如果 API 响应错误，AppStoreConnectClient 将抛出 Response.Error.requestFailure 供您考虑。此错误包含从 API 返回的 ErrorResponse、HTTP 状态代码和底层响应。

此外，Apple 对所有 API 客户端施加速率限制。如果 API 产生速率限制错误，AppStoreConnectClient 将抛出 Response.Error.rateLimitExceeded 以方便您使用。此错误包含从 API 返回的 ErrorResponse、包含调用限制和剩余调用信息的 Response.Rate 以及底层响应。

例如

do {
    let apps = try await client.send(Resources.v1.apps.get())
} catch Response.Error.requestFailure(let error, let statusCode, let response) {
    print("Received an error: \(error)")
} catch Response.Error.rateLimitExceeded(let error, let rate, let response) {
    print("Client has exceeded the rate limit")
} catch {
    print("An unexpected error occurred: \(error.localizedDescription)")
}

您可以通过 解释和处理错误 在 Apple 的文档页面上了解有关如何处理来自 App Store Connect API 的错误的更多信息。您可以通过 识别速率限制 在 Apple 的文档页面上了解有关速率限制的更多信息。可以在 此处 和 此处 找到 Enterprise Program API 的相应文档。

最后，AppStoreConnectClient 可以自动重试状态代码为 500 的 API 错误。将 RetryStrategy 值传递给任何 AppStoreConnectClient 方法上的 retry: 参数。支持的值为 .never（默认值）、.fixedInterval、.exponentialBackoff 或 .custom 处理程序。

对资源集合（应用程序、构建、Beta 测试小组等）的所有请求都支持分页。分页资源的响应将包含类型为 PagedDocumentLinks 的 links 属性，其中包含 first、next 和 self 的“引用” URL。您还可以在响应的 meta 字段中找到有关每页限制和资源总数的更多信息，该字段的类型为 PagingInformation。对于典型的分页，您通常不需要任何这些信息。

分页最常见的应用是从第一个“页面”向前分页。例如

for try await appsPage in client.pages(Resources.v1.apps.get()) {
    print(appsPage)
}

您还可以使用 AppStoreConnectClient 上的 send(_:pageAfter:retry:) 方法手动向前分页。

App Store Connect 采用三步流程来上传资产，例如预览、屏幕截图和路由覆盖文件作为应用程序元数据。可以从高层次上将该过程描述为

1. 为资产进行预留
2. 以 API 定义的块上传资产
3. 提交预留

该过程有多个故障点，并在 Apple 的文档页面 将资产上传到 App Store Connect 上详细说明。此库包含两个如何上传资产的示例，upload_preview 和 upload_screenshot，以及 一篇详细的文章。

该项目的主要目标是覆盖官方 App Store Connect API 和 Enterprise Program API 公开的整个 API 表面。否则，它正在被开发以帮助作者进行内部应用程序开发。因此，在软件包的版本稳定为 v1 之前，除了上述目标之外，没有明确的路线图。但是，始终欢迎您提供贡献。如果您想参与其中或者只是想提供反馈，请参阅 CONTRIBUTING.md 以了解详情。

此库是在 BSD-2 许可证下发布的。

有关完整文本，请参阅 LICENSE。

此库的技术方向是由先前在 asc-go 和 appstoreconnect 上的工作驱动的，以及由 @AvdLee 等人在 appstoreconnect-swift-sdk 中生成的成熟示例。客户端设计是由先前在 buildkite-swift 和 wanikani-swift 上的工作驱动的。App Store Connect、App Store Connect API 和 Enterprise Program API 是 Apple 的财产。