<p data-line="0" class="code-line">こちらの記事は「MEDLEY Summer Tech Blog Relay」の７日目の記事です。</p>
<p data-line="2" class="code-line"><span class="embed-block zenn-embedded zenn-embedded-card"><iframe id="zenn-embedded__d6e1f8d4bbb12" src="https://embed.zenn.studio/card#zenn-embedded__d6e1f8d4bbb12" data-content="https%3A%2F%2Fdeveloper.medley.jp%2Fentry%2F2025%2F08%2F15%2F20250815%2F" frameborder="0" scrolling="no" loading="lazy"></iframe></span><a href="https://developer.medley.jp/entry/2025/08/15/20250815/" style="display:none" target="_blank" rel="nofollow noopener noreferrer">https://developer.medley.jp/entry/2025/08/15/20250815/</a></p>
<p data-line="4" class="code-line">こんにちは、メドレーでデータエンジニアをしている山邉（<a href="https://github.com/beniyama" target="_blank" rel="nofollow noopener noreferrer">@beniyama</a>）です。</p>
<p data-line="6" class="code-line">先日、<a href="https://developer.medley.jp/entry/2025/07/24/120228/" target="_blank" rel="nofollow noopener noreferrer">BigQuery Data Transfer Service を通して学ぶ Google 広告のデータモデル</a> という記事をテックブログで公開しましたが、今回は <a href="https://appstoreconnect.apple.com/" target="_blank" rel="nofollow noopener noreferrer">App Store Connect</a> のデータを BigQuery に連携するための Tips をいくつかご紹介できればと思います（ちなみに Zenn は初投稿です！）。</p>
<h1 id="%E8%83%8C%E6%99%AF" data-line="8" class="code-line">
<a class="header-anchor-link" href="#%E8%83%8C%E6%99%AF" aria-hidden="true"></a> 背景</h1>
<p data-line="10" class="code-line"><a href="https://developer.medley.jp/entry/2025/07/24/120228/" target="_blank" rel="nofollow noopener noreferrer">先日の記事</a>にも記載の通り、弊社では Google BigQuery を中心としたデータ基盤を構築しています。今回もアプリの統計情報を連携して BI から見られるようにしたい、というリクエストをきっかけに調査をしたものです。</p>
<p data-line="12" class="code-line">連携対象は <a href="https://appstoreconnect.apple.com/" target="_blank" rel="nofollow noopener noreferrer">App Store Connect</a> で、本当は <a href="https://play.google.com/console" target="_blank" rel="nofollow noopener noreferrer">Google Play Console</a> も合わせて書きたかったのですが、思いのほか長文になってしまったため次回のネタに残しておこうと思います。また前回は <a href="https://cloud.google.com/bigquery/docs/dts-introduction?hl=ja" target="_blank" rel="nofollow noopener noreferrer">BigQuery Data Transfer Service (DTS)</a> を使いましたが、今回はコネクタをサポートしている <a href="https://trocco.io/" target="_blank" rel="nofollow noopener noreferrer">Trocco</a> で実装をしています。</p>
<aside class="msg message"><span class="msg-symbol">!</span><div class="msg-content">
<p data-line="15" class="code-line">本記事は 2025-08-28 時点での情報であり、最新のサービス仕様に関して動作を保証するものではありませんので、ご注意ください。</p>
</div></aside>
<h1 id="%E6%89%8B%E9%A0%86" data-line="18" class="code-line">
<a class="header-anchor-link" href="#%E6%89%8B%E9%A0%86" aria-hidden="true"></a> 手順</h1>
<h2 id="1.-app-store-connect-%E3%81%AB%E6%8B%9B%E5%BE%85%E3%81%97%E3%81%A6%E3%82%82%E3%82%89%E3%81%86" data-line="20" class="code-line">
<a class="header-anchor-link" href="#1.-app-store-connect-%E3%81%AB%E6%8B%9B%E5%BE%85%E3%81%97%E3%81%A6%E3%82%82%E3%82%89%E3%81%86" aria-hidden="true"></a> 1. App Store Connect に招待してもらう</h2>
<p data-line="22" class="code-line">連携設定だけであれば後述のチーム API キーがあれば可能ですが、コンソールと付き合わせた数値確認は必要なのでストアに招待してもらいましょう。個人の権限としてはレポートの確認だけできれば十分なので『Access to Reports』あたりで良いと思います。</p>
<h2 id="2.-%E3%83%81%E3%83%BC%E3%83%A0-api-%E3%82%AD%E3%83%BC%E3%81%AE%E7%99%BA%E8%A1%8C" data-line="24" class="code-line">
<a class="header-anchor-link" href="#2.-%E3%83%81%E3%83%BC%E3%83%A0-api-%E3%82%AD%E3%83%BC%E3%81%AE%E7%99%BA%E8%A1%8C" aria-hidden="true"></a> 2. チーム API キーの発行</h2>
<p data-line="26" class="code-line">App Store Connect には『チーム API キー』と『個人 API キー』の２種がありますが、この後の連携設定で使用する Issuer ID を持つのはチーム API キーのみになります。</p>
<p data-line="28" class="code-line"><strong>チーム API キーの作成には Admin ロールが必要です</strong>（<a href="https://developer.apple.com/documentation/appstoreconnectapi/creating-api-keys-for-app-store-connect-api#Generate-a-Team-Key-and-Assign-It-a-Role" target="_blank" rel="nofollow noopener noreferrer">参考</a>）。また、チーム API キーは App Store Connect 全体で管理されるキーで、<strong>個々のアプリ単位でのアクセス制御（例えば特定のアプリのレポートだけ連携できるようにするなど）はできない</strong>ようなのでご注意ください。</p>
<h2 id="3.-%E5%8F%96%E5%BE%97%E3%81%97%E3%81%9F%E3%81%84%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88%E3%81%A8-api-%E3%82%92%E6%8E%A2%E3%81%99" data-line="30" class="code-line">
<a class="header-anchor-link" href="#3.-%E5%8F%96%E5%BE%97%E3%81%97%E3%81%9F%E3%81%84%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88%E3%81%A8-api-%E3%82%92%E6%8E%A2%E3%81%99" aria-hidden="true"></a> 3. 取得したいレポートと API を探す</h2>
<p data-line="32" class="code-line">App Store Connect にはファイナンスレポートを始めとした様々なレポート、それに紐づくエンドポイントが用意されており、データ連携をする上でまずどのレポートを取得するかを決める必要があります。</p>
<p data-line="34" class="code-line">例えば、アプリのダウンロードデータを取得したい場合には <a href="https://developer.apple.com/help/app-store-connect/view-sales-and-trends/download-and-view-reports" target="_blank" rel="nofollow noopener noreferrer">Download and view reports</a> 内の <a href="https://developer.apple.com/help/app-store-connect/reference/summary-sales-report" target="_blank" rel="nofollow noopener noreferrer">Summary Sales Report</a> が対象です。その上で対応する API を調べると <a href="https://developer.apple.com/documentation/appstoreconnectapi/get-v1-salesreports" target="_blank" rel="nofollow noopener noreferrer">Download Sales and Trends Reports</a> となります（ページ中の <em>For more details on each report type, see Download and view reports.</em> から上述のレポート詳細に行けます）。</p>
<p data-line="36" class="code-line">またここで</p>
<blockquote data-line="38" class="code-line">
<p data-line="38" class="code-line">These endpoints require a Team key and aren’t usable with an Individual key.</p>
</blockquote>
<p data-line="40" class="code-line">とあり、ここで初めて個人 API キーではダメだということを理解します…</p>
<aside class="msg message"><span class="msg-symbol">!</span><div class="msg-content">
<p data-line="43" class="code-line">このレポートと API の対応関係がとてもわかりづらくて行ったり来たりを繰り返しました…</p>
</div></aside>
<h2 id="4.-api-%E3%82%B3%E3%83%BC%E3%83%AB%E6%99%82%E3%81%AE%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%82%92%E6%B1%BA%E3%82%81%E3%82%8B" data-line="46" class="code-line">
<a class="header-anchor-link" href="#4.-api-%E3%82%B3%E3%83%BC%E3%83%AB%E6%99%82%E3%81%AE%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%82%92%E6%B1%BA%E3%82%81%E3%82%8B" aria-hidden="true"></a> 4. API コール時のパラメータを決める</h2>
<p data-line="48" class="code-line">さて、<a href="https://developer.apple.com/documentation/appstoreconnectapi/get-v1-salesreports#Allowed-values-based-on-sales-report-type" target="_blank" rel="nofollow noopener noreferrer">API がサポートするレポートタイプ</a>を見ると、パラメータ（reportType / reportSubType / frequency / version）の組み合わせで取得できるレポートが決まることがわかります。</p>
<p data-line="50" class="code-line">例えば、この INSTALLS という reportType でできる限り詳細（DETAILED）なものを取得しようと思うと、MONTHLY（五行目）しか選択肢がないという意味になります（他のレポートには DAILY もある）。</p>
<table data-line="52" class="code-line">
<thead data-line="52" class="code-line">
<tr data-line="52" class="code-line">
<th>reportType</th>
<th>reportSubType</th>
<th>frequency</th>
<th>version</th>
</tr>
</thead>
<tbody data-line="54" class="code-line">
<tr data-line="54" class="code-line">
<td>INSTALLS</td>
<td>SUMMARY_CHANNEL</td>
<td>YEARLY</td>
<td>1_0, 1_1</td>
</tr>
<tr data-line="55" class="code-line">
<td>INSTALLS</td>
<td>SUMMARY_INSTALL_TYPE</td>
<td>YEARLY</td>
<td>1_0, 1_1</td>
</tr>
<tr data-line="56" class="code-line">
<td>INSTALLS</td>
<td>SUMMARY</td>
<td>MONTHLY</td>
<td>1_2</td>
</tr>
<tr data-line="57" class="code-line">
<td>INSTALLS</td>
<td>SUMMARY_TERRITORY</td>
<td>YEARLY</td>
<td>1_0, 1_1</td>
</tr>
<tr data-line="58" class="code-line">
<td>INSTALLS</td>
<td>DETAILED</td>
<td>MONTHLY</td>
<td>1_0, 1_1</td>
</tr>
<tr data-line="59" class="code-line">
<td>INSTALLS</td>
<td>DETAILED</td>
<td>YEARLY</td>
<td>1_2</td>
</tr>
</tbody>
</table>
<p data-line="61" class="code-line">この辺のパラメータに関しては <a href="https://documents.trocco.io/docs/data-source-app-store-connect-api?highlight=app%20store" target="_blank" rel="nofollow noopener noreferrer">Trocco のヘルプページ</a> にも記載はありますが、App Store Connect 側の API バージョンも変わり続けているため、両方ご確認されることをオススメします。</p>
<p data-line="63" class="code-line">そこで今回は下記の設定をすることにしました。</p>
<ul data-line="65" class="code-line">
<li data-line="65" class="code-line">reportType : SALES</li>
<li data-line="66" class="code-line">reportSubType : SUMMARY</li>
<li data-line="67" class="code-line">frequency : DAILY</li>
</ul>
<h2 id="5.-trocco-%E3%81%A7%E9%80%A3%E6%90%BA%E8%A8%AD%E5%AE%9A%E3%82%92%E8%A1%8C%E3%81%86" data-line="69" class="code-line">
<a class="header-anchor-link" href="#5.-trocco-%E3%81%A7%E9%80%A3%E6%90%BA%E8%A8%AD%E5%AE%9A%E3%82%92%E8%A1%8C%E3%81%86" aria-hidden="true"></a> 5. Trocco で連携設定を行う</h2>
<p data-line="71" class="code-line">ここまでくれば後は Trocco の設定を行うだけです。サンプルとして以下のような設定をしています。</p>
<p data-line="73" class="code-line"><img src="https://storage.googleapis.com/zenn-user-upload/6c354f86e559-20250828.png" alt="Trocco の設定画面" class="md-img" loading="lazy"></p>
<p data-line="75" class="code-line">ポイントは以下です。</p>
<h3 id="%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88%E6%8F%90%E4%BE%9B%E6%99%82%E9%96%93%E3%81%AB%E6%B0%97%E3%82%92%E3%81%A4%E3%81%91%E3%82%8B" data-line="77" class="code-line">
<a class="header-anchor-link" href="#%E3%83%AC%E3%83%9D%E3%83%BC%E3%83%88%E6%8F%90%E4%BE%9B%E6%99%82%E9%96%93%E3%81%AB%E6%B0%97%E3%82%92%E3%81%A4%E3%81%91%E3%82%8B" aria-hidden="true"></a> レポート提供時間に気をつける</h3>
<p data-line="79" class="code-line">例えば<a href="https://developer.apple.com/help/app-store-connect/view-sales-and-trends/view-subscription-data/" target="_blank" rel="nofollow noopener noreferrer">このページ</a>に</p>
<blockquote data-line="81" class="code-line">
<p data-line="81" class="code-line">Time Zone: Data is shown in Pacific Time (PT). A day includes transactions that happened from 12:00 a.m. to 11:59 p.m. PT.</p>
</blockquote>
<p data-line="83" class="code-line">と記載があるように、<strong>App Store Connect 側のレポートが作成されるのは Pacific Time (PT) 時間（日本とは夏時間で16時間、通常時は17時間の時差）</strong> になります。</p>
<p data-line="85" class="code-line">そのため集計対象が締まるのが日本時間の 17:00 目安になるのですが、たまたまレポートが生成されていない状態で呼んだ API からのエラーメッセージの中に</p>
<blockquote data-line="87" class="code-line">
<p data-line="87" class="code-line">Report is not available yet. Daily reports for the Americas are available by 5 am Pacific Time; Japan, Australia, and New Zealand by 5 am Japan Standard Time; and 5 am Central European Time for all other territories.</p>
</blockquote>
<p data-line="89" class="code-line">などと書いてあり、日次レポートは翌日の 05:00（日本時間）に出来上がることがわかります（これは自分の調べた限りドキュメントには明記されていなかったのと、今後変わる可能性も十分ありそうです）。なので、例えば日本時間の 05:00 過ぎあたりに定期連携するのであれば、<strong>都合２日前の日付が連携対象となります</strong>。</p>
<h3 id="bigquery-%E5%81%B4%E3%81%AE%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%81%AE%E5%91%BD%E5%90%8D%E3%81%A8%E5%8F%97%E3%81%91%E6%96%B9%E3%82%92%E8%80%83%E3%81%88%E3%82%8B" data-line="91" class="code-line">
<a class="header-anchor-link" href="#bigquery-%E5%81%B4%E3%81%AE%E3%83%86%E3%83%BC%E3%83%96%E3%83%AB%E3%81%AE%E5%91%BD%E5%90%8D%E3%81%A8%E5%8F%97%E3%81%91%E6%96%B9%E3%82%92%E8%80%83%E3%81%88%E3%82%8B" aria-hidden="true"></a> BigQuery 側のテーブルの命名と受け方を考える</h3>
<p data-line="93" class="code-line">上述の通り、レポートは reportType x reportSubType x frequency の組み合わせとなりますので、今後新しいレポートを連携したくなったときにも迷わないように、sales_summary_daily のような <code>{reportType}_{reportSubType}_{frequency}</code> の形でテーブル名をつけています。</p>
<p data-line="95" class="code-line">また、連携も <code>sales_summary_daily$$target_date_bq$</code> のように begin_date カラムを パーティション ID にした日単位のパーティションを設定し、REPLACE 連携とすることで複数回実行しても冪等になるようにしています。</p>
<h3 id="%E3%82%AB%E3%83%A9%E3%83%A0%E3%81%AE%E6%84%8F%E5%91%B3%E3%81%AB%E6%B0%97%E3%82%92%E3%81%A4%E3%81%91%E3%82%8B" data-line="97" class="code-line">
<a class="header-anchor-link" href="#%E3%82%AB%E3%83%A9%E3%83%A0%E3%81%AE%E6%84%8F%E5%91%B3%E3%81%AB%E6%B0%97%E3%82%92%E3%81%A4%E3%81%91%E3%82%8B" aria-hidden="true"></a> カラムの意味に気をつける</h3>
<p data-line="99" class="code-line">連携されたテーブルには <code>product_type_identifier</code> という STRING のカラムがあり、集計時にはこれをフィルタして対象を絞る必要があります。</p>
<p data-line="101" class="code-line">Product type identifier の示すタイプは<a href="https://developer.apple.com/help/app-store-connect/reference/product-type-identifiers/" target="_blank" rel="nofollow noopener noreferrer">リファレンス</a>に記載があり、ぱっと見ではわからない感じの体系でネーミングされています。</p>
<p data-line="103" class="code-line">例えばダウンロード数を取得するためのクエリは</p>
<div class="code-block-container"><pre class="language-sql"><code class="language-sql code-line" data-line="105"><span class="token keyword">SELECT</span>
  begin_date<span class="token punctuation">,</span>
  device<span class="token punctuation">,</span>
  version<span class="token punctuation">,</span>
  units<span class="token punctuation">,</span>
