asc-analytics-reports

asc analytics レポート

分析レポートのセグメント一式を収集し、別の分析ワークフローに渡す前に圧縮ファイルを検証します。このスキルでは、レポートの内容を解釈、集計、提示しないでください。

ガードレール

• レポートの一覧、署名付き URL、ダウンロードしたセグメント、識別子は、機密性の高いビジネスデータとして扱ってください。
• 既存のリクエストを優先してください。リクエストを作成すると App Store Connect の状態が変わり、Admin の承認を受けたプロファイルが必要です。asc analytics request を実行する前に、ユーザーから明示的な承認を得てください。
• 収集中にリクエストを削除または置き換えないでください。
• asc analytics download を使用してください。署名付きセグメント URL を別途取得または保存しないでください。
• プライベートファイルは、ソースリポジトリの外部に、所有者のみがアクセスできる権限で保存してください。
• 予期されるセグメントが欠落している場合や、検証に失敗した場合は、収集が完了したと主張しないでください。

1. CLI の仕様を確認する

認証または収集の前に、インストール済みコマンドを確認します。

asc analytics view --help

ヘルプに --processing-date、--granularity、--paginate、--include-segments が記載されている場合にのみ続行してください。これらのフィルターには asc 3.5.0 以降が必要です。いずれかのフィルターがない場合は、ユーザーにアップグレードを依頼してください。非推奨の --date フラグで代用しないでください。このフラグは Apple のサーバー側の処理日フィルターではなく、従来のローカルマッチングを使用します。

2. プライベートストレージを準備する

JSON の取得やセグメントのダウンロードを行う前に、リポジトリの外部にプライベートな一時ディレクトリを作成します。

umask 077
ASC_ANALYTICS_DIR="$(mktemp -d "${TMPDIR:-/tmp}/asc-analytics.XXXXXX")"
mkdir -m 700 "$ASC_ANALYTICS_DIR/segments"

コマンドの出力とエラーは、このディレクトリにリダイレクトしてください。生の一覧 JSON やエラー出力をチャット、コミット、イシュー、プルリクエストに貼り付けないでください。

3. 既存のリクエストを探す

アプリ ID と選択した asc プロファイルを特定し、すべてのリクエストを一覧表示します。

asc --profile "$PROFILE" analytics requests \
  --app "$APP_ID" \
  --paginate \
  --output json \
  > "$ASC_ANALYTICS_DIR/requests.json" \
  2> "$ASC_ANALYTICS_DIR/requests.stderr"

JSON を構造的に調べ、使用可能な既存のリクエストを選択してください。指定なしで検索できる場合は、--state に依存しないでください。使用可能なリクエストがない場合は停止し、ONGOING または ONE_TIME_SNAPSHOT のアクセス権を作成するか、ユーザーに確認してください。承認を求める前に、対象のアプリとプロファイルを提示してください。承認後は、重複を避けるために --reuse-existing を優先してください。

asc --profile "$APPROVED_PROFILE" analytics request \
  --app "$APP_ID" \
  --access-type "$ACCESS_TYPE" \
  --reuse-existing \
  --output json \
  > "$ASC_ANALYTICS_DIR/request.json" \
  2> "$ASC_ANALYTICS_DIR/request.stderr"

明示的な承認なしに、このコマンドを実行しないでください。続行する前に、プライベート JSON レスポンスから返されたリクエスト ID を読み取ってください。

REQUEST_ID="$(jq -er '.requestId' "$ASC_ANALYTICS_DIR/request.json")"

承認されたプロファイルでリクエストを作成または再利用した場合は、ANALYTICS_PROFILE="$APPROVED_PROFILE" を設定します。読み取り専用プロファイルで既存のリクエストを見つけた場合は、ANALYTICS_PROFILE="$PROFILE" を設定します。それ以降のすべての analytics view と analytics download の呼び出しには、同じプロファイルを使用してください。

4. レポートインスタンスを検索して選択する

まず、セグメント URL を含めずに、レポートとインスタンスのメタデータを取得します。

asc --profile "$ANALYTICS_PROFILE" analytics view \
  --request-id "$REQUEST_ID" \
  --paginate \
  --output json \
  > "$ASC_ANALYTICS_DIR/discovery.json" \
  2> "$ASC_ANALYTICS_DIR/discovery.stderr"

