使用 App Store Connect API 扩展自动化

（你好 WWDC 2020）

你好 欢迎来到 WWDC 欢迎来到“使用 App Store Connect API 扩展自动化” 我叫 Geoff Coffey 是 App Store Connect 的工程师 今天我将给大家展示一些新功能 这些功能将在今年下半年登陆 App Store Connect API

在两年前的 WWDC 上 我们介绍了这一 API 自那之后 用户的反馈一直非常良好 我们很开心能看到大家告诉我们 自己是怎么用这个 API 来简化 app 开发及 TestFlight 程序的 在最初发布时 我们将关注点放在了用户在 App Store Connect 中高频使用的功能上 例如管理自己团队的用户 创造配置文件、添加或删除 β 测试器 以及下载销售及财务报告 由于这些功能的使用频率非常高 因此我们为用户提供了相应工具 来将以上操作自动化 这样大家可以将更多时间投入在 app 上 这是两年前初次发布时的样子 但是 app 开发工作流程中的 一些重要部分 尚未囊括在 API 中 怀着激动的心情 我宣布在今年下半年 App Store Connect API 将迎来两个强大的新扩展 首先 我们将添加一个 综合 App 元数据 API 这样一来 用户就可以在 App Store 中 管理自己的存在 而新的动力和性能指标及诊断 API 使得以编程方式访问在 Xcode 中 驱动动力和性能分析工具的 同一聚集数据成为可能 这对 App Store Connect API 而言 是一次重大更新 我们添加了超过 200 个新端点 比 API 整体规模的一倍还要多 用户可以管理如 app 种类 全球可用性、主要地区和许可协议等 app 信息 可以打造新版本或添加新平台 上传 app 预览和截屏 以及添加和更新诸如 app 名称、描述 以及关键词等等的 本地化信息 API 已完全覆盖 app 版本元数据 因此用户可以完成从创建新版本 到提交供 App Review 的全部操作 我想说的是 你仍需使用 App Store Connect 网站 手动发布你的 app 并且配置 App 内购买项目 和 Game Center 由于增添了这么多的新功能和代码能力 我们想要尽可能简化 API 的使用流程 因此 我们同样在编制 一个完整的 OpenAPI 规范文件 这个文件可供用户自由下载 如果你对 OpenAPI 有些陌生的话 它是流行的 Swagger 格式的 开放标准版本 3 你可以在 Swagger-UI 中查看它 以快速获得 API 参考 甚至将它导入至代码生成器中 让所有语言的 API 集成引导 变得更加简单快捷 我们同样也优化了说明文档 当然 所有新的端点均包括在其中 现在 在更清晰完整的请求及回应示例的帮助下 我们为速率限制和文档上传等主题 添加了几篇新的解释文章 我们提供了可下载的示例代码 展示诸如创建和身份认证标签签名 与 API 回应互动以及使用新 Asset 上传 API 之类的重要 API 概念 因此 让我们看一下新的 APP 元数据 API 都能做些什么 这是我的 app Forest Explorer 我辛辛苦苦创建了一个新版本 我已经准备好将这个新版本提交至 App Store 了 让我来展示一下 如何使用新的 API 来完成提交 我们需要重点关注五个地方 我们将创建一个新版本、定价 更新 app 元数据 将该版本与一个构建关联 之后向 App Review 提交新版本 我们从在 App Store Connect 中 创建 app 的新版本开始 在 App Store Connect 中 使用侧边栏中的这些链接 在 app 页面进行创建 我可以选择创建一个 iOS app 的新版本 添加一个 macOS 或 Apple tvOS 的版本 API 支持同样的操作 在 API 中 我们有一个名叫 Apps 的资源 你的每一个 app 都拥有这个资源 并且每个 app 都和 App Store Versions 有一个关联 它们有一个平台、iOS、Apple tvOS 或 macOS 且有一个版本字符串 也就是你想要在 App Store 中 显示的版本号 因此我们只需要创建一个新的 App Store Version 创建时 我们用 ID 将它和 app 连接起来 因此 我们要做的第一件事就是 查询 app 的识别号 这件事可以通过 API 完成 我要发一个 GET 请求到 v1/apps 路由 然后用 bundleID 筛选 这是一个搜索特定 app 的好方法 若我发送了这个请求 我会得到 一个成功的 200 响应 响应包含 app 资源 以及这里我们看到的 app 识别号 在 App Store Connect 说明文档中 有时你会看到这个 ID 叫做 你的 app 的 Apple ID 我们把这个 ID 记下来 那我们就做好创建新版本的准备了 对 v1/appStoreVersions 做一个 POST 请求 我们提供平台和新的版本字符串 并且给 app 包含一个关联链接 我们就要在这里使用刚刚查找的 App ID 我发送了这个请求 得到了 201 已创建的响应 这告诉我们 App Store Connect 已创建了这一新版本 如果我们现在登陆 App Store Connect 的话 在侧边栏就能看到这个版本了 在响应中 我们看到了这个识别号 App Store Connect 已经把它 分配到这个版本 现在我们想要给 app 设置定价和可用性 在 App Store Connect 中的 App 页面 首先在侧边栏中点击“价格与可用性” 页面会跳转至“价格与可用性”界面 而今天我们将重点看一下“价格表” 今天我就不给大家展示了 但你同样可以使用 API 来管理 app 的预购订单 以及全球的可用性 那么 如何将定价融入到 API 资源模型中呢？ 我们再次从 Apps Resource 开始 它跟一个名叫 App Prices 的资源 有另外的关联 每个 App Price 都有一个开始日期 对目前的价格而言 这是一个空值 但是这是一个价格表 所以我们未来可能会有多个 计划价格的变化 这么一来 我们的 app 就有多个定价了 每个新增的价格均有一个开始日期 也就是在世界范围内该价格生效的日期 每个 App Price 还有一个阶梯报价 这跟大家熟知的 App Store Connect 的阶梯报价是一样的 包括免费梯度、99美分的第一梯度等等 要在 App Store Connect 中选一个梯度 一般来讲要先转到 “所有价格与货币”的页面 我给大家看一下 回到“价格与可用性” 我们在这里点击“所有价格与货币” 可以看到像这样的一个价格列表 左边一列是各个价格梯度 上边一行是 App Store 所在的各个区域 每个区域和每个梯度都有各自的价格点 每个价格点有两个值 一个是消费者按照所在区域使用的货币 为这一 app 支付的价格 另一个值就是每次售出所得收入 回到资源模型上 这里的价格梯度 其实是与另一组资源的关联 这些灰色的资源是只读参考数据 就是你在“所有价格与货币”页面上 看到的数据 每个价格梯度包含了一系列价格点 一个价格点对应一个 app store 区域 这些价格点体现了消费者价格与销售收入 好了 知道了这些内容 我们来用 API 看一下我们的 app 当前的价格表 我们对 v1/apps 做一个 GET 请求 然后是 app 的 ID 和价格关联 我还要把相关价格梯度加进来 这样我们就可以在响应中看到 我执行这个请求之后 就会收到一个价格列表 在这里 我们只有一个价格 开始日期是空的 也就是说目前是有效的 这里是价格梯度关联 这里可以看到这个价格关联到了第一梯度 我们把这个 JSON 数据与我们在 App Store Connect 中看到的对比一下 如果我们仔细看价格表 就可以发现一样的基本信息 我们有一个价格 目前生效中 处在第一梯度 假设我们想要为 app 做一个特别价格促销 从6月29号开始 促销时长一周 一周内 app 免费 也就是说 我们想把价格表做成这样 现在我们就有三个价格了 第一梯度有效期到6月29号 6月29号开始 换到免费梯度 一周后 到了7月6号 我们要改回第一梯度 我们来用 API 更改一下价格表

