使用 Snaps

本指南将带你以编程方式通过 Luxonis Hub GraphQL API 管理 Snaps。你将学习如何列出 Snaps、检索详细信息以及删除它们。

创建 Snaps

要从你的应用程序发送或创建 Snaps，必须使用 DepthAI。请参阅 DepthAI 中的 Snaps 文档，了解如何从应用程序中发出 Snaps。本指南重点介绍如何通过 GraphQL API 查询、筛选和管理现有的 Snaps。

前提条件

在开始之前，你应该熟悉 GraphQL 基础知识。如果你是 GraphQL 新手，请查看关于 GraphQL。你还需要一个 API Key 来认证你的请求。

要与 Luxonis Hub API 交互，你需要一个 API Key。API Key 提供对团队资源的完全访问权限。请参考 API Keys 文档，在 Luxonis Hub Web UI 中创建一个 Key。一旦获得 API Key，将其包含在 Authorization 头中：

Command Line

1Authorization: Bearer <your_api_key>

使用 snaps 查询来检索团队中所有 Snaps 的列表。此查询支持基于游标的分页，以便高效浏览大型数据集。

基本列表查询

Graphql

1query {
2  team {
3    snaps(first: 10) {
4      nodes {
5        id
6        name
7        createdAt
8        tags
9        extras
10        files {
11          id
12          name
13          classification
14        }
15        sourceDeviceId
16        sourceAppIdentifier
17      }
18      pageInfo {
19        hasNextPage
20        endCursor
21      }
22    }
23  }
24}

查询解析：

first: 10 - 限制结果为 10 个 Snaps
nodes - Snap 对象数组
pageInfo - 分页元数据（下一页的游标）

Snap 字段说明：

id：唯一 Snap 标识符
name：Snap 名称（例如 "car_detected"、"data_collection"）
createdAt：Snap 创建时间戳
tags：用于分组的标签数组（例如 "night"、"dataset_v2"）
extras：包含自定义键值对的 JSON 对象，用于可搜索的元数据
files：附加文件数组（图像、视频、点云等）
sourceDeviceId：创建该 Snap 的设备 ID
sourceAppIdentifier：创建该 Snap 的应用程序

分页

要获取下一页，请使用上一响应中的 endCursor：

Graphql

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

变量：

JSON

1{
2  "after": "cursor_from_previous_response"
3}

筛选 Snaps

通过多种条件筛选 Snaps 以查找特定数据：按时间范围筛选：

Graphql

1query($from: DateTime!, $to: DateTime!) {
2  team {
3    snaps(
4      first: 10,
5      filter: {
6        createdFrom: $from,
7        createdTo: $to
8      }
9    ) {
10      nodes {
11        id
12        name
13        createdAt
14      }
15    }
16  }
17}

变量：

JSON

1{
2  "from": "2024-01-01T00:00:00Z",
3  "to": "2024-02-01T00:00:00Z"
4}

按设备筛选：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { deviceId: "device-id" }
6    ) {
7      nodes {
8        id
9        name
10        sourceDeviceId
11      }
12    }
13  }
14}

按应用标识符筛选：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { deviceAppIdentifier: "my-app" }
6    ) {
7      nodes {
8        id
9        name
10        sourceAppIdentifier
11      }
12    }
13  }
14}

按名称筛选：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { name: "car_detected" }
6    ) {
7      nodes {
8        id
9        name
10      }
11    }
12  }
13}

按标签筛选：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { tags: ["night", "validation"] }
6    ) {
7      nodes {
8        id
9        name
10        tags
11      }
12    }
13  }
14}

按额外字段（自定义元数据）筛选：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { extras: { scene: "warehouse", lighting: "low" } }
6    ) {
7      nodes {
8        id
9        name
10        extras
11      }
12    }
13  }
14}

按文件分类筛选：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: { withFilesClassifiedAs: [IMAGE_COLOR, VIDEO] }
6    ) {
7      nodes {
8        id
9        name
10        files {
11          classification
12        }
13      }
14    }
15  }
16}

可用的文件分类：

IMAGE_COLOR：彩色图像
IMAGE_STEREO_LEFT：左立体图像
IMAGE_STEREO_RIGHT：右立体图像
VIDEO：视频文件
POINTCLOUD：点云数据
ANNOTATION：注释文件
DISPARITY：视差图
UNKNOWN_FILE：其他文件类型

组合多个筛选条件：

Graphql

1query {
2  team {
3    snaps(
4      first: 10,
5      filter: {
6        deviceId: "device-id",
7        tags: ["validation"],
8        createdFrom: "2024-01-01T00:00:00Z"
9      }
10    ) {
11      nodes {
12        id
13        name
14        tags
15        createdAt
16      }
17    }
18  }
19}

通过 ID 检索特定 Snap 的详细信息，包括文件下载 URL。

Graphql

1query($snapId: ID!) {
2  team {
3    snap(snapId: $snapId) {
4      id
5      name
6      createdAt
7      tags
8      extras
9      files {
10        id
11        name
12        hash
13        mimeType
14        size
15        presignedUrl
16        classification
17      }
18      sourceDeviceId
19      sourceSerialNumber
20      sourceAppIdentifier
21    }
22  }
23}

变量：

JSON

1{
2  "snapId": "snap-id-from-list"
3}

响应示例：

JSON

