# 关于 GraphQL

当您需要从自己的后端或服务器端工具调用 Luxonis Hub GraphQL 控制 API 时，请使用此页面。它解释了公共请求结构、关键的 Hub 特有边界以及在进入工作流指南或模式参考之前需要了解的常见模式。

跳转到：

 * [开始这里](#Start%20here)
 * [请求结构](#Request%20shape)
 * [示例查询](#Example%20queries)
 * [Hub 特有边界](#Hub-specific%20boundaries)
 * [您在模式中会看到的核心概念](#Core%20concepts%20you%20will%20see%20in%20the%20schema)

## 开始这里

发送 GraphQL 请求到：

```http
https://api.cloud.luxonis.com/graphql
```

使用 HTTP POST，并包含：

 * Content-Type: application/json
 * Authorization: Bearer <your_api_key>

对于外部集成，请使用公共的 team { ... } 接口，并将 Hub API 密钥仅保存在您的后端。如果您尚未设置身份验证，请参阅 [API 密钥](https://docs.luxonis.com/cloud/api/api-keys.md)。

## 请求结构

每个 GraphQL 请求都具有相同的实际结构：

 1. 操作定义，例如 query 或 mutation，以及操作名称和可选的变量定义。
 2. 选择集，列出您想要返回的确切字段。
 3. 变量对象，作为 JSON 与查询一起发送，使值与文档分离。
 4. HTTP 传输封装，包含 Authorization 和 Content-Type 标头。

这是典型的 Luxonis Hub 请求：

```json
{
  "query": "query Devices($first: Int!, $after: String) { team { devices(first: $first, after: $after) { nodes { id name status } } } }",
  "variables": {
    "first": 25,
    "after": null
  }
}
```

因为 GraphQL 响应会镜像您的选择集，所以您可以只请求工作流需要的字段，并在以后添加更多字段，无需更改端点。

## 示例查询

### 列出设备

使用 team { ... } 作为公共控制平面集成的根：

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

### 更新设备状态

变更操作会更改控制平面状态：

```graphql
mutation UpdateDevice($input: UpdateDeviceInput!) {
  updateDevice(input: $input) {
    clientMutationId
  }
}
```

模式定义了 UpdateDeviceInput 内允许的确切字段，因此在编写生产流程之前，请使用参考页面或自省来检查当前的输入结构。

## Hub 特有边界

### 公共接口

对于外部集成，GraphQL 控制 API 应理解为公共的 team { ... } 接口。

### 身份验证边界

Hub API 密钥是仅限后端的机密。推荐的客户集成模型是：

 1. 您的用户向您的前端和后端进行身份验证。
 2. 您的后端存储 Hub API 密钥。
 3. 您的后端调用 Hub GraphQL。
 4. 您的前端仅接收所需的派生有效负载。

### 模式自省

GraphQL 自省可用。在检查类型、字段和输入结构时，请将自省与官方指南和参考页面一起使用。

### 实时行为

目前，GraphQL 订阅不是公共集成路径。使用查询和变更进行控制平面工作，使用流式传输/引导指南进行浏览器端设备或应用会话。

## 您在模式中会看到的核心概念

您不需要完整的 GraphQL 教程即可使用 Hub，但这些概念在模式和示例中经常出现：

 * 对象类型和字段 定义您可以查询的资源和属性，例如 Device、Team 或 App。
 * 参数和变量 让您可以传递分页、过滤和输入值，而无需重写查询字符串。
 * 输入对象 对结构化变更输入（例如 UpdateDeviceInput）进行分组。
 * 枚举、接口和联合 描述受限的值和多态响应形状。
 * 连接 是使用 nodes、edges 和 pageInfo 等字段的分页模式。

如果您需要直接检查这些结构，请在 GraphQL 客户端中使用自省，或继续查看控制 API 参考页面。

## 后续步骤

 * 继续阅读 [集成指南](https://docs.luxonis.com/cloud/api/guides.md)，了解端到端的后端工作流。
 * 使用 [流式传输和可视化工具](https://docs.luxonis.com/cloud/api/guides/streaming-and-visualizer.md) 进行浏览器连接引导和远程会话流。
 * 探索
   [模式参考](https://docs.luxonis.com/cloud/api/reference/control-api/schema.md)、[查询](https://docs.luxonis.com/cloud/api/reference/control-api/queries.md)
   和 [变更](https://docs.luxonis.com/cloud/api/reference/control-api/mutations.md)，了解当前的控制 API 接口。