利用可能な processingDate と、ユーザーが指定した詳細度を選択します。DAILY、WEEKLY、MONTHLY を個別に、またはカンマ区切りのリストで受け付けます。入力をカンマで分割し、各トークンの前後の空白を取り除き、大文字に正規化します。空のトークンを含め、すべてのトークンが許可リストに含まれていることを検証してください。無効な入力を報告し、analytics view を実行する前に停止します。サポートされていない値を黙って破棄したり、フィルターが空の状態で続行したりしないでください。検証後、重複を取り除き、残りの値をカンマで結合します。 processingDate は Apple がレポートを処理した日付であり、レポートの行が表す期間とは必ずしも一致しないことに注意してください。

すべてのセグメントメタデータを含め、フィルターを適用した一覧を取得します。

asc --profile "$ANALYTICS_PROFILE" analytics view \
  --request-id "$REQUEST_ID" \
  --processing-date "$PROCESSING_DATE" \
  --granularity "$GRANULARITY" \
  --paginate \
  --include-segments \
  --output json \
  > "$ASC_ANALYTICS_DIR/inventory.json" \
  2> "$ASC_ANALYTICS_DIR/inventory.stderr"

必ず --paginate を使用してください。asc は Apple が提供するレポートとインスタンスの次ページリンクに従います。ページネーション URL を手動で再構築、変更、またはたどらないでください。

5. すべてのセグメントをダウンロードする

inventory.json を構造的に解析します。選択した各インスタンスについて、すべての セグメントを列挙し、検証に備えて各セグメントの正確な ID、sizeInBytes、および checksum を保持します。downloadUrl は出力しないでください。

各セグメントを、リクエスト ID、インスタンス ID、セグメント ID を指定して ダウンロードします。ファイル名にはセグメント ID のみを使用し、圧縮されたバイト列を そのまま保持します。分析レポートはタブ区切りテキストなので、CSV を想定させる 拡張子ではなく .txt.gz を使用します。

SEGMENT_FILE="$ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.txt.gz"
asc --profile "$ANALYTICS_PROFILE" analytics download \
  --request-id "$REQUEST_ID" \
  --instance-id "$INSTANCE_ID" \
  --segment-id "$SEGMENT_ID" \
  --output "$SEGMENT_FILE" \
  > /dev/null \
  2>> "$ASC_ANALYTICS_DIR/download.stderr"

検証前に --decompress を使用しないでください。インスタンスに複数のセグメントが ある場合はすべてダウンロードし、最初のセグメントだけでレポート全体を表すものとして 扱わないでください。

6. ダウンロードしたファイルを検証する

各ファイルについて、圧縮後のバイト数を sizeInBytes と比較し、小文字の MD5 ダイジェストを checksum と比較します。次のようなローカルシステムツールを使用します。

actual_size="$(wc -c < "$SEGMENT_FILE" | tr -d ' ')"
actual_md5="$(openssl dgst -md5 -r "$SEGMENT_FILE" | awk '{print tolower($1)}')"
expected_md5="$(printf '%s' "$CHECKSUM" | tr '[:upper:]' '[:lower:]')"

actual_size が sizeInBytes と一致し、actual_md5 が expected_md5 と一致することを 確認します。一致しない場合は、そのセグメントを失敗として記録し、未加工のエラーを 非公開に保ち、収集が完了したと主張しないでください。asc analytics download は 既存の出力ファイルを上書きしないため、失敗したセグメントは $ASC_ANALYTICS_DIR/segments/$SEGMENT_ID.retry-1.txt.gz のような新しいパスに 一度だけ再試行します。再試行分は独立して検証し、両方のチェックに合格した場合にのみ 使用します。ユーザーの承認がない限り、最初に失敗したファイルは保持してください。 検証が成功するまで、ファイルを解析または分析しないでください。

7. 結果を報告する

次の内容を簡潔にまとめて返します。

• 選択した処理日と粒度の値。
• レポート、インスタンス、想定されるセグメント、ダウンロード済みセグメント、 検証済みセグメントの件数。
• 収集が完了しているかどうか。
• 失敗または欠落したセグメント ID（ある場合）。署名付き URL やレポートの行は含めないでください。
• 現在のユーザーセッションに適切な場合は、非公開の出力ディレクトリ。

公開アーティファクトには、分析値、署名付き URL、プロファイル名、認証情報、 未加工の行を含めないでください。ユーザーの次のワークフローに備えて、検証済みの ファイルを保持してください。一時ディレクトリまたはダウンロード済みの証跡を削除する 前に、ユーザーに確認してください。