华为 Pura 80 Pro 调用 HiLens OpenAPI 返回 401 故障排查

# 华为 Pura 80 Pro 调用 HiLens OpenAPI 返回 401 故障排查

## 背景与适用场景

华为 HiLens（华为机器视觉服务）是 HMS Core 生态中的核心 AI 能力组件，为开发者提供端侧模型部署、推理调用和设备管理能力。当前主流支持设备涵盖 Mate 60 系列、Pura 70 系列、Pura 80 Pro 等 HarmonyOS 5.0 及以上机型。然而，由于 HiLens 采用基于 HMS Core 的五层鉴权体系（设备级→应用级→签名级→权限级→时间同步级），任何一层配置偏差均会触发 401 鉴权失败，这也是华为开发者社区中反馈频次最高的故障类型之一。

本文档适用于以下典型场景：
– 设备侧应用（而非云侧服务器）直接调用 HiLens REST API
– Pura 80 Pro 设备在 HarmonyOS 5.0 环境下进行 AI 能力集成
– 开发者从华强北采购设备或更换调试证书后出现偶发性 401

—

## 现象

调用华为 HiLens Studio REST API 时，请求返回 HTTP 401，响应体如下：

“`json
{
“error_code”: “1002”,
“error_msg”: “鉴权失败，请检查AppId和ClientId是否正确”
}
“`

设备为 Pura 80 Pro，系统版本 HarmonyOS 5.0，调用端为设备侧应用（非云侧）。

补充说明：在华为 HMS API 错误体系中，错误码 1002 特指客户端认证层失败，与 1001（参数缺失）、1003（签名不匹配）属于同一错误族系，但根因定位路径截然不同。1002 的核心特征是「客户端身份未被 API 网关认可」，而非「请求内容本身有问题」，这意味着问题出在调用端配置而非接口调用逻辑。

—

## 可能原因

### 原因一：agconnect-services.json 未正确注入

HarmonyOS 应用调用 HMS Core API 前，必须将华为开发者联盟后台生成的 `agconnect-services.json` 放置在应用资源目录。Pura 80 Pro 的 HarmonyOS 5 对目录结构做了收紧，错误放置会导致 SDK 读取配置失败，签名校验直接返回 401。

检查文件是否在以下路径之一：

“`
# Stage模型（推荐）
entry/src/main/module/resources/rawfile/agconnect-services.json

# FA模型旧路径
entry/src/main/assets/agconnect-services.json
“`

深度解析：agconnect-services.json 本质上是一份由华为服务器动态签发的设备身份授权文件，其内部包含的 `client_id`、`client_secret`、`app_key` 等字段在每次应用启动时会被 HMS SDK 用于换取临时访问令牌（Access Token）。若文件缺失或路径错误，SDK 的 `getToken()` 调用会在本地直接抛出 SecurityException，网关返回 1002 而非 1010（认证超时），这正是许多开发者容易混淆的地方。

### 原因二：Client ID 与设备指纹不匹配

华为要求调用端应用的 SHA-256 证书指纹必须与后台登记的指纹一致。Pura 80 Pro 调试时若使用临时签名，SHA-256 会与发布证书不同，后台配置未同步更新的情况下，API 网关会拒绝请求。

典型案例：某深圳华强北方案商在量产设备预置 HiLens 能力时，使用了流水线统一的调试证书，但 AGC 后台仅登记了发布证书指纹。结果首批 200 台设备上线后全部返回 401，最终通过 HMS 技术支持工单定位到指纹白名单机制。此类问题在高周转的硬件调试场景中极为常见。

### 原因三：HMS Core 版本过旧或缺失

HarmonyOS 5 的 HMS Core 5.0 对 API 权限校验比旧版更严格。若设备上 HMS Core 版本低于 5.0.0.300，部分 HiLens 相关 API 会直接返回 401 而非明确的权限错误。

版本演进背景：HMS Core 从 4.x 升级到 5.0 是一次重大的安全架构演进。4.x 版本允许一定程度的「宽容模式」——即使签名指纹略有偏差，只要 AppId 正确即可通过基础鉴权；而 5.0 引入了「设备-应用-签名」三重绑定校验，任何一层不匹配都会直接拒绝。Pura 80 Pro 出厂默认搭载 HMS Core 5.0.0.300 及以上版本，但部分存量设备或降级恢复的设备可能仍停留在旧版本。

### 原因四：API 作用域（Scope）未在AGC开通

HiLens Studio 的模型部署类 API 属于高危权限，需在 AppGallery Connect 后台手动开通对应服务，并在 `module.json5` 中声明 `requestPermissions` 列表中声明对应权限。

权限体系说明：华为 HMS 的权限分为「普通权限」和「受控权限」两类。HiLens 的模型读取、模型推理、设备管理等能力均属于受控权限，需要开发者在 AGC 后台提交权限申请并等待华为审核通过。审核通过后，权限会与 AppId 绑定，后续 API 调用时网关会验证调用方是否持有对应权限声明。这一机制与 Google Play 的 App Signing 以及 Apple 的 entitlements 类似，但华为的绑定关系更为严格——同一 AppId 在不同设备上调用相同 API，若权限声明缺失，也会返回 401。

—

## 解决步骤

### Step 1：验证配置文件有效性

解压应用 APK，提取根目录下的 `agconnect-services.json`，检查以下字段：

“`json
{
“client”: {
“app_id”: “3xxxxx86”,
“cp_id”: “2xxxxx4xxxxx4”,
“product_id”: “7xxxxx0”,
“client_id”: “3xxxxx86xxxxx0”,
“client_secret”: “xxxxx”,
“project_id”: “7xxxxx0”,
“app_key”: “xxxxx”
},
“service”: {
“analytics”: { … },
“cloudstorage”: { … },
“ml”: { … }
}
“`

确认 `service.ml` 节点存在且配置完整。若为空对象 `{}`，说明 HiLens 服务未开通；若节点缺失，说明当前应用未开通机器视觉服务，需前往 AGC 后台「HMS Core」→「机器视觉服务」提交开通申请。

补充验证点：检查 `client.app_id` 的格式是否为 8 位数字（华为国内应用以「1」或「2」开头），若出现字母或位数异常，说明下载的配置文件来自海外区或其他项目，而非当前应用。

### Step 2：重新登记设备指纹

在 AGC 后台「用户与访问」→「应用信息」→「证书/密钥管理」中，将当前调试证书的 SHA-256 添加至「App签名」列表：

“`bash
# 提取当前签名指纹
keytool -list -v -keystore ~/.android/debug.keystore \
-alias androiddebugkey -storepass android -keypass android
“`

将输出中的 `SHA256:` 值完整复制到 AGC 后台，保存后等待 5-10 分钟生效。

关键细节：AGC 后台签名指纹支持多指纹白名单，这对于同时使用调试证书和发布证书的开发流程尤为重要。此外，若使用 HarmonyOS 的「自动签名」功能（DevEco Studio 内置），每次 USB 连接新设备时 SDK 会动态生成临时签名，此时 SHA-256 会随设备 USB 连接会话变化，需要定期将新指纹同步至 AGC 后台。

### Step 3：升级 HMS Core

在设备「设置」→「应用」→「应用和元服务」中，将 HMS Core 更新至最新版本。或通过以下 adb 命令强制触发更新检测：

“`bash
adb shell am start -a com.huawei.appmarket.MainActivity
“`

相关阅读：手机868 深圳报价