项目

项目是组织资源的基本单位，用于管理和组织多个设备。通过项目API，您可以创建、查询、更新和删除项目。

获取所有项目

http

GET /api/v2/projects/

接口说明

获取当前组织的所有项目，支持分页和搜索功能。

请求参数

参数	类型	必填	说明
`page`	integer	否	页码，默认为1
`page_size`	integer	否	每页数量，默认为20
`search`	string	否	搜索项目 ID 或名称

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": [
        {
            "project_id": "PRJ123456",
            "name": "项目名称",
            "device_count": 10,
            "offline_device_count": 2,
            "created_at": "2025-03-19T01:20:24Z",
            "updated_at": "2025-03-19T01:20:24Z"
        }
    ],
    "error": null
}

响应参数

字段	类型	说明
`project_id`	string	项目ID
`name`	string	项目名称
`device_count`	integer	项目中的设备总数
`offline_device_count`	integer	离线设备数量
`created_at`	string	创建时间
`updated_at`	string	更新时间

代码示例

Python

python

def get_projects(page=1, page_size=20, search=None):
    """获取所有项目
    
    Args:
        page: 页码，默认为1
        page_size: 每页数量，默认为20
        search: 搜索项目ID或名称
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    params = {
        "page": page,
        "page_size": page_size
    }
    
    if search:
        params["search"] = search
    
    url = f"{API_BASE}/projects/"
    response = requests.get(url, headers=headers, params=params)
    return response.json()

# 使用示例
projects = get_projects(page=1, page_size=10, search="测试项目")
print(f"获取到 {len(projects['data'])} 个项目")

cURL

bash

curl -X GET "https://ums.holdingbyte.com/api/v2/projects/?page=1&page_size=20&search=测试项目" \
     -H "Authorization: Bearer your_access_token"

创建项目

http

POST /api/v2/projects/

接口说明

创建新的项目。

请求参数

参数	类型	必填	说明
`name`	string	是	项目名称

请求示例

请求数据

json

{
    "name": "新项目名称"
}

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": {
        "project_id": "PRJ123456",
        "name": "新项目名称",
        "device_count": 0,
        "offline_device_count": 0,
        "created_at": "2025-03-19T01:20:24Z",
        "updated_at": "2025-03-19T01:20:24Z"
    },
    "error": null
}

代码示例

Python

python

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

# 使用示例
new_project = create_project("新测试项目")
print(f"创建的项目ID: {new_project['data']['project_id']}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/projects/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"name": "新测试项目"}'

更新项目

http

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

接口说明

更新现有项目的信息。

请求参数

参数	类型	必填	说明
`name`	string	是	项目名称

请求示例

请求数据

json

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

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": {
        "project_id": "PRJ123456",
        "name": "更新后的项目名称",
        "device_count": 10,
        "offline_device_count": 2,
        "created_at": "2025-03-19T01:20:24Z",
        "updated_at": "2025-03-19T01:20:24Z"
    },
    "error": null
}

代码示例

Python

python

def update_project(project_id, name):
    """更新项目信息
    
    Args:
        project_id: 项目ID
        name: 更新后的项目名称
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "name": name
    }
    
    url = f"{API_BASE}/projects/{project_id}/"
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# 使用示例
project_id = "PRJ123456"
updated_project = update_project(project_id, "更新后的项目名称")
print(f"项目更新成功: {updated_project['success']}")

cURL

bash

curl -X PUT "https://ums.holdingbyte.com/api/v2/projects/PRJ123456/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"name": "更新后的项目名称"}'

删除项目

http

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

接口说明

删除指定的项目。

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": null,
    "error": null
}

代码示例

Python

python

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

# 使用示例
project_id = "PRJ123456"
result = delete_project(project_id)
print(f"项目删除{'成功' if result['success'] else '失败'}")

cURL

bash

curl -X DELETE "https://ums.holdingbyte.com/api/v2/projects/PRJ123456/" \
     -H "Authorization: Bearer your_access_token"

获取项目设备列表

http

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

接口说明

获取指定项目下的所有设备。

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": [
        {
            "device_id": "DEV123456",
            "name": "设备名称",
            "status": "online",
            "connect_time": "2025-03-19T01:20:24Z"
            // 其他设备信息...
        }
    ],
    "error": null
}

代码示例

Python

python

def get_project_devices(project_id):
    """获取项目下的设备列表
    
    Args:
        project_id: 项目ID
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}"
    }
    
    url = f"{API_BASE}/projects/{project_id}/devices/"
    response = requests.get(url, headers=headers)
    return response.json()

# 使用示例
project_id = "PRJ123456"
devices = get_project_devices(project_id)
print(f"项目中有 {len(devices['data'])} 个设备")

cURL

bash

curl -X GET "https://ums.holdingbyte.com/api/v2/projects/PRJ123456/devices/" \
     -H "Authorization: Bearer your_access_token"

转移项目

http

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

接口说明

将项目及其下的所有设备转移到其他组织。转移时，项目下的所有设备也会被转移到目标组织，并且设备的分组信息会被清空。

请求参数

参数	类型	必填	说明
`target_org_slug`	string	是	目标组织的slug

请求示例

请求数据

json

{
    "target_org_slug": "target-organization"
}

响应

返回数据 (200 OK)

json

{
    "success": true,
    "data": null,
    "error": null
}

代码示例

Python

python

def transfer_project(project_id, target_org_slug):
    """转移项目
    
    Args:
        project_id: 项目ID
        target_org_slug: 目标组织的slug
    """
    headers = {
        "Authorization": f"Bearer {ACCESS_TOKEN}",
        "Content-Type": "application/json"
    }
    
    data = {
        "target_org_slug": target_org_slug
    }
    
    url = f"{API_BASE}/projects/{project_id}/transfer/"
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# 使用示例
project_id = "PRJ123456"
target_org_slug = "target-organization"
result = transfer_project(project_id, target_org_slug)
print(f"项目转移{'成功' if result['success'] else '失败'}")

cURL

bash

curl -X POST "https://ums.holdingbyte.com/api/v2/projects/PRJ123456/transfer/" \
     -H "Authorization: Bearer your_access_token" \
     -H "Content-Type: application/json" \
     -d '{"target_org_slug": "target-organization"}'

错误响应

项目API可能返回的错误响应遵循统一的格式。有关详细的错误码和处理方法，请参阅API错误响应文档。

错误响应示例

json

{
    "success": false,
    "data": null,
    "error": {
        "code": 400,
        "message": "目标组织不存在"
    }
}

注意事项

转移后，项目下所有设备的组织归属会更新
设备的分组信息会被清空
不能转移到当前所属的组织

权限要求

需要组织管理员权限
源组织和目标组织都必须存在

项目 ​

获取所有项目 ​

请求参数 ​

响应 ​

响应参数 ​

代码示例 ​

创建项目 ​

请求参数 ​

请求示例 ​

响应 ​

代码示例 ​

更新项目 ​

请求参数 ​

请求示例 ​

响应 ​

代码示例 ​

删除项目 ​

响应 ​

代码示例 ​

获取项目设备列表 ​

响应 ​

代码示例 ​

转移项目 ​

请求参数 ​

请求示例 ​

响应 ​

代码示例 ​

错误响应 ​

注意事项 ​

权限要求 ​

项目

获取所有项目

请求参数

响应

响应参数

代码示例

创建项目

请求参数

请求示例

响应

代码示例

更新项目

请求参数

请求示例

响应

代码示例

删除项目

响应

代码示例

获取项目设备列表

响应

代码示例

转移项目

请求参数

请求示例

响应

代码示例

错误响应

注意事项

权限要求