py-hikvision-toolkit

一个用于与海康威视 iSecure Center (ISC) API 交互的 Python 客户端库。

项目主页

Gitee: https://gitee.com/guolei19850528/py_hikvision_toolkit

文档: 海康威视开放平台

功能特性

• HMAC-SHA256 签名算法：符合 Artemis 网关规范的请求签名
• 同步/异步支持：同时支持同步和异步 HTTP 请求
• 请求头自动生成：自动处理认证信息（Access Key、Nonce、Timestamp、Signature）
• 响应数据模型：基于 Pydantic 的响应数据验证和类型提示
• 工具函数集：提供图片处理、URL 处理、响应模型构建等辅助功能

安装

使用 uv（推荐）

uv add py-hikvision-toolkit

使用 pip

pip install py-hikvision-toolkit

快速开始

from py_hikvision_toolkit.isc import Isc
from py_hikvision_toolkit.isc.responses import build_base_instance
from py_hikvision_toolkit.isc.utils import url_add_artemis_prefix

# 初始化 ISC 客户端
isc = Isc(
    host="https://isc.example.com:1443",
    ak="your_access_key",
    sk="your_secret_key"
)

# 发送同步请求
response = isc.request_with_headers(
    url=url_add_artemis_prefix("/api/resource/v1/org/orgInfo"),
    json={"orgIndexCodes": ["root000000"]}
)

# 解析响应
result = build_base_instance(response)
if result.is_success():
    print(result.data)
else:
    print(f"请求失败，错误码：{result.code}，错误信息：{result.msg}")

API 说明

Isc 客户端类

初始化

from py_hikvision_toolkit.isc import Isc

isc = Isc(
    host="https://isc.example.com:1443",  # ISC 服务器地址
    ak="your_ak",  # Access Key
    sk="your_sk",  # Secret Key
    client_kwargs={"timeout": 30}  # 可选：客户端配置
)

核心方法

认证机制

ISC API 使用基于 HMAC-SHA256 的签名机制：

1. 构建签名字符串（按顺序拼接）：

   • HTTP 方法（如 POST）
   • Accept 头值
   • Content-Type 头值
   • x-ca-key
   • x-ca-nonce（随机 UUID）
   • x-ca-timestamp（毫秒时间戳）
   • 请求路径

2. 使用 Secret Key 对签名字符串进行 HMAC-SHA256 签名

3. 将签名放入 x-ca-signature 请求头中

utils 工具函数

响应数据模型

Base 模型

from py_hikvision_toolkit.isc.responses import Base

response = {"code": 0, "msg": "success"}
base = Base(**response)

字段说明：

• code: 错误码，0 表示成功（支持整数和字符串）
• msg: 错误信息描述

Success 模型

from py_hikvision_toolkit.isc.responses import Base

response = {"code": 0, "msg": "success", "data": {"items": []}}
success = Base(**response)
print(success.is_success())

字段说明：

• code: 固定为 0 或 "0"
• msg: 成功消息（可选）
• data: 返回的实际数据

示例代码

示例 1：获取组织信息

from py_hikvision_toolkit.isc import Isc
from py_hikvision_toolkit.isc.responses import build_base_instance
from py_hikvision_toolkit.isc.utils import url_add_artemis_prefix

isc = Isc(host="https://isc.example.com:1443", ak="your_ak", sk="your_sk")

response = isc.request_with_headers(
    url=url_add_artemis_prefix("/api/resource/v2/org/advance/orgList"),
    json={"orgIndexCodes": "root000000", "pageNo": 1, "pageSize": 100}
)

result = build_base_instance(response)
if result.is_success():
    print(result.data)
else:
    print(f"请求失败，错误码：{result.code}，错误信息：{result.msg}")

示例 2：异步请求

import asyncio
from py_hikvision_toolkit.isc import Isc
from py_hikvision_toolkit.isc.responses import build_base_instance


async def main():
   isc = Isc(host="https://isc.example.com:1443", ak="your_ak", sk="your_sk")
   response = await isc.async_request_with_headers(
      url="/api/resource/v1/org/orgInfo",
      json={"orgIndexCodes": ["root000000"]}
   )
   result = build_base_instance(response)
   if result.is_success():
      print(result.data)
   else:
      print(f"请求失败，错误码：{result.code}，错误信息：{result.msg}")


asyncio.run(main())

示例 3：添加人脸

from py_hikvision_toolkit.isc import Isc
from py_hikvision_toolkit.isc.utils import url_add_artemis_prefix, image_to_base64_and_md5

isc = Isc(host="https://isc.example.com:1443", ak="your_ak", sk="your_sk")

# 将图片转换为 Base64
base64_str, md5_str = image_to_base64_and_md5("/path/to/face.jpg")

response = isc.request_with_headers(
    url=url_add_artemis_prefix("/api/resource/v1/person/single/add"),
    json={
        "tagId": "frs",
        "personName": "张三",
        "certificateType": "111",
        "certificateNo": "110101199001011234",
        "orgIndexCode": "e5b44598-9b9f-4273-8540-3209eaf4c7a1",
        "faces": [{"faceData": base64_str}]
    }
)

项目结构

py_hikvision_toolkit/
├── src/
│   └── py_hikvision_toolkit/
│       ├── __init__.py
│       └── isc/
│           ├── __init__.py       # Isc 客户端类
│           ├── responses.py      # 响应数据模型
│           └── utils.py          # 工具函数
├── pyproject.toml
├── LICENSE
└── README.md

许可证

MIT License

作者

Guolei (174000902@qq.com)