虽然我们添加了三个价格 但我只想对整个价格表做一个原子变更 我们现在要对 app 做一个补丁请求 我们不是要改变 app 的任何属性 所以就不管属性这个部分了 但是我们要更改价格关联 如果你对 App Store Connect 比较熟悉 你就会知道我们一般会添加 想要关联到我们这个 app 上的资源 ID 但是在这里 app 价格资源还不存在 我们需要创建价格资源 并将其附在 app 上 只用一个请求来完成 因为价格还不存在 还没有 ID 所以我们先用临时的 ID 我们有三个价格 所以我们需要三个临时 ID 我现在要用 new-price-1、new-price-2 和 new-price-3 临时 ID 用什么值设置都可以 重要的是我要用这个语法 用一个美元标志和括号括住这个 ID 这起到的是一个信号的功能 向 API 表明这是一个 尚未存在的资源的临时 ID 我们要在同一个请求下对其进行定义 现在我们需要定义新的 app 价格资源 这是第一个 我们把第一个临时 ID new-price-1 用在这里 也用美元标志的语法 它的开始日期是空的 也就是说 这个价格就是我们现在想要的价格 这里我们也可以先不管开始日期 结果也是一样的 最后我们给它关联到第一梯度 接下来我们来定义第二个价格 第二个价格是这样的 ID 是 new-price-2 开始日期是 6 月 29 日 我们将其关联到第 0 梯度 也就是免费梯度

