# 列出设备并检查设备状态

当您需要枚举 Luxonis Hub 团队中的设备、详细检查某个设备，并决定是否继续执行应用生命周期或支持的更新操作时，请使用本指南。

## 前提条件

开始之前，您应当熟悉 GraphQL 基础知识。如果您是 GraphQL 新手，请查看 [关于 GraphQL](https://docs.luxonis.com/cloud/api/graphql.md)。

您还需要一个 API 密钥来验证请求。使用 [API 密钥](https://docs.luxonis.com/cloud/api/api-keys.md) 在 Luxonis Hub Web 界面中创建一个，然后将其包含在 Authorization
请求头中：

```bash
Authorization: Bearer <your_api_key>
```

> **将 API 密钥保存在后端**
> API 密钥可以访问您团队的公共控制平面。请将其存储在后端或其他服务器端工具中，而不是放在不可信的客户端上。

## 列出设备

首先查询对您的团队可见的设备。获得设备 ID，以便后续用于读取或变更操作。

```graphql
query {
  team {
    devices(first: 10) {
      nodes {
        id
        name
        status
        model
        architecture
        version
        lastContactAt
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

利用此响应快速回答以下实际问题：

 * 团队中存在哪些设备
 * 它们当前是 ONLINE 还是 OFFLINE
 * 哪个设备 ID 用于后续查询
 * 是否还有更多页面

### 在更大的设备群中分页

要获取下一页，请将上一页的 endCursor 传递给 after 参数。

```graphql
query($after: String) {
  team {
    devices(first: 10, after: $after) {
      nodes {
        id
        name
        status
      }
      pageInfo {
        hasNextPage
        endCursor
      }
    }
  }
}
```

变量：

```json
{
  "after": "cursor_from_previous_response"
}
```

### 按状态或设备组筛选设备

当工作流需要缩小设备范围时，可按状态或设备组进行筛选。

```graphql
query {
  team {
    devices(filter: { status: ONLINE }, first: 10) {
      nodes {
        id
        name
        status
      }
    }
  }
}
```

可用的筛选条件包括：

 * status：ONLINE 或 OFFLINE
 * deviceGroupId：按特定设备组 ID 筛选
 * adoptKeyId：按特定采纳密钥筛选已采纳的设备

## 检查单个设备

使用列表查询返回的一个设备 ID 来获取在采取操作前所需的运行详细信息。

```graphql
query($deviceId: ID!) {
  team {
    device(deviceId: $deviceId) {
      id
      name
      status
      model
      serialNumber
      architecture
      kind
      capabilities
      version
      lastContactAt
      lastStatusChangeAt
      networkInterfaces {
        interfaceName
        ipv4Address
        macAddress
      }
      availableUpgrade {
        id
        version
        semver
      }
    }
  }
}
```

变量：

```json
{
  "deviceId": "device-id-from-list"
}
```

利用此响应确认：

 * 设备身份和当前连接状态
 * 目标是 OAK 还是 SELF_HOSTED
 * 设备路径可用的能力
 * 网络详细信息是否解释了当前可达性状态
 * availableUpgrade 是否提供了支持的更新候选

> **只请求工作流需要的字段**
> GraphQL 的选择集是灵活的。从上述字段开始，然后根据设备管理工作流的实际使用情况精简或扩展查询。

## 从检查转向操作

在能够列出设备并检查目标设备后，下一步通常是对该状态采取操作，而不是直接跳入交互式浏览器会话。

常见的后续任务包括：

 * 在设备上安装应用或检查已安装的应用状态
 * 启动或停止已安装的应用
 * 当 availableUpgrade 存在时，触发支持的 OTA 或固件更新
 * 只有当目标是远程交互、日志或可视化（而非控制平面操作）时，才使用浏览器端会话

对于外部集成，请将写操作保留在后端，并遵循 [集成架构](https://docs.luxonis.com/cloud/api/guides/integration-architecture.md) 中描述的客户自有架构。

## 验证结果

当以下所有条件成立时，您就可以进行下一个工作流了：

 * 您可以调用 team.devices 并获得预期的设备群列表
 * 您可以使用返回的一个设备 ID 调用 team.device
 * 您可以判断设备是否在线、运行哪个版本，以及是否存在支持的更新数据
 * 您知道下一步是应用生命周期变更、更新流程还是交互式会话

## 后续步骤

### 变更操作参考

从设备读取操作进入团队范围的写操作，例如设备和应用管理变更操作。

[变更操作参考](https://docs.luxonis.com/cloud/api/reference/control-api/mutations.md)

### 管理应用

安装应用、控制运行状态，并了解设备检查后的下一步操作。

[管理应用](https://docs.luxonis.com/cloud/features/application-management/manage-applications.md)

### 更新设备（OTA）

查看目前支持的更新路径以及 OTA 操作与设备状态的关系。

[更新设备（OTA）](https://docs.luxonis.com/cloud/features/device-management/ota-updates.md)

### 流式传输和可视化工具

当下一步是浏览器端实时交互而非控制平面操作时，请使用此路径。

[流式传输和可视化工具](https://docs.luxonis.com/cloud/api/guides/streaming-and-visualizer.md)