项目管理

项目是设备管理的基本单位，用于对设备进行分组和管理。一个组织下可以创建多个项目，每个项目可以包含多个设备。

接口概览

方法	端点	描述
`GET`	`/api/v2/projects/`	获取项目列表
`POST`	`/api/v2/projects/`	创建项目
`GET`	`/api/v2/projects/{project_id}/`	获取项目详情
`PUT`	`/api/v2/projects/{project_id}/`	更新项目
`DELETE`	`/api/v2/projects/{project_id}/`	删除项目
`POST`	`/api/v2/projects/{project_id}/transfer/`	转移项目

项目对象

项目对象包含以下字段：

字段	类型	描述
`project_id`	string	项目唯一标识符
`name`	string	项目名称
`favorite`	boolean	是否收藏
`device_count`	integer	项目下的设备总数
`offline_device_count`	integer	离线设备数量
`created_at`	string	创建时间（ISO 8601 格式）

获取项目列表

获取当前组织下的所有项目。

GET /api/v2/projects/

请求头

参数	必填	描述
`Authorization`	是	Bearer Token 认证

响应示例

json

[
    {
        "project_id": "proj_abcdefghij",
        "name": "智慧农业项目",
        "favorite": true,
        "device_count": 15,
        "offline_device_count": 2,
        "created_at": "2025-01-15T08:30:00Z"
    },
    {
        "project_id": "proj_klmnopqrst",
        "name": "环境监测项目",
        "favorite": false,
        "device_count": 8,
        "offline_device_count": 0,
        "created_at": "2025-02-20T14:15:00Z"
    }
]

代码示例

PythoncURL

python

import requests

API_BASE = "https://dl.yengear.com/api/v2"
ACCESS_TOKEN = "your_access_token"