最后我们来定义 new-price-3 日期是 7 月 6 日 再回到价格梯度 1 大家要记住 我们还没有为这个价格表变更 发出过任何请求 我们还在为我之前提到的这一个原子请求 搭建 JSON 有效负载 这是我们之前在做的请求 现在我们需要把我们刚刚定义过的价格 添加到这个请求中去 我们把一个“included”部分 添加到请求实体中 然后把三个新的价格插入到 这个包含的数组中 最后的有效负载会是这样 屏幕上只能显示这么多 包含的数组中 资源的顺序并不重要 重要的是上边这些临时 ID 要跟下边的临时 ID 一一对应 我们在发出这个请求时 App Store Connect 会创建这三个价格 为其分配真正的 ID 然后关联到 app 上 全靠一个原子操作即可完成 我们来把请求发出去 我们收到了 200 响应 现在已经应用了我们的新价格表 注意 价格变更和可用区域的变更 会立即体现在 App Store 中 如果你的 app 已经发布了 这些变更就会立刻生效 不会等到你的新版本完成 App Review 并发布之后才生效 所以在试用 API 的时候 不要拿已发布的 app 做测试

现在我们来聊聊 app 元数据的编辑 这是 API 中的一个重要领域 有很多端点 我先来给大家大体讲一下

回到我们的“版本”页面 我可以点击“app 信息” 然后就会转到一个页面 可以看到 app 层面的信息 包括本地化的 app 名称 子标题和隐私政策 以及 App Store 分类 如果我们在这里点击版本 就可以看到版本层面的信息 这是在逐平台基础上做更改的元数据 像是截屏、推广文本以及关键词 API 资源模型的运作原理也差不多 这是我们目前看到过的内容 app 还与一个叫作“app 信息” 的资源有关联 这里你可以看到 app 层面的信息 比如说你的 App Store 分类 部分 app 信息做了本地化 所以每一个 app 信息都与 多个 app 信息本地化有关联 每一个对应一个地区 这里你可以找到像是 app 名称 子标题和隐私政策等属性 当然 版本层面也有本地化数据 我们称这类资源为 App Store 版本本地化 版本针对每一个地区 都有一个这种资源 让我们返回 App Store Connect 仔细看一看版本页面 我现在看的是美国英语本地化 如果我们仔细看看截屏和 app 预览 可以看到我们有多个显示类型 像 6.5 英寸的 iPhone 5.5 英寸的 iPhone 或 12.9 英寸的 iPad Pro 在每个显示类型里 我们可以上传最多 3 个预览 和最多 10 张截屏 这些都是在 API 里面进行模型化 也是通过资源和关联 版本本地化与 多个 app 截屏组有关联 一个对应一个显示类型 本地化也有多个 app 预览组 最后 每个截屏组与多张截屏关联 每个预览组与多个预览关联 关于 app 版本元数据还有很多可以聊的 但今天我们要聊的主要资源就是这些

比如说我们想要上传一个 适配 6.5 英寸 iPhone 的 app 预览 美国英语本地化版本来推广我的新一版本

换句话说 我们来找到美国英语本地化 获取 app 预览组 然后在里面加一个预览

每一个版本都有至少一个本地化： 你的 app 的主要地区的版本 我们可以像这样抓取那个本地化 向 appStoreVersionsLocalizations URL 发起一个 GET 请求 获取我们的版本 ID 得到的响应包括所有本地化 其中就有这一个美国英语版本 在下面这里我们可以看到相关的 appPreviewSets URL 发送 GET 请求获取这个 URL 然后我们得到了一个空的数据数组 这就告诉我们这个本地化下面 没有任何 app 预览组 那我们就添加一个 大家可能猜到了 我们向 v1/appPreviewSets 发一个 POST 请求 使用预览类型 IPHONE_65 这代表了 6.5 英寸的 iPhone 链接到我们刚刚通过 ID 找到的本地化 我们发送这个请求 然后预览组就被创建了 现在我们就可以添加一个 app 预览了

我们发送这个请求 然后预览组就被创建了 但预览不只有属性和关联 你还需要上传一个视频文件到 App Store Connect 这是之前在 App Store Connect API 里 从未见过的 API 交互 让我们往后退一步 看看这是怎么实现的 app 预览只是你可以通过这个 API 上传的文件类型之一 你还可以上传截屏、App Review 附件 和 GeoJSON 路由 app 覆盖文件 但不论上传的是什么 最基本的问题都是一样的 就是你的磁盘里要有这个文件 我们把它称之为一个 Asset 你想要把它上传到 App Store Connect 但就卡在互联网这里了 我们的 Asset 上传流程分多个步骤 旨在确保用户能够将大视频文件 以最快速度上传到 App Store Connect 上传过程还要可靠 即使互联网连接信号有时不是那么可靠 是这么实现的 首先先创建一个预留 然后上传真正的 Asset 可能是分成了几个部分的 然后提交 Asset 最后检查错误 我们来试试

