必须确认三件事：一是在磁力引擎后台创建应用获取client_id和client_secret；二是实现access_token的获取与2小时自动刷新逻辑；三是严格按HMAC-SHA256算法签名，参数须字典序拼接且含timestamp、nonce、access_token等。
快手磁力引擎 API 调用前必须确认的三件事
PHP 无法直接“调用磁力引擎”——它没有开放 PHP SDK，所有交互都走 HTTP 接口（RESTful），且强制要求 HTTPS + 签名认证。不搞清鉴权逻辑，发一百个请求都会返回 401 Unauthorized 或 {"code":10001,"msg":"invalid sign"}。
你得自己构造签名、拼接参数、发 POST/GET 请求，不是 file_get_contents() 扔个 URL 就行。
- 必须先在 磁力引擎后台 创建应用，拿到
client_id和client_secret - 所有接口需用
access_token，它不是永久有效，有效期 2 小时，得自己做刷新逻辑（调用/oauth2/access_token） - 签名算法是 HMAC-SHA256，密钥是
client_secret，原文是按字典序拼接的全部非空参数（含timestamp、nonce、access_token等），漏一个字段或顺序错，签名就失效
用 cURL 发起报表拉取请求（PHP 实操要点）
获取广告效果数据的核心接口是 /rest/report/v1/getReportData，POST 提交 JSON。PHP 里最容易翻车的是 Content-Type、JSON 编码和错误处理没跟上。
- 必须显式设置
Content-Type: application/json，否则返回{"code":10005,"msg":"invalid content type"} -
json_encode()后要检查是否为false（比如中文乱码或循环引用），否则发出去的是空字符串 - 别用
file_get_contents()+stream_context_create()，对超时、重定向、HTTP 状态码处理太弱；坚持用cURL，至少加CURLOPT_TIMEOUT和CURLOPT_FAILONERROR - 响应体始终是 JSON，但失败时可能不含
data字段，直接$res->data会报 Notice；先判isset($res->code)再分支处理
示例关键片段：
立即学习“PHP免费学习笔记（深入）”；
curl_setopt($ch, CURLOPT_URL, 'https://www.php.cn/link/62dc8116091a39428cf634860718926c/rest/report/v1/getReportData');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Content-Type: application/json',
'Authorization: Bearer ' . $access_token
]);
报表参数怎么填才不被拒（date_range、metrics、dimensions）
接口返回空数据或 {"code":20001,"msg":"invalid date range"}，大概率是时间或指标写错了。磁力引擎对 date_range 格式极其敏感，且部分 metrics 不能和某些 dimensions 混用。
-
date_range必须是对象，不是字符串：{"start_date":"2024-05-01","end_date":"2024-05-07"}；日期不能跨自然周（如周一到周日），也不能超过最近 30 天 -
metrics填["clicks", "cost"]没问题，但填["ctr"]就会报错——CTR 是计算字段，不在原始指标列表里，得自己算 -
dimensions加了"adgroup_id"就不能再加"creative_id"，层级冲突；查账户汇总数据就别传任何维度 - 单次请求最多返回 10 万行，超量会截断且不提示；需要分页就得传
page和page_size（最大 1000），并轮询直到has_more === false
access_token 过期后自动续期的最小可行逻辑
PHP 脚本跑一小时就挂，八成是 token 过期没处理。不能每次请求都去刷新 token，也不能等 401 了再重试——因为并发请求可能同时撞上过期点，造成大量重复刷新和限流。
- 把
access_token和expires_in（单位秒）一起缓存，比如存在 Redis 里，key 命名为ks_access_token:{client_id} - 发起报表请求前，先查缓存，如果剩余有效期 /oauth2/refresh_token 刷新，并更新缓存
- 刷新接口要用原
refresh_token（首次授权返回的），不是access_token；且grant_type固定为"refresh_token" - 别在 Web 请求里做刷新——可能阻塞用户；建议用 CLI 脚本定时刷新并写入缓存，业务代码只读
token 刷新失败常见原因是 refresh_token 已被用过一次（它是一次性），或超过 30 天未使用自动作废。这个细节文档里藏得很深，但实际高频出问题。
