关于 GraphQL

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

跳转到：

开始这里
请求结构
示例查询
Hub 特有边界
您在模式中会看到的核心概念

开始这里

发送 GraphQL 请求到：

Http

1https://api.cloud.luxonis.com/graphql

使用 HTTP POST，并包含：

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

对于外部集成，请使用公共的 team { ... } 接口，并将 Hub API 密钥仅保存在您的后端。如果您尚未设置身份验证，请参阅 API 密钥。

请求结构

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

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

这是典型的 Luxonis Hub 请求：

JSON

1{
2  "query": "query Devices($first: Int!, $after: String) { team { devices(first: $first, after: $after) { nodes { id name status } } } }",
3  "variables": {
4    "first": 25,
5    "after": null
6  }
7}

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

示例查询

列出设备

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

Graphql

1query Devices($first: Int!, $after: String) {
2  team {
3    devices(first: $first, after: $after) {
4      nodes {
5        id
6        name
7        status
8      }
9      pageInfo {
10        hasNextPage
11        endCursor
12      }
13    }
14  }
15}

更新设备状态

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

Graphql

1mutation UpdateDevice($input: UpdateDeviceInput!) {
2  updateDevice(input: $input) {
3    clientMutationId
4  }
5}

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

Hub 特有边界

公共接口

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

身份验证边界

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

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

模式自省

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

实时行为

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

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

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

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

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

后续步骤

继续阅读集成指南，了解端到端的后端工作流。
使用流式传输和可视化工具进行浏览器连接引导和远程会话流。
探索模式参考、查询和变更，了解当前的控制 API 接口。

本页目录