目录 API 现在会返回具有视频和 3D 模型媒体的产品的相关媒体，并支持按媒体类型筛选搜索结果。您可以仅请求附有视频或 3D 模型媒体的产品，匹配的响应中将包含指向这些资产的链接。此新筛选器为可选功能，现有查询仍会返回相同的产品。
变更内容
现在，search_catalog、get_product和lookup_catalog会在产品的媒体数组中返回视频和3D模型资产，而此前仅支持图片。
目录API搜索接受新的过滤器catalog.filters.media，每个条目指定一种媒体类型：image、video或model_3d。这些条目通过AND组合，因此同时请求video和model_3d将仅返回同时具备这两种媒体的产品。
如果类型无法识别，请求不会失败；API会忽略该类型并在result.messages[]中以代码not_found进行报告。
匹配的产品将附带媒体资产 URL，这样客户端无需二次请求即可渲染产品媒体。
此前，您需要先请求产品，逐一检查其是否包含可用的媒体，然后丢弃没有媒体的产品。新的筛选器取代了这种模式。现有筛选器、端点均未发生变化，也无需进行迁移。
新的媒体类型需要声明Shopify全局目录扩展（dev.shopify.catalog.global）的草稿版本，在代理配置文件中声明草稿版本只需一行更改；若不声明，媒体字段将仅返回图片。该草稿模式将在下一个UCP版本中转为稳定版。
注意：按媒体类型过滤适用于<code><span class="PreventFireFoxApplyingGapToWBR">search<wbr/></span>_catalog</code>。即使不设置过滤条件，<code><span class="PreventFireFoxApplyingGapToWBR">get<wbr/></span>_product</code>和<code><span class="PreventFireFoxApplyingGapToWBR">lookup<wbr/></span>_catalog</code>也会返回资产URL。若使用稳定版扩展并应用过滤，过滤条件会被尊重，但响应中仍仅包含图片。
受影响对象
此变更会影响调用目录 API 的以下应用和工具：
- 使用search_catalog并希望按image、video或model_3d媒体类型筛选产品
- 依赖search_catalog、get_product或lookup_catalog响应中的产品媒体资产URL
若要接收视频和3D模型资产，客户端必须在代理配置文件中声明Shopify全局目录扩展（dev.shopify.catalog.global）的草稿版本；否则，媒体字段将继续仅返回图片。
为何重要
如果您正在构建增强现实试穿、3D 产品展示或优先使用摄像头的购物体验，则无法在没有可渲染资产的情况下使用产品。在查询时针对特定媒体进行筛选，可以消除“获取-检查-丢弃”的循环；而在同一响应中返回资产 URL，则可减少每个产品的额外往返请求。
操作指南
如果您不需要在目录结果中使用视频或 3D 媒体，则无需采取任何操作。现有查询将继续正常工作并返回相同的产品。
- 在代理配置文件中声明dev.shopify.catalog.global的草稿版本，或指向Shopify发布的草稿配置文件。
- 在search_catalog请求中添加catalog.filters.media，并指定所需的媒体类型。
- 从响应的媒体数组中读取资产URL。视频和3D条目包含一个sources数组，其中每种文件格式对应一个条目。
- 处理已请求媒体存在但所需格式不匹配的产品。
- 通过检查确保每个返回的产品都至少包含一个所请求类型的资产 URL。如果仅返回图片，说明您的配置仍处于稳定版。
相关文档
- 目录 API 参考
- 智能体配置文件