Expanding automation with the App Store Connect API

ハイライト

2020 年、App Store Connect API は 200 以上のエンドポイントを追加し、App バージョンのメタデータ、スクリーンショットとプレビューのアップロード、審査提出、Xcode の Power and Performance 指標を自動化に開放しました。ただし手動リリース、App 内課金、Game Center の設定は引き続き Web で行います。

主要内容

App Store Connect API が最初に解決したのは、繰り返しのバックオフィス作業です。チームユーザーの管理、provisioning profile の作成、beta tester の追加と削除、売上と財務レポートのダウンロードです。これらをスクリプト化すると、リリース準備の手作業は大きく減ります。しかし重要な一部は Web に残りました。新バージョンの作成、App Store メタデータの維持、スクリーンショットとプレビューのアップロード、審査への提出です。(00:35)

2020 年の変化は、このリリース経路を API に取り込んだことです。Apple は 200 以上のエンドポイントを追加し、既存 API の 2 倍を超えました。App Metadata API は App カテゴリ、全世界の提供地域、主言語、ライセンス契約、バージョン作成、プラットフォーム追加、スクリーンショットと app preview のアップロード、名称・説明・キーワードなどのローカライズ情報をカバーします。新バージョン作成から App Review 提出までが範囲です。(01:02)

デモの Forest Explorer は実際のリリース例です。新バージョンを作り、価格を変更し、メタデータを更新し、アップロード済み build を関連付け、審査に提出します。この順序は CI/CD やリリーススクリプトに適しており、各ステップで明確な HTTP 応答が得られ、失敗時は特定リソースで止まります。(03:17)

同じセッションでは Power and Performance Metrics and Diagnostics API も追加されました。Xcode Organizer がメモリ、起動時間、hang rate、ディスク書き込み、消費電力を分析する背後の集約データを公開します。チームは本番の性能トレンドを独自 dashboard、バグシステム、回帰チェックに接続できます。(22:39)

境界も明確です。手動リリースは App Store Connect の Web または iOS App で行い、App 内課金と Game Center の設定も Web です。価格と提供地域の変更は即座に本番 App に影響するため、live app で実験してはいけません。(02:00、11:06)

詳細

App Store バージョンの作成

（04:16）バージョン作成の起点は Apps リソースです。各 App には App Store Versions があり、各バージョンには platform と versionString があります。デモは bundle ID で App ID を検索し、App Store Version を作成します。

GET /v1/apps?filter[bundleID]=com.example.ForestExplorer

200 OK
response data:
  app id: {appId}

キーポイント:

デモの filter[bundleID] は対象 App を特定します。
応答の app id はドキュメントでも使われる Apple ID で、以降のバージョン、価格、build 関連付けに使います。
このステップは読み取りのみで、リリーススクリプトの最初の検証点に適しています。

POST /v1/appStoreVersions

platform: IOS
versionString: 2.0
app relationship: {appId}

201 CREATED
response data:
  app store version id: {versionId}

キーポイント:

platform、versionString、app relationship は transcript が明示した作成情報です。
201 CREATED は App Store Connect がバージョンを作成したことを意味し、Web にログインするとサイドバーに表示されます。
返る version id はローカライズ、build 関連付け、審査提出の主リソースです。

1 回の PATCH で価格スケジュールを原子的に更新する

（07:17）価格スケジュールは App Prices と Price Tier で構成されます。現在価格の startDate は null で、将来価格には生效日があります。デモは現在価格を読み、関連 priceTier を include します。

GET /v1/apps/{appId}/prices?include=priceTier

200 OK
response data:
  price startDate: null
  priceTier: Tier 1

キーポイント:

startDate: null は現在有効な価格を表します。
priceTier は App Store Connect の All Prices and Currencies ページと一致する読み取り専用参照です。
priceTier を include すると、1 回の応答で価格階層関係を取得できます。

（08:24）1 週間の無料プロモーションでは、3 回の作成リクエストではなく App へ 1 回 PATCH し、3 つの新価格を同一変更として送ります。

PATCH /v1/apps/{appId}

