""" 优时开放平台 · API 客户端示例(Python 3.7+,仅标准库) 签名串:METHOD + "\\n" + path + "\\n" + X-Timestamp + "\\n" + X-Nonce + "\\n" + sha256_hex(body) 签名: X-Sign = lower_hex(HMAC-SHA256(sign_key, 签名串)) - path:实际发出的 URL 路径(保持 URL 编码原样),不含域名和查询参数,例如 /v1/tickets - body:实际发出的请求体原始字节;没有请求体时为空 - X-Timestamp:秒级时间戳,与服务器相差不能超过 300 秒 - X-Nonce:16~64 位的字母、数字、下划线或短横线,10 分钟内不能重复 用法: OPEN_BASE_URL=https://open-api.yours.xyz OPEN_APPID=op_xxx OPEN_SECRET=xxx OPEN_SIGN_KEY=xxx python3 client.py python3 client.py sign # 只计算签名(自检) """ import hashlib import hmac import json import os import secrets import sys import time import urllib.error import urllib.parse import urllib.request from datetime import datetime from typing import Any, Dict, Optional TOKEN_REFRESH_MARGIN = 300 # token 到期前多少秒就重新获取 CODE_TOKEN_INVALID = 40102 # token 无效或过期 class _NoRedirect(urllib.request.HTTPRedirectHandler): """不跟随重定向:POST 被 301 / 302 后会变成不带请求体的 GET,导致难以排查的签名错误""" def redirect_request(self, req, fp, code, msg, headers, newurl): # type: ignore[override] return None _OPENER = urllib.request.build_opener(_NoRedirect) def sign(sign_key: str, method: str, path: str, timestamp: str, nonce: str, body: bytes) -> str: """计算请求签名(纯函数,不读取时钟和随机数,方便和服务端对照)""" string_to_sign = "\n".join([method.upper(), path, timestamp, nonce, hashlib.sha256(body).hexdigest()]) return hmac.new(sign_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest() class YoursOpenError(Exception): pass def describe_error(title: str, res: Dict[str, Any]) -> str: return "{}:code={} msg={} request_id={}".format(title, res.get("code", "-"), res.get("msg", "-"), res.get("request_id", "-")) class YoursOpenClient: def __init__(self, base_url: str, appid: str, secret: str, sign_key: str, timeout: float = 10): """base_url 只写协议和域名(可带端口),不要带 /v1,例如 https://open-api.yours.xyz""" self.base_url = base_url.rstrip("/") self.appid = appid self.secret = secret self.sign_key = sign_key self.timeout = timeout self._token = "" self._token_expires_at = 0.0 def token(self, force_refresh: bool = False) -> str: """获取 access_token。有效期内复用;每天获取次数有限,生产环境请在多个进程之间共享缓存。""" if not force_refresh and self._token and time.time() < self._token_expires_at: return self._token body = self._encode_json({"appid": self.appid, "secret": self.secret, "grant_type": "client_credential"}) res = self._send("POST", self.base_url + "/oauth/token", body, {"Content-Type": "application/json"}) if res.get("code") != 0: raise YoursOpenError(describe_error("获取 token 失败", res)) self._token = res["data"]["access_token"] self._token_expires_at = time.time() + max(0, int(res["data"]["expires_in"]) - TOKEN_REFRESH_MARGIN) return self._token def request(self, method: str, path: str, query: Optional[Dict[str, str]] = None, body: Optional[Dict[str, Any]] = None, signed: bool = True) -> Dict[str, Any]: """ 调用开放接口,返回解析后的响应 {code, msg, data, request_id}(业务错误不抛异常,由调用方判断 code)。 path:以 / 开头、已经 URL 编码的路径,例如 /v1/tickets;查询参数放在 query 里(不参与签名) body:请求体,会编码成 JSON;None 表示不带请求体 signed:是否签名。写接口(*.write)必须签名;读接口签了也没有影响 """ if not path.startswith("/") or "?" in path or "#" in path: raise ValueError("path 必须以 / 开头,且不能包含查询参数") method = method.upper() if body is not None and method in ("GET", "HEAD"): raise ValueError("GET / HEAD 请求不能带请求体(签名包含请求体,但不会被发送)") raw = b"" if body is None else self._encode_json(body) url = self.base_url + path + ("?" + urllib.parse.urlencode(query, quote_via=urllib.parse.quote) if query else "") res = self._send_api(method, path, url, raw, signed, False) if res.get("code") == CODE_TOKEN_INVALID: # token 被吊销或过期:重新获取一次再试(每次请求都会生成新的 nonce) res = self._send_api(method, path, url, raw, signed, True) return res def _send_api(self, method: str, path: str, url: str, raw: bytes, signed: bool, refresh_token: bool) -> Dict[str, Any]: headers = {"Authorization": "Bearer " + self.token(refresh_token)} if raw: headers["Content-Type"] = "application/json" if signed: timestamp = str(int(time.time())) nonce = secrets.token_hex(16) headers["X-Timestamp"] = timestamp headers["X-Nonce"] = nonce # 签的必须是下面实际发送的 raw,不能重新编码一次 headers["X-Sign"] = sign(self.sign_key, method, path, timestamp, nonce, raw) return self._send(method, url, raw, headers) def _send(self, method: str, url: str, body: bytes, headers: Dict[str, str]) -> Dict[str, Any]: data = None if method in ("GET", "HEAD") else body req = urllib.request.Request(url, data=data, headers=headers, method=method) try: with _OPENER.open(req, timeout=self.timeout) as resp: status, raw = resp.status, resp.read() except urllib.error.HTTPError as e: # 4xx / 5xx 也是开放平台格式的响应 status, raw = e.code, e.read() except urllib.error.URLError as e: raise YoursOpenError("请求失败:{}".format(e.reason)) try: res = json.loads(raw.decode("utf-8")) except ValueError: res = None if not isinstance(res, dict) or "code" not in res: raise YoursOpenError("响应不是开放平台格式(HTTP {})".format(status)) return res @staticmethod def _encode_json(data: Dict[str, Any]) -> bytes: return json.dumps(data, ensure_ascii=False, separators=(",", ":")).encode("utf-8") def demo() -> int: """演示:获取 token → 查询门店 → 现场取号。需要应用拥有 store.read 和 ticket.write 权限""" config = {} for name in ("OPEN_BASE_URL", "OPEN_APPID", "OPEN_SECRET", "OPEN_SIGN_KEY"): config[name] = os.environ.get(name, "") if not config[name]: print("请设置环境变量 " + name, file=sys.stderr) return 2 client = YoursOpenClient(config["OPEN_BASE_URL"], config["OPEN_APPID"], config["OPEN_SECRET"], config["OPEN_SIGN_KEY"]) try: client.token() print("获取 token 成功") stores = client.request("GET", "/v1/stores") if stores.get("code") != 0 or not stores["data"]["items"]: print(describe_error("查询门店失败", stores), file=sys.stderr) return 1 store = stores["data"]["items"][0] print("门店:store_id={} name={}".format(store["store_id"], store["name"])) # out_ticket_no 是你自己的单号(幂等键):超时重试时必须使用同一个单号 out_ticket_no = "DEMO" + datetime.now().strftime("%Y%m%d%H%M%S") + secrets.token_hex(3) ticket = client.request("POST", "/v1/tickets", body={ "out_ticket_no": out_ticket_no, "store_id": store["store_id"], "user": {"open_user_id": "demo_user_1", "mobile": "13800000000", "name": "张三"}, }) if ticket.get("code") != 0: print(describe_error("取号失败", ticket), file=sys.stderr) return 1 data = ticket["data"] print("取号成功:ticket_id={} number={} status={} ahead_count={}".format( data["ticket_id"], data["number"], data["status"], data["ahead_count"])) return 0 except YoursOpenError as e: print(str(e), file=sys.stderr) return 1 if __name__ == "__main__": if len(sys.argv) > 1 and sys.argv[1] == "sign": if len(sys.argv) != 8: print("用法:python3 client.py sign ", file=sys.stderr) sys.exit(2) _, _, key, http_method, req_path, ts, nonce_value, body_file = sys.argv if key == "-": # 从环境变量读取,避免 sign_key 出现在 shell 历史和进程列表里 key = os.environ["OPEN_SIGN_KEY"] with open(body_file, "rb") as f: print(sign(key, http_method, req_path, ts, nonce_value, f.read())) sys.exit(0) sys.exit(demo())