こちらの記事は「MEDLEY Summer Tech Blog Relay」の７日目の記事です。
こんにちは、メドレーでデータエンジニアをしている山邉（@beniyama）です。
先日、BigQuery Data Transfer Service を通して学ぶ Google 広告のデータモデル という記事をテックブログで公開しましたが、今回は App Store Connect のデータを BigQuery に連携するための Tips をいくつかご紹介できればと思います（ちなみに Zenn は初投稿です！）。
背景
先日の記事にも記載の通り、弊社では Google BigQuery を中心としたデータ基盤を構築しています。今回もアプリの統計情報を連携して BI から見られるようにしたい、というリクエストをきっかけに調査をしたものです。
連携対象は App Store Connect で、本当は Google Play Console も合わせて書きたかったのですが、思いのほか長文になってしまったため次回のネタに残しておこうと思います。また前回は BigQuery Data Transfer Service (DTS) を使いましたが、今回はコネクタをサポートしている Trocco で実装をしています。
手順
1. App Store Connect に招待してもらう
連携設定だけであれば後述のチーム API キーがあれば可能ですが、コンソールと付き合わせた数値確認は必要なのでストアに招待してもらいましょう。個人の権限としてはレポートの確認だけできれば十分なので『Access to Reports』あたりで良いと思います。
2. チーム API キーの発行
App Store Connect には『チーム API キー』と『個人 API キー』の２種がありますが、この後の連携設定で使用する Issuer ID を持つのはチーム API キーのみになります。
チーム API キーの作成には Admin ロールが必要です（参考）。また、チーム API キーは App Store Connect 全体で管理されるキーで、個々のアプリ単位でのアクセス制御（例えば特定のアプリのレポートだけ連携できるようにするなど）はできないようなのでご注意ください。
3. 取得したいレポートと API を探す
App Store Connect にはファイナンスレポートを始めとした様々なレポート、それに紐づくエンドポイントが用意されており、データ連携をする上でまずどのレポートを取得するかを決める必要があります。
例えば、アプリのダウンロードデータを取得したい場合には Download and view reports 内の Summary Sales Report が対象です。その上で対応する API を調べると Download Sales and Trends Reports となります（ページ中の For more details on each report type, see Download and view reports. から上述のレポート詳細に行けます）。
またここで
These endpoints require a Team key and aren’t usable with an Individual key.
とあり、ここで初めて個人 API キーではダメだということを理解します…
4. API コール時のパラメータを決める
さて、API がサポートするレポートタイプを見ると、パラメータ（reportType / reportSubType / frequency / version）の組み合わせで取得できるレポートが決まることがわかります。
例えば、この INSTALLS という reportType でできる限り詳細（DETAILED）なものを取得しようと思うと、MONTHLY（五行目）しか選択肢がないという意味になります（他のレポートには DAILY もある）。
| reportType | reportSubType | frequency | version |
|---|---|---|---|
| INSTALLS | SUMMARY_CHANNEL | YEARLY | 1_0, 1_1 |
| INSTALLS | SUMMARY_INSTALL_TYPE | YEARLY | 1_0, 1_1 |
| INSTALLS | SUMMARY | MONTHLY | 1_2 |
| INSTALLS | SUMMARY_TERRITORY | YEARLY | 1_0, 1_1 |
| INSTALLS | DETAILED | MONTHLY | 1_0, 1_1 |
| INSTALLS | DETAILED | YEARLY | 1_2 |
この辺のパラメータに関しては Trocco のヘルプページ にも記載はありますが、App Store Connect 側の API バージョンも変わり続けているため、両方ご確認されることをオススメします。
そこで今回は下記の設定をすることにしました。
- reportType : SALES
- reportSubType : SUMMARY
- frequency : DAILY
5. Trocco で連携設定を行う
ここまでくれば後は Trocco の設定を行うだけです。サンプルとして以下のような設定をしています。
ポイントは以下です。
レポート提供時間に気をつける
例えばこのページに
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.
と記載があるように、App Store Connect 側のレポートが作成されるのは Pacific Time (PT) 時間（日本とは夏時間で16時間、通常時は17時間の時差） になります。
そのため集計対象が締まるのが日本時間の 17:00 目安になるのですが、たまたまレポートが生成されていない状態で呼んだ API からのエラーメッセージの中に
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.
などと書いてあり、日次レポートは翌日の 05:00（日本時間）に出来上がることがわかります（これは自分の調べた限りドキュメントには明記されていなかったのと、今後変わる可能性も十分ありそうです）。なので、例えば日本時間の 05:00 過ぎあたりに定期連携するのであれば、都合２日前の日付が連携対象となります。
BigQuery 側のテーブルの命名と受け方を考える
上述の通り、レポートは reportType x reportSubType x frequency の組み合わせとなりますので、今後新しいレポートを連携したくなったときにも迷わないように、sales_summary_daily のような {reportType}_{reportSubType}_{frequency} の形でテーブル名をつけています。
また、連携も sales_summary_daily$$target_date_bq$ のように begin_date カラムを パーティション ID にした日単位のパーティションを設定し、REPLACE 連携とすることで複数回実行しても冪等になるようにしています。
カラムの意味に気をつける
連携されたテーブルには product_type_identifier という STRING のカラムがあり、集計時にはこれをフィルタして対象を絞る必要があります。
Product type identifier の示すタイプはリファレンスに記載があり、ぱっと見ではわからない感じの体系でネーミングされています。
例えばダウンロード数を取得するためのクエリは
SELECT
begin_date,
device,
version,
units,
FROM
`<PROJECT ID>.<DATASET ID>.sales_summary_daily`
WHERE
product_type_identifier = '1' -- ダウンロードに絞る
ORDER BY
1, 2, 3
のようになります。
また、begin_date と end_date というカラムをそのまま連携すると BigQuery 上ではタイムスタンプとして見える（もともとは Date 型の様子）のですが、前述の通り PT 時間の日付を示すカラムのはずなので注意が必要です。
まとめ
Trocco を活用した App Store Connect 連携を見てきましたがいかがでしたでしょうか？
ポイントとしては
- 連携にはチーム API キーが必要
- 取得したいレポートと API 仕様をよく見比べる（特に取得可能なレポートタイプ）
- レポートは Pacific Time 基準で作成され、さらに日本時間から２日程度ラグがある
あたりでしょうか。
外部システムとのデータ連携は、ブラックボックスになりがちな先方の API 仕様や、明文化されていない実装でハマることが多いため、何かしらのお役に立てれば幸いです。また、実際は連携部分の開発もする必要があるところですが、そこは Trocco のおかげであまり気にしなくて良いと言うのはマネージドサービスならではのメリットですね。
こういった地味な？ところはまだまだ AI にお任せできないな…と思いつつ、次は Google Play Console 編を書こうと思います。
さて明日の MEDLEY Summer Tech Blog Relay 記事は医療プラットフォーム本部の内堀さんです！引き続きブログリレーをお楽しみに！
Discussion