此页面由 AI 自动翻译。查看英文原版
最后更新

本页目录

  • 先决条件
  • 总结
  • 后续步骤

使用 Snaps

最后更新
本指南将引导您使用 Luxonis Hub GraphQL API 以编程方式管理 Snaps。您将学习如何列出 Snaps、检索详细信息以及删除它们。

先决条件

在开始之前,您应该熟悉 GraphQL 基础知识。如果您是 GraphQL 新手,请查阅 关于 GraphQL。您还需要一个 API 密钥来验证您的请求。
要与 Luxonis Hub API 交互,您需要一个 API 密钥。API 密钥提供对您团队资源的完全访问权限。按照 API 密钥文档在 Luxonis Hub Web UI 中创建密钥。获得 API 密钥后,将其包含在 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。删除作为后台任务异步进行。

方法 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:按过滤器删除

删除符合特定条件的 Snaps:
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: 删除来自特定设备的 Snaps
  • deviceAppId: 删除来自特定应用程序实例的 Snaps
  • deviceAppIdentifier: 删除来自具有此标识符的应用程序的 Snaps
  • createdFrom: 删除在此时间戳之后创建的 Snaps
  • createdTo: 删除在此时间戳之前创建的 Snaps
  • name: 删除具有此名称的 Snaps
  • tags: 删除具有这些标签的 Snaps
  • extras: 删除具有这些自定义元数据的 Snaps
  • withFilesClassifiedAs: 删除包含此分类文件的 Snaps

检查删除状态

使用 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: 一个或多个 Snap ID 不属于您的团队
  • BG_TASK_LIMIT_REACHED: 后台任务过多,请稍后重试

总结

在本指南中,您学习了如何:
  • 使用分页和过滤列出 Snaps
  • 检索有关单个 Snaps 的详细信息
  • 使用预签名 URL 下载 Snap 文件
  • 通过 ID 或使用过滤器删除 Snaps
  • 通过后台任务跟踪删除进度

后续步骤