搜索表格

API Reference 搜索端点的 OpenAPI 规范。

注意

本文档由 AI 翻译。如有错误，请参考英文版本或提交反馈。

搜索端点查找与提供的查询匹配的表格行，并按相关性对它们进行排序。

搜索的许多 API 表面与表格端点共享。本页重点关注搜索特定的行为，有关更多详细信息，请参阅表格端点文档或搜索 API 参考。

查询

query 参数是搜索的核心 API，控制结果相关性和过滤。查询使用强大的查询语言编写，如下所述。

查询针对 sheets 参数指定的表格执行。

子句

子句是查询的基本构建块，执行字段与预期值的比较。它们采用 [specifier][operation][value] 的基本形式，即 Name="Rainbow Drip"。

query=Name=“Rainbow Drip”

// /api/search?sheets=Action&fields=Name&query=Name="Rainbow Drip"
{
  "results": [
    {
      "row_id": 34688,
      "fields": { "Name": "Rainbow Drip" }
    }
  ]
}

指定符

类似于[字段过滤器]，可以通过指定字段的完整路径来搜索嵌套在结构字段中的字段。点表示法用于结构体和关系，数组访问表示法用于数组。

query=ClassJob.Abbreviation=“PCT”

// /api/search?sheets=Action&fields=Name&query=ClassJob.Abbreviation="PCT"
{
  "results": [
    {
      "row_id": 34650,
      "fields": { "Name": "Fire in Red" }
    },
    {
      "row_id": 34653,
      "fields": { "Name": "Blizzard in Cyan" }
    },
    // ...
  ]
}

query=BaseParam[].Name=“Spell Speed”

// /api/search?sheets=Item&fields=Name,BaseParam[].Name&query=BaseParam[].Name="Spell Speed"
{
  "results": [
    {
      "row_id": 1973,
      "fields": {
        "Name": "Ul'dahn Wand",
        "BaseParam": [
          { "fields": { "Name": "Mind" } },
          { "fields": { "Name": "Vitality" } },
          { "fields": { "Name": "Spell Speed" } },
          { "fields": { "Name": "" } },
          { "fields": { "Name": "" } },
          { "fields": { "Name": "" } }
        ]
      }
    },
    {
      "row_id": 1989,
      "fields": {
        "BaseParam": [
          { "fields": { "Name": "Mind" } },
          { "fields": { "Name": "Vitality" } },
          { "fields": { "Name": "Spell Speed" } },
          { "fields": { "Name": "" } },
          { "fields": { "Name": "" } },
          { "fields": { "Name": "" } }
        ],
        "Name": "Serpent Officer's Wand"
      },
      // ...
    },
  ]
}

要在请求范围的 language 参数以外的语言中搜索值，可以用语言装饰字段。

query=Name@ja=“天使の筆”

// /api/search?sheets=Item&fields=Name&query=Name@ja="天使の筆"
{
  "results": [
    {
      "row_id": 42589,
      "fields": {
        "Name": "Angel Brush"
      }
    }
  ]
}

操作和值

上面的示例一直在使用精确相等搜索字段。为了进一步定制查询，可以使用多个操作来执行具有类型感知语义的比较。

Type	Example
String	"value"
Number	1, -1, 1.0
Boolean	true, false

Operation	Type	Comparison
=	any	Exact equality
>=, >, <=, <	number	Numeric comparison
~	string	Partial string comparison

query=Name~“rainbow”

// /api/search?sheets=Action&fields=Name&query=Name~"rainbow"
{
  "results": [
    {
      "row_id": 34688,
      "fields": { "Name": "Rainbow Drip" }
    },
    {
      "row_id": 21474,
      "fields": { "Name": "Lunar Rainbow" }
    },
    {
      "row_id": 29388,
      "fields": { "Name": "Rainbow Gulal" }
    },
    {
      "row_id": 6288,
      "fields": {"Name": "Rainbow Dynamo" }
    }
  ]
}

query=Recast100ms>3000

// /api/search?sheets=Action&fields=Name,Recast100ms&query=Recast100ms>3000
{
  "results": [
    {
      "row_id": 6,
      "fields": {
        "Name": "Return",
        "Recast100ms": 9000
      }
    },
    {
      "row_id": 30,
      "fields": {
        "Name": "Hallowed Ground",
        "Recast100ms": 4200
      }
    },
    // ...
  ]
}

多子句和相关性

一个查询可以通过用空格分隔来指定多个子句。所有结果将至少匹配提供的子句之一。

结果的排序由它们与查询的相关性定义——匹配更多子句的结果将排在匹配较少的结果之前。用于此排序的值在结果中作为 score 返回。

query=ClassJobLevel=92 Name=“Rainbow Drip”

在此示例中，返回了 ClassJobLevel 92 可用的所有技能。由于 rainbow drip 也匹配 Name 子句，它优先于其他结果。

// /api/search?sheets=Action&fields=ClassJobLevel,Name&query=ClassJobLevel=92 Name="Rainbow Drip"
{
  "results": [
    {
      "score": 2,
      "row_id": 34688,
      "fields": {
        "ClassJobLevel": 92,
        "Name": "Rainbow Drip"
      }
    },
    {
      "score": 1,
      "row_id": 34644,
      "fields": {
        "ClassJobLevel": 92,
        "Name": "Uncoiled Twinfang"
      }
    },
    // ...
  ]
}

