Immich项目API中搜索已删除资源的正确使用方法

在Immich项目的API使用过程中，部分开发者可能会遇到搜索已删除资源时无法正确过滤的问题。本文将从技术实现角度分析这一现象，并详细介绍正确的API调用方法。

问题背景分析

Immich作为一个自托管的照片和视频管理平台，提供了完善的API接口用于资源管理。其中/api/search/metadata端点用于搜索资源元数据，但开发者需要注意其过滤机制的特殊性。

常见误区

许多开发者尝试通过以下方式过滤已删除资源：

• 使用isTrashed字段作为请求参数
• 期望通过isTrashedOnly等不存在的参数进行过滤

这些尝试都无法生效，因为Immich API的设计采用了不同的过滤逻辑。

正确实现方法

Immich API提供了专门的参数来处理已删除资源：

1. withDeleted参数
   该参数为布尔值，设置为true时会在返回结果中包含已删除的资源，但不会过滤掉未删除的资源。

2. trashedAfter参数
   可以配合withDeleted使用，指定一个时间戳，只返回在该时间之后被删除的资源。

最佳实践示例

以下是一个有效的API请求示例，用于获取所有已删除的图片资源：

{
  "withDeleted": true,
  "trashedAfter": "2000-01-01T00:00:00Z",
  "order": "desc",
  "page": 1,
  "type": "IMAGE"
}

分页处理技巧

Immich API默认返回250条记录，开发者需要通过分页参数获取更多结果：

• 使用page参数指定页码
• 结合take参数控制每页数量

高级使用建议

对于大规模资源管理场景，建议：

1. 先获取时间分段信息，再按时间段查询
2. 对返回结果进行本地缓存处理
3. 考虑使用批量操作接口提高效率

通过理解Immich API的设计理念和正确使用相关参数，开发者可以高效地管理资源删除状态，实现各种自动化管理需求。