使用 Snaps
最后更新
创建 Snaps
要从您的应用程序发送或创建 Snaps,您必须使用 DepthAI。请查阅 DepthAI 中的 Snaps 文档,了解如何从您的应用程序发出 Snaps 的详细信息。本指南重点介绍通过 GraphQL API 查询、过滤和管理现有 Snaps。
先决条件
要与 Luxonis Hub API 交互,您需要一个 API 密钥。API 密钥提供对您团队资源的完全访问权限。按照 API 密钥文档在 Luxonis Hub Web UI 中创建密钥。获得 API 密钥后,将其包含在
Authorization 标头中:Command Line
1Authorization: Bearer <your_api_key>使用 查询分解:要获取下一页,请使用上一个响应中的 变量:通过各种条件过滤 Snaps 以查找特定数据:按时间范围过滤:变量:按设备过滤:按应用程序标识符过滤:按名称过滤:按标签过滤:按附加信息(自定义元数据)过滤:按文件分类过滤:可用文件分类:
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 个 Snapsnodes- Snap 对象数组pageInfo- 分页元数据(下一页的游标)
id: 唯一的 Snap 标识符name: Snap 名称(例如,"car_detected"、"data_collection")createdAt: Snap 创建时的时间戳tags: 用于分组的标签数组(例如,"night"、"dataset_v2")extras: 包含可搜索元数据的自定义键值对的 JSON 对象files: 附加文件数组(图像、视频、点云等)sourceDeviceId: 创建 Snap 的设备 IDsourceAppIdentifier: 创建 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
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。删除作为后台任务异步进行。使用其 ID 删除特定的 Snaps:变量:响应:删除符合特定条件的 Snaps:可用的删除过滤器:使用 变量:响应(进行中):响应(已完成):删除响应中的
异步删除
Snap 删除不是即时的。API 返回一个
bgTaskId,您可以使用它来跟踪删除进度。方法 1:按 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: 删除来自特定设备的 SnapsdeviceAppId: 删除来自特定应用程序实例的 SnapsdeviceAppIdentifier: 删除来自具有此标识符的应用程序的 SnapscreatedFrom: 删除在此时间戳之后创建的 SnapscreatedTo: 删除在此时间戳之前创建的 Snapsname: 删除具有此名称的 Snapstags: 删除具有这些标签的 Snapsextras: 删除具有这些自定义元数据的 SnapswithFilesClassifiedAs: 删除包含此分类文件的 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
- 通过后台任务跟踪删除进度
关键要点
- 使用 标签和附加信息 进行有效的 Snap 组织和搜索
- 利用 过滤器 查询数据的特定子集
- 删除是异步的 - 始终检查
bgTaskId以获取进度 - 预签名 URL 是有时效的 - 及时下载文件
后续步骤
- 查阅 Snaps 功能文档,了解如何通过 Luxonis Hub UI 管理 Snaps
- 了解如何使用 DepthAI 从您的应用程序发送 Snaps
- 浏览 完整模式参考,了解所有与 Snap 相关的类型和变异
- 发现更多 自动化指南,获取其他 API 集成示例