注意

计算分数的方式不被视为 API 表面的一部分。可能会执行分数计算的更改以改善结果相关性。任何此类调整都可能导致分数值和响应排序顺序的更改。

过滤结果

默认情况下，所有查询子句应该匹配，这导致上面概述的相关性排序。可以使用前缀调整此行为：

+clause

子句必须匹配。只有匹配的结果才会包含在响应中。

-clause

子句不得匹配。任何匹配的结果都将被丢弃。

query=+ClassJobCategory.PCT=true +ClassJobLevel=92

此示例搜索必须可由画师使用且必须在 92 级可用的技能。Rainbow Drip 是唯一符合此条件的技能。

// /api/search?sheets=Action&fields=Name&query=+ClassJobCategory.PCT=true +ClassJobLevel=92
{
  "results": [
    {
      "row_id": 34688,
      "fields": { "Name": "Rainbow Drip" }
    }
  ]
}

query=ClassJobCategory.WAR=true -ClassJobLevel<96

此示例搜索应该可由战士使用且不得在 96 级之前可用的技能。

// /api/search?sheets=Action&fields=Name,ClassJobLevel&query=ClassJobCategory.WAR=true -ClassJobLevel<96
{
  "results": [
    {
      "row_id": 36924,
      "fields": {
        "ClassJobLevel": 96,
        "Name": "Primal Wrath"
      }
    },
    {
      "row_id": 36925,
      "fields": {
        "ClassJobLevel": 100,
        "Name": "Primal Ruination"
      }
    }
  ]
}

为了执行更复杂的查询，可以用括号对子句进行分组。在查询中，组的行为类似于单个子句，操作由内部的子查询定义。

例如，简化的查询 +a +(b c) 将返回同时匹配 a 和至少一个 b 或 c 的所有结果。

query=+ClassJobCategory.PCT=true +(ClassJobLevel=80 ClassJobLevel=90)

此示例搜索可由画师使用且_也_在 80 级或 90 级可用的技能。

// /api/search?sheets=Action&fields=Name,ClassJobLevel&query=+ClassJobCategory.PCT=true +(ClassJobLevel=80 ClassJobLevel=90)
{
  "results": [
    {
      "score": 2,
      "row_id": 34662,
      "fields": {
        "ClassJobLevel": 80,
        "Name": "Holy in White"
      }
    },
    {
      "score": 2,
      "row_id": 34663,
      "fields": {
        "ClassJobLevel": 90,
        "Name": "Comet in Black"
      }
    }
  ]
}

查询 URI 编码

在执行 API 请求时，确保查询已编码为 URI 安全字符串非常重要，因为诸如 + 之类的字符如果以纯文本形式保留，会有替代行为。

大多数环境都提供了执行此编码的实用程序，例如 JavaScript 中的 encodeURIComponent。

查询多个表格

除了如上所示查询单个表格外，还可以同时跨多个表格执行查询。这样做时，来自所有查询表格的结果将合并并按相关性排序。

sheets=Action,Item&query=Name~“rainbow”

此示例搜索名称中包含”rainbow”的技能_和_物品。

// /api/search?sheets=Action,Item&fields=Name&query=Name~"rainbow"
{
  "results": [
    {
      "sheet": "Item",
      "row_id": 28928,
      "fields": {
        "Name": "Fae Rainbow"
      }
    },
    {
      "sheet": "Action",
      "row_id": 34688,
      "fields": {
        "Name": "Rainbow Drip"
      }
    },
    // ...
  ]
}

在多个表格上执行搜索时，查询只能访问可用字段的_交集_。如果查询的字段仅存在于指定表格的子集上，查询解析将失败，并返回错误。

分页

搜索端点接受 limit 参数，其行为与表格端点接受的同名参数等效。

如果响应包含完整结果集的子集，则在 next 属性中提供游标值。可以通过在新请求中将此值传递给 cursor 参数来获得更多结果。使用游标查询时，sheets 和 query 参数将被忽略，因为游标已经在先前请求的数据集上操作。

query=Name~“rainbow”&limit=2

这是来自[操作和值]的示例查询，返回总共 4 个结果，但结果限制已设置为 2 个结果。第一个响应在 next 中包含游标，第二个请求使用此游标获取剩余的 2 个结果。第二个响应上不存在 next，表示没有更多结果。

// /api/search?fields=Name&sheets=Action&query=Name~"rainbow"&limit=2
{
  "next": "4bce9ed3-74d7-4d4c-940f-4a918d204a58",
  "results": [
    {
      "row_id": 34688,
      "fields": { "Name": "Rainbow Drip" }
    },
    {
      "row_id": 21474,
      "fields": { "Name": "Lunar Rainbow" }
    }
  ]
}
// /api/search?fields=Name&cursor=4bce9ed3-74d7-4d4c-940f-4a918d204a58&limit=2
{
  "results": [
    {
      "row_id": 29388,
      "fields": { "Name": "Rainbow Gulal" }
    },
    {
      "row_id": 6288,
      "fields": { "Name": "Rainbow Dynamo" }
    }
  ]
}