使用快照

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

创建快照

要从您的应用程序发送或创建快照，您必须使用 DepthAI。请查看 DepthAI 中的快照文档，了解如何从应用程序发出快照的详细信息。本指南侧重于通过 GraphQL API查询、过滤和管理现有快照。

先决条件

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

要与 Luxonis Hub API 交互，您需要一个 API 密钥。API 密钥可完全访问您团队的资源。遵循 API 密钥文档，在 Luxonis Hub Web UI 中创建密钥。获得 API 密钥后，将其包含在 Authorization 标头中：

Command Line

1Authorization: Bearer <your_api_key>

使用 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 个快照
nodes - 快照对象数组
pageInfo - 分页元数据（下一页的游标）

快照字段说明：

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

分页

要获取下一页，请使用上一个响应中的 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}

过滤快照

按各种条件过滤快照以查找特定数据：按时间范围过滤：

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 检索特定快照的详细信息，包括文件下载 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：创建快照的设备序列号
sourceAppIdentifier：发出快照的应用程序标识符

通过其 ID 或应用过滤器来删除快照。删除是作为后台任务异步进行的。

异步删除

快照删除不是即时的。API 返回一个 bgTaskId，您可以使用它来跟踪删除进度。

方法 1：按 ID 删除

使用其 ID 删除特定快照：

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 集成示例

本页目录

使用快照

先决条件

步骤 1：获取 API 密钥

步骤 2：列出快照

基本列表查询

分页

过滤快照

步骤 3：加载单个快照

步骤 4：删除快照

方法 1：按 ID 删除

方法 2：按过滤器删除

检查删除状态

状态值

摘要

后续步骤

本页目录

使用快照View as Markdown

先决条件

步骤 1：获取 API 密钥

步骤 2：列出快照

基本列表查询

分页

过滤快照

步骤 3：加载单个快照

步骤 4：删除快照

方法 1：按 ID 删除

方法 2：按过滤器删除

检查删除状态

状态值

摘要

后续步骤

使用快照