asc-analytics-reports

asc 分析报告

收集完整的分析报告分段，并在交给单独的分析工作流之前验证压缩文件。此技能不会解读、汇总或展示报告内容。

防护措施

• 将报告清单、签名 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. 查找现有请求

解析 App 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 生成，并保持压缩字节不变。分析报告采用制表符分隔文本，因此应使用 .txt.gz，不要让人误以为是 CSV：

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、配置文件名称、凭据或原始行。保留已验证的文件，供用户在下一工作流中使用。删除临时目录或任何已下载的证据前，请先征得同意。