relationships.prices:
  - ${new-price-1}
  - ${new-price-2}
  - ${new-price-3}

included:
  - id: ${new-price-1}
    startDate: null
    priceTier: Tier 1
  - id: ${new-price-2}
    startDate: 2020-06-29
    priceTier: Tier 0
  - id: ${new-price-3}
    startDate: 2020-07-06
    priceTier: Tier 1

200 OK

キーポイント:

${...} は同一リクエスト内の未作成リソースを参照する一時 ID 構文です。
included の 3 リソースは App Store Connect が作成し、実 ID を割り当て、App にリンクします。
価格と提供地域の変更は即座に反映されるため、本番 App 向けテストには環境保護を入れます。

App Preview アップロードの 4 ステップ

（13:33）メタデータは App レベルとバージョンレベルに分かれます。ローカライズ名、subtitle、プライバシーポリシーは App Info Localizations、スクリーンショット、promotional text、キーワード、app preview は App Store Version Localization です。デモは US English の 6.5 インチ iPhone app preview です。

GET /v1/appStoreVersions/{versionId}/appStoreVersionLocalizations
GET {appPreviewSets relationship URL}

POST /v1/appPreviewSets
previewType: IPHONE_65
localization relationship: {localizationId}

キーポイント:

各バージョンには少なくとも 1 つのローカライズ、つまり主言語の localization があります。
appPreviewSets が空配列なら、先に preview set を作成します。
IPHONE_65 はデモの 6.5 インチ iPhone 用 previewType です。

（15:45）動画ファイルのアップロードは 4 段階です。reservation 作成、1 つ以上の part アップロード、asset commit、エラー確認です。

POST /v1/appPreviews

file name: ForestExplorer.mov
file size in bytes: <bytes>
appPreviewSet relationship: {previewSetId}

response upload operations:
  method
  url
  length in bytes
  offset in bytes
  request headers

キーポイント:

reservation ではファイル名とバイトサイズを伝えます。
応答に upload operations が返り、小ファイルは 1 操作、大ファイルは複数になることがあります。
クライアントは length と offset で分割し、各 operation の method、URL、headers を使います。

for each upload operation:
  read bytes from offset with length
  upload that part with the provided method, URL, and headers
  retry only the failed part when a part upload fails

キーポイント:

複数 part の順序は問いません。並列アップロードも可能です。
失敗した part だけ再試行し、成功済み part は再アップロード不要です。
常に複数 operation を前提に設計します。今日 1 分割でも明日は複数分割になることがあります。

PATCH /v1/appPreviews/{previewId}

uploaded: true
source file MD5 checksum: <checksum>

キーポイント:

commit では uploaded を true にし、元ファイルの MD5 checksum を送ります。
App Store Connect は asset を再構成し、checksum、整合性、動画長、サイズ、音轨を検証します。
処理は非同期です。asset を再取得し state が COMPLETE になるまで待ち、FAILED なら errors array を見て削除・修正・再アップロードします。

build を関連付けて審査に提出する

（19:49）build 自体は Xcode または Transporter でアップロードします。API は build id を検索し、新バージョンに紐づけます。

GET /v1/builds

filters:
  app ID: {appId}
  pre-release version number: {preReleaseVersion}
  build version number: {buildNumber}

キーポイント:

デモは app ID、pre-release version number、build version number の 3 条件で build を特定します。
応答の build id がバージョン関係の更新に使われます。
CI がアップロードした build が App Store Connect に入ったか確認するステップです。

PATCH /v1/appStoreVersions/{versionId}/relationships/build

build id: {buildId}

204 NO CONTENT

キーポイント:

204 NO CONTENT は関係更新成功で、リソース本文は返りません。
build id と version id が有効であることを確認できます。
メタデータと build が揃って初めて審査提出の条件を満たします。

（21:00）App Review には連絡先、デモアカウント、メモ、必要な添付が依然必要です。API では App Review Details、App Review Attachments、App Store Version Submission に対応します。

POST /v1/appReviewDetails
version relationship: {versionId}

POST /v1/appStoreVersionSubmissions
version relationship: {versionId}