通过向 1/appPreviews 发出 POST 请求 创建一个 app 预览预留 然后告诉 App Store Connect 即将要上传的文件的名字 和文件大小 将其链接到我们刚刚创建的预览组 然后 App Store Connect 为这个预览预留一个位置 使用文件大小来创建一组上传操作 对于较小的 Asset 这就很简单 只要进行一个 HTTP PUT 操作 来把数据上传到我们的服务器 但对于较大的 Asset 我们会给你发回一个多步骤的操作 每一个操作就包含相同的属性 一个 HTTP 方法、一个 URL 一个大小长度 一个偏移量大小和一组请求标头 用户拿着这些操作 使用里面的信息 来将自己的 Asset 分成多个部分 一个部分对应一步操作 用户将在每一步操作中使用长度和偏移值 来确定每一部分对应的文件大小区间 注意 大家应该随时做好收到多个操作的准备 我们可能会考量不同因素 来决定需要几个操作 可能大家今天一步上传的 Asset 明天可能就需要几步 所以大家的代码应该随时做好 多步上传的准备

我们的 Asset 被分成几部分以后 我们可以开始第二步了 通过这个方法 每一步上传操作的 URL 和请求标头 用户上传对应的部分 你可以一步一步上传 也可以一次同时上传多个部分

你可以随机上传不同部分 完全没问题 当然 有时候上传会失败 也没问题 再试一次这部分就好 如果只有一个部分上传失败 不需要重新上传其他的部分 不断尝试直至所有的部分都上传成功 一旦上传成功 就可以开始第三步了 那就是提交 Asset 提交 Asset 你需要通过将上传属性设定为 true 为预览 URL 打补丁 及将预览标记为已上传 还需要为初始源文件 提供一个 MD5 校验和 App Store Connect 将用这个校验和 确保每个部分都被正确拆分和上传 我们发送这个请求 然后 App Store Connect 重新拼接这个 Asset 验证校验和 检查文件完整性 例如 这是不是真的是一个视频文件 检查多项指标 如视频长度 维度和音轨 如果都没问题 那这个 Asset 就会被标记为完成 你的 app 预览可以提交审查了 大家记住 Asset 处理是异步的 对于较大的 Asset 可能会花一些时间 可以随时使用 API 重新抓取某个 Asset 查看它的状态

