工作流 - 资产

搜索资产

概述

Frame.io 的 API 支持对整个帐户中的资产进行深度、多方面搜索，这与 Web 应用程序中的功能相对应。虽然最常用的筛选条件是“团队”、“项目”和“状态”，但筛选和排序能以独特的方式组合，从而生成由 API 驱动且非常具体的集合。总体而言，除了 account_id、q（查询）和 sort 之外，所有筛选条件都遵循相同的结构，具体说明如下。search-filters.png

请求的页面大小与返回的页面大小不匹配

截至 2022 年 3 月，搜索 API 的分页功能存在一个已知缺陷。在该缺陷修复之前，我们不建议使用搜索 API 来迭代多页结果（即超过 100 个资产），因为请求的页面大小可能与实际返回的资产数量不符。

默认值

触发搜索的 API 请求始终相同：

它始终是同一个请求

向 https://api.frame.io/v2/search/library 发起 POST 请求

如果未显式提供，搜索调优的默认值如下：

属性默认值描述
page_size10每页将返回 10 个资产。
page1查询将返回响应的第一页。
sortrelevance“相关性”尝试基于一组经过特别调优的属性对资产进行排序。在没有查询的情况下，相关性会严重倾向于上传时间较近的资产。

关于本指南

本指南将逐步介绍如何构建一个匹配以下条件的搜索查询：

  • 帐户内的资产
  • 匹配查询 "moon"
  • 在特定项目中
  • 上传时间介于 2020 年 4 月 1 日至 4 月 30 日之间
  • 且状态为“已批准”

我们最终的搜索请求体将如下所示：

1{
2    "account_id": "<account_id>",
3    "q": "moon",
4    "sort": "name",
5    "filter": {
6        "inserted_at": [
7            {
8                "op": "gte",
9                "value": "2020-04-01T04:00:00.000Z"
10            },
11            {
12                "op": "lte",
13                "value": "2020-04-30T03:59:59.999Z"
14            }
15        ],
16        "project_id": {
17            "op": "eq",
18            "value": "<project_id>"
19        },
20        "label": {
21            "op": "eq",
22            "value": "approved"
23        }
24    },
25    "page_size": 10,
26    "page": 1
27}

帐户、查询和排序

帐户 (account_id)、查询 (q) 和排序 sort 是搜索查询中三个最基本的构建块，它们位于任何 filter 属性之外。

帐户上下文

从技术上讲，执行搜索所需的唯一属性是 account_id。这样做会简单提取帐户上的每个资产（包括文件夹），并使用默认分页值（每页 10 个资产，从第 1 页开始）。

1{
2    "account_id": "<account_id>"
3}

搜索查询

下一个最常见（也最有帮助）要包含的属性就是查询本身。注意：由于 Frame.io 的 API 搜索接受空查询，因此无需使用通配符 (*) 查询。您要么是在搜索某些内容，要么是在请求对帐户中的所有资产进行（可能经过筛选的）排序。

在我们的示例中，我们将搜索“moon”这个词。

1{
2    "account_id": "<account_id>",
3    "q": "moon"
4}

排序

sort.png

Frame.io 支持多种不同的排序选项。排序顺序的语法在各个选项之间都是类似的：

  • 每个选项都有一个默认的排序方向
  • 要反转该方向，请在排序值前加上负号 -

例如，要按字母逆序（Z 到 A）排序，您可以声明 &quot;sort&quot;: &quot;-name&quot;。默认的排序操作是“相关性”。因此，它不需要声明；如果未提供 sort 属性，系统将默认使用相关性排序。

排序选项属性默认方向
相关性不适用不适用
上传日期inserted_at最旧在前
名称nameA 至 Z
大小filesize最小在前
上传者creator.nameA 至 Z
因此，在我们构建查询时，现在可以在 sort 中添加按 name（A 到 Z）排序：
1{
2    "account_id": "<account_id>",
3    "q": "moon",
4    "sort": "name"
5}

筛选条件和分页

筛选条件既是 Frame.io 资产搜索中最复杂的部分，但也是最强大的功能。筛选条件被编写在一个单独的 filter 对象内，并且都遵循相同的模式：一个操作 (op) 和一个值 (value)。筛选条件将使用以下常见缩写，除“等于”之外的等效选项仅用于日期和大小查询：

  • eq — 等于
  • lt — 小于
  • gt — 大于
  • lte — 小于或等于
  • gte — 大于或等于
  • match — 精确匹配，仅用于“上传者”和“文件类型”筛选条件

例如，用于匹配已知 project_id 的 filter 将按如下方式构建：

1{
2    "filter": {
3        "project_id": {
4            "op": "eq",
5            "value": "<project_id>"
6        }
7    }
8}

选项和操作

下表描述了与每种筛选条件类型相关的选项和操作。

筛选选项属性支持的操作支持的值
已存档archivedeqtrue、false
上传日期inserted_ateq、lt、gt、lte、gte<datetime></datetime> (ISO-8601, UTC)
已删除deletedeqtrue、false
文件类型filetypematch<mime type=""></mime>
私有privateeqtrue、false
项目project_ideq<project_id></project_id>
大小filesizeeq、lt、gt、lte、gtesize（以字节为单位）
状态labeleqnone、in_progress、needs_review、approved
团队team_ideq<team_id></team_id>
类型asset_typeeqaudio、document、folder、image、other、stream、video
上传者creator.namematch<name></name>
上传者必须是活跃的帐户成员才能填充索引

搜索那些已不再是帐户成员的创作者将无法生效，因为该用户已不在用户搜索索引中。

为了继续构建我们的查询，我们现在可以添加一个筛选条件，用于筛选满足以下条件的资产：

  • 在特定项目中
  • 上传时间介于 2020 年 4 月 1 日至 4 月 30 日之间
  • 标记为“已批准”
1{
2    "account_id": "<account_id>",
3    "q": "moon",
4    "sort": "name",
5    "filter": {
6        "inserted_at": [
7            {
8                "op": "gte",
9                "value": "2020-04-01T04:00:00.000Z"
10            },
11            {
12                "op": "lte",
13                "value": "2020-04-28T03:59:59.999Z"
14            }
15        ],
16        "project_id": {
17            "op": "eq",
18            "value": "<project_id>"
19        },
20        "label": {
21            "op": "eq",
22            "value": "approved"
23        }
24    }
25}
分页

搜索端点的分页方式与任何其他端点完全相同，通过位于请求体最外层的 page_size 和 page 属性来实现。有关分页的更多详细信息，请参阅此处的单独指南。