def get_projects():
    """获取项目列表"""
    response = requests.get(
        f"{API_BASE}/projects/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    )
    return response.json()

# 调用示例
projects = get_projects()
for project in projects:
    print(f"{project['name']}: {project['device_count']} 台设备")

bash

curl -X GET "https://dl.yengear.com/api/v2/projects/" \
     -H "Authorization: Bearer your_access_token"

获取项目详情

获取指定项目的详细信息。

GET /api/v2/projects/{project_id}/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符

响应示例

json

{
    "project_id": "proj_abcdefghij",
    "name": "智慧农业项目",
    "favorite": true,
    "device_count": 15,
    "offline_device_count": 2,
    "created_at": "2025-01-15T08:30:00Z"
}

错误响应

状态码	描述
`404`	项目不存在

创建项目

在当前组织下创建新项目。

POST /api/v2/projects/

请求参数

参数	类型	必填	描述
`name`	string	是	项目名称
`project_id`	string	否	自定义项目 ID，不填则自动生成

请求示例

json

{
    "name": "新建监测项目"
}

响应示例

json

{
    "project_id": "proj_uvwxyzabcd",
    "name": "新建监测项目",
    "favorite": false,
    "device_count": 0,
    "offline_device_count": 0,
    "created_at": "2025-03-21T10:00:00Z"
}

代码示例

PythoncURL

python

def create_project(name):
    """创建项目"""
    response = requests.post(
        f"{API_BASE}/projects/",
        headers={
            "Authorization": f"Bearer {ACCESS_TOKEN}",
            "Content-Type": "application/json"
        },
        json={"name": name}
    )
    return response.json()

# 调用示例
new_project = create_project("温室大棚监测")
print(f"项目已创建: {new_project['project_id']}")

bash

curl -X POST "https://dl.yengear.com/api/v2/projects/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"name": "温室大棚监测"}'

更新项目

更新指定项目的信息。支持部分更新，只需提供要修改的字段。

PUT /api/v2/projects/{project_id}/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符

请求参数

参数	类型	必填	描述
`name`	string	否	项目名称
`favorite`	boolean	否	是否收藏

注意

project_id 创建后不可修改。

请求示例

json

{
    "name": "更新后的项目名称",
    "favorite": true
}

响应示例

json

{
    "project_id": "proj_abcdefghij",
    "name": "更新后的项目名称",
    "favorite": true,
    "device_count": 15,
    "offline_device_count": 2,
    "created_at": "2025-01-15T08:30:00Z"
}

代码示例

PythoncURL

python

def update_project(project_id, **kwargs):
    """更新项目信息"""
    response = requests.put(
        f"{API_BASE}/projects/{project_id}/",
        headers={
            "Authorization": f"Bearer {ACCESS_TOKEN}",
            "Content-Type": "application/json"
        },
        json=kwargs
    )
    return response.json()

# 调用示例
updated = update_project("proj_abcdefghij", name="新名称", favorite=True)

bash

curl -X PUT "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"name": "新名称", "favorite": true}'

删除项目

删除指定项目。

DELETE /api/v2/projects/{project_id}/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符

警告

删除项目前，请确保项目下没有设备。如果项目下存在设备，需要先解绑或转移设备。

响应

成功删除返回 HTTP 状态码 204 No Content，无响应体。

代码示例

PythoncURL

python

def delete_project(project_id):
    """删除项目"""
    response = requests.delete(
        f"{API_BASE}/projects/{project_id}/",
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    )
    return response.status_code == 204

# 调用示例
if delete_project("proj_abcdefghij"):
    print("项目已删除")

bash

curl -X DELETE "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/" \
     -H "Authorization: Bearer your_access_token"

转移项目

将项目转移到其他组织。转移后，项目及其下所有设备的归属将变更为目标组织。

POST /api/v2/projects/{project_id}/transfer/

路径参数

参数	类型	必填	描述
`project_id`	string	是	项目唯一标识符

请求参数

参数	类型	必填	描述
`target_org_slug`	string	是	目标组织的 slug 标识

请求示例

json

{
    "target_org_slug": "target-organization"
}

响应

成功转移返回 HTTP 状态码 200 OK，无响应体。

错误响应

状态码	错误信息	描述
`400`	项目已属于目标组织	不能转移到当前所属组织
`404`	目标组织不存在	指定的目标组织不存在

代码示例

PythoncURL

python

def transfer_project(project_id, target_org_slug):
    """转移项目到其他组织"""
    response = requests.post(
        f"{API_BASE}/projects/{project_id}/transfer/",
        headers={
            "Authorization": f"Bearer {ACCESS_TOKEN}",
            "Content-Type": "application/json"
        },
        json={"target_org_slug": target_org_slug}
    )
    return response.status_code == 200

# 调用示例
if transfer_project("proj_abcdefghij", "new-organization"):
    print("项目转移成功")

bash

curl -X POST "https://dl.yengear.com/api/v2/projects/proj_abcdefghij/transfer/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"target_org_slug": "new-organization"}'

提示

项目管理 ​

接口概览 ​

项目对象 ​

获取项目列表 ​

请求头 ​

响应示例 ​

代码示例 ​

获取项目详情 ​

路径参数 ​

响应示例 ​

错误响应 ​

创建项目 ​

请求参数 ​

请求示例 ​

响应示例 ​

代码示例 ​

更新项目 ​

路径参数 ​

请求参数 ​

请求示例 ​

响应示例 ​

代码示例 ​

删除项目 ​

路径参数 ​

响应 ​

代码示例 ​

转移项目 ​

路径参数 ​

请求参数 ​

请求示例 ​

响应 ​

错误响应 ​

代码示例 ​

项目管理

接口概览

项目对象

获取项目列表

请求头

响应示例

代码示例

获取项目详情

路径参数

响应示例

错误响应

创建项目

请求参数

请求示例

响应示例

代码示例

更新项目

路径参数

请求参数

请求示例

响应示例

代码示例

删除项目

路径参数

响应

代码示例

转移项目

路径参数

请求参数

请求示例

响应

错误响应

代码示例