1{
2  "data": {
3    "team": {
4      "snap": {
5        "id": "snap-abc123",
6        "name": "car_detected",
7        "createdAt": "2024-01-15T10:30:00Z",
8        "tags": ["validation", "warehouse"],
9        "extras": { "scene": "warehouse", "lighting": "low" },
10        "files": [
11          {
12            "id": "file-xyz789",
13            "name": "image.jpg",
14            "hash": "abc123...",
15            "mimeType": "image/jpeg",
16            "size": 524288,
17            "presignedUrl": "https://storage.example.com/snap-abc123/image.jpg?signature=...",
18            "classification": "IMAGE_COLOR"
19          }
20        ],
21        "sourceDeviceId": "device-123",
22        "sourceSerialNumber": "OAK123456",
23        "sourceAppIdentifier": "detection-app"
24      }
25    }
26  }
27}

关键字段说明：

presignedUrl：直接、有时限的文件下载 URL。使用此 URL 无需身份验证即可下载文件。
hash：用于完整性校验的文件校验和
mimeType：文件的 MIME 类型（例如 "image/jpeg"、"video/mp4"）
size：文件大小（字节）
sourceSerialNumber：创建该 Snap 的设备序列号
sourceAppIdentifier：发出该 Snap 的应用程序标识符

通过 ID 或应用筛选条件来删除 Snaps。删除操作作为后台任务异步执行。

异步删除

Snap 删除不是即时的。API 返回一个 bgTaskId，可用于跟踪删除进度。

方法 1：按 ID 删除

通过 ID 删除特定 Snaps：

Graphql

1mutation DeleteSnapsByIds($ids: [ID!]!) {
2  team {
3    deleteSnapsByIds(ids: $ids) {
4      status
5      bgTaskId
6    }
7  }
8}

变量：

JSON

1{
2  "ids": ["snap-id-1", "snap-id-2", "snap-id-3"]
3}

响应:

JSON

1{
2  "data": {
3    "team": {
4      "deleteSnapsByIds": {
5        "status": "SUCCESS",
6        "bgTaskId": "bg-task-abc123"
7      }
8    }
9  }
10}

方法2：按过滤器删除

删除符合特定条件的快照：

Graphql

1mutation DeleteSnapsByFilter {
2  team {
3    deleteSnapsByFilter(
4      filter: {
5        deviceId: "device-id",
6        createdFrom: "2024-01-01T00:00:00Z",
7        createdTo: "2024-02-01T00:00:00Z",
8        tags: ["test"]
9      }
10    ) {
11      status
12      bgTaskId
13    }
14  }
15}

可用的删除过滤器：

deviceId：删除指定设备的快照
deviceAppId：删除指定应用实例的快照
deviceAppIdentifier：删除具有此标识符的应用的快照
createdFrom：删除此时间戳之后创建的快照
createdTo：删除此时间戳之前创建的快照
name：删除此名称的快照
tags：删除包含这些标签的快照
extras：删除包含这些自定义元数据的快照
withFilesClassifiedAs：删除包含此分类文件的快照

检查删除状态

使用 bgTaskId 跟踪删除进度：

Graphql

1query($bgTaskId: ID!) {
2  team {
3    bgTask(bgTaskId: $bgTaskId) {
4      id
5      state {
6        deletedCount
7        totalCount
8      }
9      createdAt
10      completedAt
11      failedAt
12    }
13  }
14}

变量：

JSON

1{
2  "bgTaskId": "bg-task-id-from-deletion"
3}

响应（进行中）：

JSON

1{
2  "data": {
3    "team": {
4      "bgTask": {
5        "id": "bg-task-abc123",
6        "state": {
7          "deletedCount": 150,
8          "totalCount": 500
9        },
10        "createdAt": "2024-01-15T11:00:00Z",
11        "completedAt": null,
12        "failedAt": null
13      }
14    }
15  }
16}

响应（已完成）：

JSON

1{
2  "data": {
3    "team": {
4      "bgTask": {
5        "id": "bg-task-abc123",
6        "state": {
7          "deletedCount": 500,
8          "totalCount": 500
9        },
10        "createdAt": "2024-01-15T11:00:00Z",
11        "completedAt": "2024-01-15T11:05:30Z",
12        "failedAt": null
13      }
14    }
15  }
16}

状态值

删除响应中的 status 字段可能为：

SUCCESS：删除任务创建成功
IDS_NOT_FROM_TEAM：一个或多个快照 ID 不属于您的团队
BG_TASK_LIMIT_REACHED：正在运行的后台任务过多，请稍后重试

总结

在本指南中，您学习了如何：

分页列出快照并进行过滤
获取单个快照的详细信息
使用预签名 URL 下载快照文件
按 ID 或使用过滤器删除快照
通过后台任务跟踪删除进度

要点总结

使用标签和附加信息实现快照的有效组织和搜索
善用过滤器查询数据的特定子集
删除是异步操作 - 务必通过 bgTaskId 检查进度
预签名 URL 有时间限制 - 请及时下载文件

下一步

查看快照功能文档了解如何通过 Luxonis Hub UI 管理快照
学习如何使用 DepthAI 从您的应用发送快照
浏览完整模式参考了解所有与快照相关的类型和变更操作
发现更多自动化指南获取其他 API 集成示例

本页目录

使用 Snaps

前提条件

步骤 1：获取 API Key

步骤 2：列出 Snaps

基本列表查询

分页

筛选 Snaps

步骤 3：加载单个 Snap

步骤 4：删除 Snaps

方法 1：按 ID 删除

方法2：按过滤器删除

检查删除状态

状态值

总结

下一步