157 lines
4.2 KiB
Markdown
157 lines
4.2 KiB
Markdown
# mijia-go-api
|
|
|
|
`mijia-go-api` 是一个纯 Go 米家 API 库，支持二维码登录与 token 刷新、家庭/设备/场景/耗材查询、属性读写、action 执行、统计查询，以及基于 MIoT 设备描述的高级 `Device` 操作。
|
|
|
|
本项目只提供 Go 库，不提供 CLI、MCP、skills 或 HAR decrypt 功能。
|
|
|
|
## 安装
|
|
|
|
```bash
|
|
go get git.misaka.ren/m1saka/mijia-go-api
|
|
```
|
|
|
|
## 登录
|
|
|
|
`NewClient` 的认证路径传空字符串时，默认使用 `~/.config/mijia-api/auth.json`。`Login` 会优先尝试刷新已有 token；需要重新登录时，会在终端输出二维码供米家 App 扫描。
|
|
|
|
```go
|
|
package main
|
|
|
|
import (
|
|
"context"
|
|
"log"
|
|
|
|
mijia "git.misaka.ren/m1saka/mijia-go-api"
|
|
)
|
|
|
|
func main() {
|
|
client, err := mijia.NewClient("")
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
if _, err := client.Login(context.Background()); err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
|
|
auth := client.AuthData()
|
|
log.Printf("已登录 userId=%s", auth.UserID)
|
|
}
|
|
```
|
|
|
|
`auth.json` 包含 `serviceToken`、`passToken`、`ssecurity` 等敏感认证数据。库写入该文件时使用 `0600` 权限；请保持此权限，并且不要将该文件提交到版本库。
|
|
|
|
Web/GUI 应用可通过 `WithQRWriter` 接收登录输出，再将其展示给用户：
|
|
|
|
```go
|
|
var loginOutput bytes.Buffer
|
|
client, err := mijia.NewClient("", mijia.WithQRWriter(&loginOutput))
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
if _, err := client.Login(ctx); err != nil {
|
|
return err
|
|
}
|
|
|
|
// loginOutput 包含二维码 URL 和终端二维码文本，可交给 Web/GUI 展示层。
|
|
renderLoginOutput(loginOutput.String())
|
|
```
|
|
|
|
Writer 接收的内容包含登录二维码 URL，属于敏感登录信息；调用方不得将其写入日志、监控事件或其他持久化记录。
|
|
|
|
## 底层 API
|
|
|
|
以下示例展示设备、属性和 action 的直接调用。`GetDevices` 的 `homeID` 传空字符串时查询所有家庭。
|
|
|
|
```go
|
|
devices, err := client.GetDevices(ctx, "")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
properties, err := client.GetProperties(ctx, []mijia.PropertyRequest{
|
|
{DID: devices[0].DID, SIID: 2, PIID: 1},
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
_, err = client.SetProperties(ctx, []mijia.PropertySetRequest{
|
|
{DID: devices[0].DID, SIID: 2, PIID: 1, Value: true},
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
_, err = client.RunActions(ctx, []mijia.ActionRequest{
|
|
{DID: devices[0].DID, SIID: 2, AIID: 1},
|
|
})
|
|
```
|
|
|
|
家庭、场景、耗材和统计分别使用 `GetHomes`、`GetScenes`、`RunScene`、`GetConsumables` 和 `GetStatistics`。
|
|
|
|
## 高级 Device
|
|
|
|
`NewDevice` 可通过 `DeviceSelector.DID` 或 `DeviceSelector.Name` 选择设备；名称匹配到多个设备时会返回 `MultipleDevicesFoundError`。设备描述默认缓存到认证文件所在目录，每次成功的 `Get`、`Set`、`RunAction` 后默认等待 `500ms`。
|
|
|
|
```go
|
|
device, err := mijia.NewDevice(ctx, client, mijia.DeviceSelector{DID: "设备 DID"})
|
|
// 也可以按名称选择：mijia.DeviceSelector{Name: "客厅灯"}
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
value, err := device.Get(ctx, "on")
|
|
if err != nil {
|
|
return err
|
|
}
|
|
|
|
if err := device.Set(ctx, "on", true); err != nil {
|
|
return err
|
|
}
|
|
|
|
_, err = device.RunAction(ctx, "toggle", nil)
|
|
_ = value
|
|
```
|
|
|
|
可通过实际导出的 `DeviceOption` 调整行为：
|
|
|
|
```go
|
|
device, err := mijia.NewDevice(
|
|
ctx,
|
|
client,
|
|
mijia.DeviceSelector{Name: "客厅灯"},
|
|
mijia.WithDeviceDelay(0),
|
|
mijia.WithDeviceCacheDir("./miot-cache"),
|
|
mijia.WithDeviceHTTPClient(http.DefaultClient),
|
|
)
|
|
```
|
|
|
|
## 超时与错误
|
|
|
|
所有网络和设备操作都接收 `context.Context`，建议设置超时：
|
|
|
|
```go
|
|
ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
|
|
defer cancel()
|
|
|
|
devices, err := client.GetDevices(ctx, "")
|
|
```
|
|
|
|
API 错误和高级设备错误可使用 `errors.As` 判断：
|
|
|
|
```go
|
|
var apiErr *mijia.APIError
|
|
var deviceErr *mijia.DeviceGetError
|
|
|
|
switch {
|
|
case errors.As(err, &apiErr):
|
|
log.Printf("API 错误: code=%d message=%s", apiErr.Code, apiErr.Message)
|
|
case errors.As(err, &deviceErr):
|
|
log.Printf("设备读取错误: device=%s property=%s code=%d", deviceErr.DeviceName, deviceErr.Name, deviceErr.Code)
|
|
}
|
|
```
|
|
|
|
写属性和执行 action 时，对应错误类型为 `DeviceSetError` 和 `DeviceActionError`；设备选择还可能返回 `DeviceNotFoundError` 或 `MultipleDevicesFoundError`。
|