<span class="token keyword">FROM</span>
<span class="token identifier"><span class="token punctuation">`</span>&lt;PROJECT ID&gt;.&lt;DATASET ID&gt;.sales_summary_daily<span class="token punctuation">`</span></span> 
<span class="token keyword">WHERE</span>
  product_type_identifier <span class="token operator">=</span> <span class="token string">'1'</span> <span class="token comment">-- ダウンロードに絞る</span>
<span class="token keyword">ORDER</span> <span class="token keyword">BY</span>
  <span class="token number">1</span><span class="token punctuation">,</span> <span class="token number">2</span><span class="token punctuation">,</span> <span class="token number">3</span>
</code></pre></div><p data-line="119" class="code-line">のようになります。</p>
<p data-line="121" class="code-line">また、begin_date と end_date というカラムをそのまま連携すると BigQuery 上ではタイムスタンプとして見える（<a href="https://developer.apple.com/help/app-store-connect/reference/summary-sales-report" target="_blank" rel="nofollow noopener noreferrer">もともとは Date 型の様子</a>）のですが、前述の通り PT 時間の日付を示すカラムのはずなので注意が必要です。</p>
<h1 id="%E3%81%BE%E3%81%A8%E3%82%81" data-line="123" class="code-line">
<a class="header-anchor-link" href="#%E3%81%BE%E3%81%A8%E3%82%81" aria-hidden="true"></a> まとめ</h1>
<p data-line="125" class="code-line">Trocco を活用した App Store Connect 連携を見てきましたがいかがでしたでしょうか？</p>
<p data-line="127" class="code-line">ポイントとしては</p>
<ul data-line="129" class="code-line">
<li data-line="129" class="code-line">連携にはチーム API キーが必要</li>
<li data-line="130" class="code-line">取得したいレポートと API 仕様をよく見比べる（特に取得可能なレポートタイプ）</li>
<li data-line="131" class="code-line">レポートは Pacific Time 基準で作成され、さらに日本時間から２日程度ラグがある</li>
</ul>
<p data-line="133" class="code-line">あたりでしょうか。</p>
<p data-line="135" class="code-line">外部システムとのデータ連携は、ブラックボックスになりがちな先方の API 仕様や、明文化されていない実装でハマることが多いため、何かしらのお役に立てれば幸いです。また、実際は連携部分の開発もする必要があるところですが、そこは Trocco のおかげであまり気にしなくて良いと言うのはマネージドサービスならではのメリットですね。</p>
<p data-line="137" class="code-line">こういった地味な？ところはまだまだ AI にお任せできないな…と思いつつ、次は Google Play Console 編を書こうと思います。</p>
<p data-line="139" class="code-line">さて明日の MEDLEY Summer Tech Blog Relay 記事は医療プラットフォーム本部の内堀さんです！引き続きブログリレーをお楽しみに！</p>


Trocco で  App Store Connect のデータを BigQuery に連携する

1. App Store Connect に招待してもらう

3. 取得したいレポートと API を探す

4. API コール時のパラメータを決める

レポート提供時間に気をつける

BigQuery 側のテーブルの命名と受け方を考える

Discussion