Immich项目API中/search/metadata端点使用问题解析

背景介绍

Immich是一款开源的自主托管照片和视频备份解决方案，提供了丰富的API接口供开发者调用。其中/search/metadata端点是用于搜索媒体资源元数据的重要接口。本文将深入分析该接口在实际使用中遇到的一些问题及解决方案。

问题现象

开发者在调用/search/metadata接口时发现，尝试通过isTrashed参数过滤已删除资源时，接口返回结果中仍然包含未删除的资源。这表明过滤条件未被正确应用。

技术分析

接口设计原理

Immich的/search/metadata接口设计采用了灵活的查询参数结构，但需要注意以下几点：

1. 接口不支持直接通过isTrashed字段进行过滤，这是开发者常见的误解
2. 正确的做法是使用withDeleted参数来控制是否包含已删除资源
3. 结合trashedAfter参数可以进一步筛选特定时间后被删除的资源

正确使用方法

经过深入分析，正确的请求参数组合应为：

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

这种组合能够：

• 包含所有已删除资源(withDeleted: true)
• 筛选指定时间后删除的资源(trashedAfter)
• 按时间降序排列(order: desc)
• 只返回图片类型(type: IMAGE)
• 分页获取结果(page: 1)

常见误区

1. 误用isTrashed字段：开发者常误以为可以直接使用响应中的isTrashed字段作为过滤条件，实际上接口设计上不支持这种用法。

2. 分页处理不当：接口默认返回250条记录，需要正确处理分页才能获取完整结果集。

3. 参数组合不当：单独使用withDeleted参数会返回所有资源，必须结合其他条件才能实现精确筛选。

最佳实践建议

1. 明确查询目的：在调用接口前，应明确需要获取的是已删除资源、未删除资源还是全部资源。

2. 合理使用时间筛选：trashedAfter参数可以精确控制时间范围，避免获取过多不必要的数据。

3. 处理分页逻辑：对于大型资源库，必须实现完整的分页处理逻辑，确保获取所有符合条件的结果。

4. 错误处理机制：实现健壮的错误处理机制，应对可能的API变更或参数调整。

总结

Immich的/search/metadata接口提供了强大的资源搜索能力，但需要正确理解其参数设计和使用方法。通过本文的分析，开发者可以避免常见的调用误区，实现高效的资源筛选和管理。在实际应用中，建议结合具体业务需求，灵活运用各种参数组合，以达到最佳的查询效果。