DELETE /v1/appStoreVersionSubmissions/{submissionId}

キーポイント:

Review details は提出前に何度でも PATCH できます。
App Store Version Submission の作成は Submit for Review をクリックするのと同等です。
誤りがあれば submission を DELETE で撤回できます。スクリーンショット不足などで作成時は 400 とエラー説明が返ります。

Power and Performance 指標と診断の読み取り

（23:21）Power and Performance API は Xcode Power and Performance ビューの背後にある集約データを読みます。入口は App でも build でも構いません。

GET /v1/apps/{appId}/perfPowerMetrics
Accept: <Power and Performance custom media type>

GET /v1/builds/{buildId}/perfPowerMetrics
Accept: <Power and Performance custom media type>

キーポイント:

App URL の perfPowerMetrics 関係から最近バージョンの指標を読みます。
build URL の perfPowerMetrics 関係から特定 build の指標を読みます。
transcript は応答に HANG metrics があると述べ、hang rate の単位は seconds per hour です。

（24:09）ディスク書き込みには diagnostic signatures と log data もあり、「書き込み増加」から具体的なコールスタックへ進めます。

GET /v1/builds/{buildId}/diagnosticSignatures

response data:
  signature
  weight
  log data relationship

GET {log data relationship URL}
Accept: <Power and Performance custom media type>

キーポイント:

diagnostic signatures は総ディスク書き込みへの寄与で並び、最大寄与が先頭です。
signature は実行時の書き込み位置、weight は総書き込みへの寄与です。
log data 応答には App 情報、総ディスク書き込み、詳細 call stack が含まれ、原因特定に使えます。

重要ポイント

やること: リリース草案作成を CI に取り込む。価値: デモの主経路は app id 検索、バージョン作成、build 関連付けから App Review submission まで続き、「リリース準備」を Web クリックから監査可能なスクリプトにできます。始め方: まず GET /v1/apps?filter[bundleID]=... と POST /v1/appStoreVersions を実装し、返る {versionId} をリリースパイプラインログに記録します。
やること: 価格プロモーションのスケジュールスクリプトを作る。価値: 価格スケジュールは 1 回の PATCH で原子的に更新でき、途中で価格ノードが一部だけ作られるのを避けられます。始め方: まず /v1/apps/{appId}/prices?include=priceTier を読み、一時 ID ${new-price-*} で完全なプロモーション周期を生成します。本番 App へのテスト payload 禁止の環境保護を入れます。
やること: 多言語メタデータをリポジトリから App Store Connect に同期する。価値: App Info Localizations と App Store Version Localizations は名称、subtitle、プライバシーポリシー、スクリーンショット、キーワード、promotional text をカバーし、ローカライズファイルと一緒にコードレビューに載せられます。始め方: locale ごとに version localizations を読み、まず 1 市場の名称とキーワードだけ同期し、審査フロー確認後にスクリーンショットと preview set を接続します。
やること: 再開可能な素材アップロード worker を実装する。価値: app preview、スクリーンショット、App Review attachments、GeoJSON routing app coverage files はいずれも reservation、part upload、commit、error check の流れです。始め方: upload operations を offset と length のタスクキューにし、失敗 part だけ再試行します。commit 後に state をポーリングし、FAILED では errors array をビルドログに書きます。
やること: 本番性能指標をチーム dashboard に接続する。価値: perfPowerMetrics と diagnosticSignatures で Xcode Organizer の集約データを独自ツールに入れ、hang rate、ディスク書き込み、call stack を回帰アラートにできます。始め方: まず App レベルの perfPowerMetrics で最近バージョンのトレンドを取得し、異常 build に diagnosticSignatures と log data を要求し、signature、weight、call stack をチケットに紐づけます。

Expanding automation with the App Store Connect API

ハイライト

主要内容

詳細

App Store バージョンの作成

1 回の PATCH で価格スケジュールを原子的に更新する

App Preview アップロードの 4 ステップ

build を関連付けて審査に提出する

Power and Performance 指標と診断の読み取り

重要ポイント

関連セッション

コメント