一、云市场 API 是怎么工作的
阿里云云市场上的 API 类商品,基本都托管在 阿里云 API 网关 上。一次调用的链路是:
调用方 ──(Authorization: APPCODE xxx)──▶ API 网关 ──(后端签名)──▶ 服务商后端 ──▶ 识别引擎 │ │ │ ├─ 校验 AppCode、套餐余量、QPS │ └─ 失败时在响应头返回 X-Ca-Error-* └─ 计费以网关统计的成功调用为准
这带来两个对接时必须清楚的点:
- 鉴权在网关完成:调用方只需要关心 AppCode,不需要和服务商单独签约或对接签名算法;
- 错误分两层:网关层错误(鉴权、额度、限流)通过 响应头 返回;业务层错误(参数错误、未识别到车牌)通过 响应体
code返回。排查时要先看头、再看体。
二、开通服务与获取凭证
- 访问商品页 market.aliyun.com/detail/cmapi00074871,选择适合的调用次数套餐完成购买;
- 进入 控制台 → 云市场 → 已购买的服务,在商品详情中可以看到
AppKey、AppSecret、AppCode三个凭证; - 本文使用 AppCode 简单身份认证,适合服务端调用;如果有更高的安全要求,也可以使用 AppKey + AppSecret 的签名认证方式(参考 API 网关官方文档"客户端签名")。
凭证建议存放在 KMS 凭据管家 或函数计算的环境变量中,不要提交到代码仓库。
三、接口规范
| 项目 | 内容 |
| 请求方法 | POST |
| Content-Type | application/x-www-form-urlencoded; charset=UTF-8 |
| 鉴权 | Header Authorization: APPCODE {你的AppCode} |
| 文件格式 | JPG / PNG / WEBP / PDF,≤ 2M |
请求参数(二选一,同时传入时优先 fileBase64):
| 参数 | 说明 |
fileBase64 |
文件 Base64 编码,可带 data:image/xxx;base64, 前缀 |
fileUrl |
公网可下载的文件地址 |
响应示例:
{ "code": 0, "msg": "success", "reqId": "6F1C7A2E-xxxx-xxxx-xxxx-9B0E5D3A1F27", "data": { "plateNumber": "川AQ3C28", "plateColor": "blue", "plateLayer": "single" } }
| 字段 | 取值说明 |
plateNumber |
号牌号码,支持蓝牌、绿牌(新能源)、黄牌单/双层、白牌、港澳号牌 |
plateColor |
blue、green、yellow、white、black;部分香港号牌底色不固定时为空 |
plateLayer |
single 单层、double 双层 |
reqId |
请求唯一标识,用于对账和问题追溯 |
四、错误处理:网关层 vs 业务层
4.1 网关层错误
请求被 API 网关拦截时,响应头中会带有:
X-Ca-Request-Id: 7B9E... # 网关请求 ID X-Ca-Error-Code: ... # 网关错误码 X-Ca-Error-Message: ... # 错误描述
常见情况:AppCode 不存在或拼写错误、Authorization 格式不对(APPCODE 与值之间必须有一个空格)、套餐余量为 0、超出 QPS 限制。这类错误请求没有到达服务商后端,需要在调用方或控制台侧解决。
4.2 业务层错误
| HTTP 状态码 | code | 含义 |
| 200 | 0 | 识别成功 |
| 400 | 10004 | 参数错误:参数为空、Base64 无法解码等 |
| 400 | 10007 | 文件超过大小限制 |
| 500 | 10000 | 识别失败:如图片中无车牌 |
该接口对失败请求返回非 2xx 状态码,按云市场的计费规则,非 2xx 的调用一般不计费(以商品页计费说明为准),这对存在一定比例无效图片的业务比较友好。
4.3 统一判定逻辑
def parse(resp): if resp.headers.get("X-Ca-Error-Code"): return "GATEWAY_ERROR", resp.headers.get("X-Ca-Error-Message") body = resp.json() if resp.status_code == 200 and body.get("code") == 0: return "OK", body["data"] if body.get("code") in (10004, 10007): return "BAD_INPUT", body.get("msg") # 不重试,提示用户 return "OCR_FAILED", body.get("msg") # 可提示重拍
五、实践:OSS + 函数计算 FC 的事件驱动识别
很多业务的图片本来就存在 OSS 上(例如车险查勘照片、停车场抓拍图)。一个低运维成本的做法是:图片上传到 OSS → 触发函数计算 → 调用车牌识别 → 结果写回数据库 / 消息队列。
App 上传 ──▶ OSS Bucket (uploads/plate/*.jpg) │ ObjectCreated 事件 ▼ 函数计算 FC (Python 3.10) │ 1. 生成带签名的临时 URL │ 2. 调用车牌识别接口(fileUrl) │ 3. 写入 RDS / 投递 MNS ▼ 业务系统
函数代码示例(OSS 触发器):
# index.py —— 函数计算 FC,Python 3.10 运行时 import json import os import oss2 import requests API_URL = "xxxx/yunmarket/plate_number_ocr" APPCODE = os.environ["PLATE_APPCODE"] # 函数环境变量 BUCKET = os.environ["OSS_BUCKET"] ENDPOINT = os.environ["OSS_ENDPOINT"] # 如 oss-cn-hangzhou-internal.aliyuncs.com def handler(event, context): evt = json.loads(event)["events"][0] key = evt["oss"]["object"]["key"] creds = context.credentials # 使用函数绑定的 RAM 角色 auth = oss2.StsAuth(creds.access_key_id, creds.access_key_secret, creds.security_token) # 签名 URL 需要公网可访问,用公网 Endpoint 生成 bucket = oss2.Bucket(auth, ENDPOINT.replace("-internal", ""), BUCKET) file_url = bucket.sign_url("GET", key, 300) # 5 分钟有效 resp = requests.post( API_URL, headers={"Authorization": f"APPCODE {APPCODE}"}, data={"fileUrl": file_url}, timeout=15, ) if resp.headers.get("X-Ca-Error-Code"): raise RuntimeError(f"gateway error: {resp.headers.get('X-Ca-Error-Message')}") # 交给 FC 重试 body = resp.json() result = {"key": key, "reqId": body.get("reqId"), "code": body.get("code")} if body.get("code") == 0: result.update(body["data"]) print(json.dumps(result, ensure_ascii=False)) # TODO: 写入 RDS 或投递到消息队列 return result
要点:
- 用签名 URL 传
fileUrl:Bucket 保持私有读,生成短时效签名 URL 给识别服务下载,避免 Base64 带来的约 33% 体积膨胀; - RAM 角色授权:函数绑定只读该 Bucket 的 RAM 角色,不在代码里放 AccessKey;
- 重试策略:只对网关层错误和网络超时重试;
10004/10007属于输入问题,重试没有意义; - 超时配置:函数超时建议 ≥ 30 秒,HTTP 超时 15 秒。
六、生产环境建议
安全
- AppCode 只放在服务端,客户端(App/小程序/H5)一律经过自有后端转发;
- 如业务对安全要求高,改用 AppKey/AppSecret 签名认证,防止凭证泄露后被重放。
成本
- 客户端上传前压缩(长边 1600px 左右),既能满足 2M 限制,也能缩短传输和识别耗时;
- 对同一张图片做 MD5 去重缓存,避免重复识别;
- 在控制台为套餐余量设置提醒,避免额度耗尽导致业务中断。
稳定性与可观测性
- 日志中同时记录网关
X-Ca-Request-Id和业务reqId,出现问题时可分别向网关和服务商定位; - 识别失败时业务侧降级为手工录入,不要阻塞主流程;
- 结合 SLS 日志服务统计识别成功率、平均耗时,按车牌颜色维度观察效果。
七、总结
云市场 API 的价值在于把"模型训练 + 部署 + 运维"打包成一个按次计费的 HTTP 接口。以本文的 车牌号识别 为例,接入工作主要集中在三件事上:
- 正确构造 AppCode 鉴权与表单参数;
- 区分网关层与业务层错误,制定对应的重试与降级策略;
- 结合 OSS、函数计算等云产品,把识别能力嵌入现有的数据流。
建议在正式接入前,先用小套餐对业务中的真实图片做一轮批量测试,评估识别效果。