如果我们抓取 app 预览 我们可以在这里查看状态属性 验证一旦成功 Asset 状态会变成完成 如果哪一步发生了错误 状态会变成失败 错误数组会告诉你哪里出了问题 这样你可以删除 Asset、修正问题 然后重新上传 我们今天仔细地讲解了 app 预览 和其他几个 app 元数据相关的资源 但都还是皮毛 可以用 API 管理和修改的元数据 还有很多 大家一定要去看看 说明文档中新的 app 元数据部分 里面有一份完整的 app 和版本元数据相关 API 端点清单 现在我们来聊聊 为新版本添加构建 在 App Store Connect 中 你可以在版本页 就在构建部分这里添加构建 这个构建要放在资源模型的哪里呢？ 就放在这个地方 App Store 版本 跟其相关的构建有一个关联 当然了 你并不是真的通过 API 来创建构建 而是用 Xcode 来创建 并且用 Xcode 或 Transporter 来更新构建 所以假设构建 已经在 App Store Connect 中了 我们只需要查找它的 ID 并将它与版本关联就可以了 现在开始觉得 这些操作看着非常熟悉吧 我要发一个 GET 请求到 v1/builds 路由 然后用 app ID 预发布版本号以及构建版本号筛选 我将从响应中抓取构建 ID 现在我们可以借助这个构建 ID 在新版本中为构建关联打补丁 我们把它发送出去 然后会获得这个 204 无内容的响应 由于这是一个关联更新 因此没有资源数据返回 所以 这是一条成功的响应信息 这条信息告诉我们 构建和版本 ID 是有效的 并且它们彼此已正确关联完毕了 在完成元数据且添加一个构建后 可以提交给 Review 了 在 App Store Connect 中 整个流程分三步 第一步 我们提供联系信息 演示版本账号 以及任何 App Review 所需的备注 第二步 如有需要 我们可以上传附件 最后一步 点击提交以供审核 在 API 中 我们要再次从 App Store 版本出发 它与 App Store Review Details 有一个关联 在 App Store Review Details 中 你可以为 App Review 添加信息 这其中又有多个 App Review 附件 这些工作就像 app 预览一样 可以上传文件至 App Store Connect 如需对一个新版本添加 App Review 详情 只需向 v1/appReviewDetails 发出 POST 请求 提供所需信息并将其与版本关联 这样就行了 现在 App Review 详情 已经附在我们的版本上了 若你已经添加了 App Review 详情 你可以使用一个补丁来编辑它们 编辑该信息的频次由你决定 直到满意 可以提交供审核为止 下面我们看一下如何操作 我们到底该如何使用 API 来点击提交供审核按钮呢？ 我们又有另一个资源 叫做 App Store Version Submission 我们只需创建一个这样的资源 就能够将版本提交至 App Store 向 v1/appStoreVersionSubmissions 发送一个 POST 请求 将其链接到我们的版本 并发送请求 这样就可以了 我们的版本之后就会到 App Review 了 若我们犯了一个错误 想要在 app 审核前将其撤回 删除这个 App Store Version Submission 资源就可以了 当然了 若版本尚未做好准备 例如我们忘记添加截屏了 那么创建一个提交将会失败 并得到一个 400 响应 这个响应将会包含 解释何处需要修改的错误信息 记住 若你的版本存在 App 内购买项目 或 Game Center 配置 这些需要通过 App Store Connect 网站来创建 并且创建应在提交供审核前完成 这就是 app 元数据 API 的全部内容了 希望通过讲解 大家能够了解 这些 API 资源是如何整合在一起的 利用这些资源 我们已经成功创建了一个版本 提供了所有需要的 App Store 信息 并且将它发送给了 App Review 若我们打开了自动发布功能 那么在审核完成之后 我们的 app 能够立即在 App Store 上线 你也可以在网页端通过 App Store Connect 手动发布 或者在 iOS 端也可以

接下来让我们看看全新的 动力和性能 指标及诊断 API 这是 Xcode 中的动力和性能视图 它能够利用从实时用户会话中收集的数据 帮助监测 app 性能指标 如已用内存、发布时间、挂起率 Disk Writes 以及耗电量 你可以使用 API 访问同样的信息 我将为大家概括讲解一下 如何访问这一数据 以及它是如何融入更大的 API 资源模型的 但其实我们有关于这一特性的专题 能够让你更深入地了解全新的 API 包括如何解读响应数据 以及如何洞悉 app 行为 所以一定别忘了查看 “动力与性能 App Store Connect API” 的专题视频 你可以通过从 app URL 请求 perfPowerMetrics 关联 获得 app 最新版本的性能指标 指标数据使用自定义媒体类型 因此你还需要一个正确的 Accept 标头 这一标头能够使你获得 app 最新版本的指标 但你也可以使用构建 URL 上的 perfPowerMetrics 关联 来抓取一个特定构建的指标 不管采用那种方法 一旦发出这一请求 我们将通过一组结构化的指标数据 获取一个成功的响应 这里 我能看到第一组指标是挂起指标 而第一组数据是以秒/小时表示的挂起率 大家可以去看看另一个视频 来了解这个响应的剩余部分 以及学习如何解读这一数据 但我想再给大家展示两个端点 特别是 Disk Writes 一旦发现问题点 你就能够浏览诊断信息 包括调用栈 来帮助找出潜在问题的来源 在 Xcode 中 我们展示了诊断签名列表 这是你在 app 中做 disk writes 的地方 这些签名按占总 Disk Writes 写入量的百分比排序 因此写入量占比最大的在最上方 对于每个诊断签名而言 你可以查看实际的调用栈 以及额外的诊断详情 你可以使用 API 来获得同样的信息 再一次 我们从构建 URL 开始 我们抓取了它的新 diagnosticSignatures 关联 让我们获取一下 API 通过诊断签名列表做出响应 这些是标准的 App Store Connect API 资源 它们有一个签名属性 这标记出了运行时间内 disk write 发生的位置 以及一个权重 表明这个签名对总写入量的贡献大小 每个签名同样跟其日志数据有一个关联 若我们使用这个链接 并再次使用这个自定义媒体类型 我们能够得到诊断数据 除 app 信息和总 disk writes 之外 你能在这个响应中找到详细的调用栈 这就是 app 元数据 以及动力和性能 指标及诊断 API 的全部内容 这些综合在一起就是 App Store Connect API 的一次重大更新 期待收到各位使用新功能的反馈 谢谢大家