搜索服务 API

显示全部

搜索

提供跨 OpenStack 资源的索引和搜索功能。

常规信息

OpenStack Searchlight 项目提供了一个搜索 API，该 API 呈现了一个用于查询 OpenStack 云中可用各种资源的接口。Searchlight 创建一个索引（使用开源 Elasticsearch 技术）并使其保持更新。此外，Searchlight 的搜索 API 需要身份验证并尊重每个 OpenStack 服务定义的基于角色的访问控制 (RBAC)。这使得最终用户可以访问 Elasticsearch 提供的强大搜索功能，但操作员可以放心，最终用户无法访问他们无法在每个 OpenStack 服务公开的 API 中找到的信息。

搜索 API 允许您使用 Elasticsearch 查询领域特定语言 构建详细的查询。如果您是 Elasticsearch 专家（或想成为一名专家），那很好，但这可能超出了大多数最终用户有效使用搜索 API 所需的范围。因此，我们将在下面提供各种有用的查询示例（参见 创建通用搜索）。

为了有效使用搜索 API，您需要了解一些关于 OpenStack 资源类型、Searchlight 如何存储关于 OpenStack 资源的数据以及 Searchlight 插件的信息。

OpenStack 资源类型

OpenStack 云为用户提供许多资源，例如服务器、镜像、网络。为了消除歧义（例如，您使用 Nova 创建的资源有时称为“服务器”，有时称为“实例”），已经开发出一种基于 OpenStack Heat 项目使用的标准词汇。

Heat 识别特定的资源类型，这些类型被赋予形式为

OS::{project_name}::{resource}

其中 {project_name} 和 {resource} 将被实际的项目名称和资源名称替换。例如，Nova 服务器（或“实例”）具有资源类型标识符 OS::Nova::Server。

Heat 项目在 OpenStack 资源类型 处维护着 OpenStack 资源类型标识符的列表。

总而言之，您需要知道您感兴趣的每个 OpenStack 资源类型的标识符，以便可以有效地搜索这些资源。

Searchlight 数据

Searchlight 创建一个文档来表示 OpenStack 云中的每个单独项目（服务器、镜像、网络）。这些文档存储在 Elasticsearch 索引中。当您使用搜索 API 提出查询时，将返回适合您的查询（以及您的 RBAC 角色）的文档。

为了便于搜索，每个文档都有一个文档类型。Searchlight 使用 OpenStack 资源类型（如前一节所述）作为文档类型。例如，存储在 Glance 中的虚拟机镜像将由一个文档表示，该文档具有文档类型 OS::Glance::Image。

与单个 OpenStack 资源对应的特定文档需要一个唯一的标识符。碰巧的是，每个 OpenStack 服务已经为它控制的每个单独资源分配了一个唯一的标识符，因此 Searchlight 分配的文档 ID 就是它。例如，如果您在 Glance 中有一个 ID 为 997ec7e8-a46b-4ab7-a1d4-788e06f52abe 的镜像，那么该镜像将在索引中由一个文档表示，该文档具有文档 ID 997ec7e8-a46b-4ab7-a1d4-788e06f52abe。

文档中的信息与您查询处理该特定资源类型的本机 API 时将获得相同的内容。例如，具有文档类型 OS::Glance::Image 的文档将包含与您查询 Images API 获取有关该镜像的信息相同的信息。当然，使用 Searchlight 的优势在于，您可以访问 Elasticsearch 提供的先进搜索功能。

Searchlight 索引

在上一节中，您了解到存储在 Elasticsearch 中的每个文档都由 (a) 它所在的索引、(b) 它的文档类型和 (c) 它的文档 ID 唯一标识。您已经知道如何确定文档类型（它是您感兴趣的 OpenStack 资源的资源类型）和文档 ID（它与管理该资源的 OpenStack 服务分配给该资源的标识符相同）。所以剩下的就是弄清楚要使用哪个索引。

由于顶级专业人员的精心工程设计，这很简单。Searchlight 维护自己的索引，名为“searchlight”。此外，搜索 API 会自动使用此索引，因此您无需指定它。我们仅在此处提及它，因为您会在从搜索 API 收到的某些 Elasticsearch 响应中看到它的名称，因此了解它是什么是有用的。

最后一点。Searchlight 通过使用了解并索引特定 OpenStack 资源类型的插件来实现其魔力。因此，为了使资源类型可以通过搜索 API 访问，必须安装一个 Searchlight 插件来索引该类型的资源。并非所有 OpenStack 资源当前都有 Searchlight 插件与之关联，并且并非所有 OpenStack 部署者都可能已安装所有可用插件。您可以使用 列出插件 调用来确定特定云中可用的插件。

GET

/v1/search/plugins

列出插件

详情

列出受支持的插件。

为了索引 OpenStack 资源，Searchlight 需要一个特定于每种资源类型的插件。因此，在特定 OpenStack 云中可以索引的资源仅限于 (a) 存在插件，以及 (b) 该插件已由云操作员启用。您可以使用此调用来确定可以在特定云中期望搜索哪些文档类型。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

没有请求参数，并且此调用不接受请求体。

响应

名称	入参	类型	描述
插件	body	数组	插件列表。列表中的每个元素包含以下字段 alias-indexing - 此插件用于引用在其中创建文档的 Elasticsearch 索引的别名 alias-searching - 此插件用于引用用于查询由此插件创建的文档的 Elasticsearch 索引的别名 type - 与此插件关联的文档类型

响应示例

{
    "plugins": [
        {
             "type": "OS::Glance::Image",
             "alias-indexing": "searchlight-listener",
             "alias-searching": "searchlight-search"
        },
        {
             "type": "OS::Glance::Metadef",
             "alias-indexing": "searchlight-listener",
             "alias-searching": "searchlight-search"
        }
    ]
}

GET

/v1/search/facets

列出方面

详情

列出受支持的方面。

对于每个已注册的资源类型，Searchlight 可以提供有关这些字段存在的字段名称和值的列表。

• 返回哪些字段以及是否列出值由每个插件确定。

• 某些字段或值可能仅对管理员用户列出。

• 对于某些字符串字段，结果中可能包含 facet_field。如果存在，则可用于对方面选项进行精确术语匹配。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
exclude_options (可选)	查询	布尔值	禁用聚合方面字段。提供性能改进。默认值为 false。
include_fields (可选)	查询	布尔值	禁用显示方面字段。仅显示计数。默认值为 true。
type (可选)	查询	字符串	您希望列出方面资源的资源类型。

此调用不接受请求体。

响应

名称	入参	类型	描述
方面	body	对象	一个 JSON 对象，将资源类型名称与支持该资源类型的方面列表配对。列表中的每个方面对象包含以下字段 name - 方面的名称 type - 方面的数据类型 facet_field - (可选，可能适用于某些字符串字段) 可用于进行精确术语匹配

响应示例

{
    "OS::Glance::Image": {
        "doc_count": 50,
        "facets": [
            {
                "name": "status",
                "type": "string",
                "options": [
                    {
                        "key": "queued",
                        "doc_count": 47
                    },
                    {
                        "key": "active",
                        "doc_count": 3
                    }
                ]
            },
            {
                "name": "created_at",
                "type": "date"
            },
            {
                "name": "virtual_size",
                "type": "long"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            { "...": "..." }
        ]
    },
    "OS::Glance::Metadef": {
        "doc_count": 25,
        "facets": [
            {
                "name": "objects.description",
                "nested": true,
                "type": "string"
            },
            {
                "name": "objects.properties.description",
                "nested": true,
                "type": "string"
            },
            { "...": "..." }
        ]
    },
    "OS::Nova::Server": {
        "doc_count": 100,
        "facets": [
            {
                "name": "status",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "ACTIVE"
                    }
                ],
                "type": "string"
            },
            {
                "name": "OS-EXT-SRV-ATTR:host",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            {
                "name": "image.id",
                "type": "string"
            },
            {
                "name": "OS-EXT-AZ:availability_zone",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "nova"
                    }
                ],
                "type": "string"
            },
            { "...": "..." }
        ]
    }
}

响应示例（包括 exclude_options 查询参数)

假设此请求：GET /v1/search/facets?exclude_options=true

{
    "OS::Glance::Image": {
        "doc_count": 50,
        "facets": [
            {
                "name": "status",
                "type": "string"
            },
            {
                "name": "created_at",
                "type": "date"
            },
            {
                "name": "virtual_size",
                "type": "long"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            { "...": "..." }
        ]
    },
    "OS::Glance::Metadef": {
        "doc_count": 25,
        "facets": [
            {
                "name": "objects.description",
                "type": "string"
            },
            {
                "name": "objects.properties.description",
                "type": "string"
            },
            { "...": "..." }
        ]
    },
    "OS::Nova::Server": {
        "doc_count": 100,
        "facets": [
            {
                "name": "status",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "ACTIVE"
                    }
                ],
                "type": "string"
            },
            {
                "name": "OS-EXT-SRV-ATTR:host",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
            {
                "name": "image.id",
                "type": "string"
            },
            {
                "name": "OS-EXT-AZ:availability_zone",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "nova"
                    }
                ],
                "type": "string"
            },
            { "...": "..." }
        ]
    }
}

响应示例（包括 type 查询参数)

假设此请求：GET /v1/search/facets?type=OS::Nova::Server

{
    "OS::Nova::Server": {
        "doc_count": 100,
        "facets": [
            {
                "name": "status",
                "options": [
                    {
                        "doc_count": 1,
                        "key": "ACTIVE"
                    }
                ],
                "type": "string"
            },
            {
                "name": "OS-EXT-SRV-ATTR:host",
                "type": "string"
            },
            {
                "name": "name",
                "type": "string",
                "facet_field": "name.raw"
            },
           { "...": "..." }
        ]
    }
}

响应示例（包括 include_fields 查询参数)

假设此请求：GET /v1/search/facets?include_fields=false

{
    "OS::Nova::Server": {
        "doc_count": 7
    },
    "OS::Neutron::Net": {
        "doc_count": 19
    },
    "OS::Glance::Image": {
        "doc_count": 68
    }
}

POST

/v1/search

创建通用搜索

详情

提交搜索请求。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
查询	body	对象	一个 JSON 对象，包含用 Elasticsearch 查询领域特定语言 表示的请求查询。

请求示例

{
    "query": {
        "match_all": {}
    }
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "OS::Software::DBMS",
                "_index": "searchlight",
                "_type": "OS::Glance::Metadef",
                "_score": 1.0,
                "_source": {
                    "description": "A database is an ...",
                    "display_name": "Database Software",
                    "namespace": "OS::Software::DBMS",
                    "objects": [
                        {
                            "description": "PostgreSQL, often simply 'Postgres' ...",
                            "name": "PostgreSQL",
                            "properties": [
                                {
                                    "default": "5432",
                                    "description": "Specifies the TCP/IP port...",
                                    "property": "sw_database_postgresql_listen_port",
                                    "...": "..."
                                },
                                { "...": "..." }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Database"
                        }
                    ]
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

创建类型限制搜索

详情

请求类型限制搜索。

通过在请求中包含 type 字段，您可以将结果限制为特定的资源类型或类型。

type 字段可以采用字符串值（特定资源类型的名称）或值数组（其中每个值都是资源类型的名称）。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
查询	body	对象	一个 JSON 对象，包含用 Elasticsearch 查询领域特定语言 表示的请求查询。
type	body	字符串或字符串数组	要限制搜索的资源类型的名称或类型。

请求示例（单个资源类型)

此示例说明了请求单个资源类型，Glance 镜像。

{
    "query": {
        "match_all": {}
    },
    "type": "OS::Glance::Image"
}

请求示例（多个资源类型)

此示例说明了请求多个资源类型，Glance 镜像和 Glance 元定义。

{
    "query": {
        "match_all": {}
    },
    "type": ["OS::Glance::Image", "OS::Glance::Metadef"]
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例（单个资源类型)

此示例说明了对单个资源类型，Glance 镜像 (OS::Glance::Image) 的响应。

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "a701f610-b162-45ac-a5a0-69e08aba8687",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "a701f610-b162-45ac-a5a0-69e08aba8687",
                    "members": [],
                    "name": "Docker container image",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

响应示例（多个资源类型)

这个例子说明了对多种资源类型（Glance 镜像 (OS::Glance::Image) 和 Glance 元定义 (OS::Glance::Metadef)）的请求的响应。

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "OS::Software::DBMS",
                "_index": "searchlight",
                "_type": "OS::Glance::Metadef",
                "_score": 1.0,
                "_source": {
                    "description": "A database is an ...",
                    "display_name": "Database Software",
                    "namespace": "OS::Software::DBMS",
                    "objects": [
                        {
                            "description": "PostgreSQL, often simply 'Postgres' ...",
                            "name": "PostgreSQL",
                            "properties": [
                                {
                                    "default": "5432",
                                    "description": "Specifies the TCP/IP port...",
                                    "property": "sw_database_postgresql_listen_port",
                                    "...": "..."
                                },
                                { "...": "..." }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Database"
                        }
                    ]
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

创建管理搜索

详情

提交管理搜索请求。

默认情况下，用户在搜索响应中收到的结果仅限于公共资源以及用户项目（或“租户”）拥有（或与之共享）的资源。

管理员可以选择通过在搜索请求体中传递 all_projects 字段来查看索引中的所有资源。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
查询	body	对象	一个 JSON 对象，包含用 Elasticsearch 查询领域特定语言 表示的请求查询。
all_projects (可选)	body	布尔值	指示管理员希望在搜索中包含所有项目的资源。默认值为 false。

请求示例

{
    "query": {
        "match_all": {}
    },
    "all_projects": true
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "OS::Software::DBMS",
                "_index": "searchlight",
                "_type": "OS::Glance::Metadef",
                "_score": 1.0,
                "_source": {
                    "description": "A database is an ...",
                    "display_name": "Database Software",
                    "namespace": "OS::Software::DBMS",
                    "objects": [
                        {
                            "description": "PostgreSQL, often simply 'Postgres' ...",
                            "name": "PostgreSQL",
                            "properties": [
                                {
                                    "default": "5432",
                                    "description": "Specifies the TCP/IP port...",
                                    "property": "sw_database_postgresql_listen_port",
                                    "...": "..."
                                },
                                { "...": "..." }
                            ]
                        }
                    ],
                    "tags": [
                        {
                            "name": "Database"
                        }
                    ]
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

创建自由文本搜索

详情

提交自由文本搜索请求。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
type	body	字符串或字符串数组	要限制搜索的资源类型的名称或类型。
multi_match	body	字符串或字符串数组	一个 JSON 对象，包含一个 query 字段，其值为 Elasticsearch 查询字符串。

请求示例

假设您想找到所有在某些字段中包含单词“cirros”的镜像，无论是在名称、标签或其他镜像属性中。

{
    "type": "OS::Glance::Image",
    "query": {
        "multi_match": {
            "query":"cirros",
            "fields": ["_all"]
        }
    }
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例

{
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "hits": {
        "hits": [
            {
                "_id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "76580e9d-f83d-49d8-b428-1fb90c5d8e95",
                    "members": [],
                    "name": "cirros-0.3.2-x86_64-uec",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            {
                "_id": "15c2501d-07bd-4eb1-b15f-77ef739e5419",
                "_index": "searchlight",
                "_type": "OS::Glance::Image",
                "_score": 1.0,
                "_source": {
                    "id": "15c2501d-07bd-4eb1-b15f-77ef739e5419",
                    "description": "Extra special cirros image",
                    "members": [],
                    "name": "Simply Sensational",
                    "owner": "d95b27da6e9f4acc9a8031918e443e04",
                    "visibility": "public",
                    "...": "..."
                }
            },
            { "...": "..." }
        ],
        "max_score": 1.0,
        "total": 8
    },
    "timed_out": false,
    "took": 1
}

POST

/v1/search

创建短语搜索

详情

提交一个搜索请求，查找特定字段中的短语。

一个常见场景是，某些资源具有自定义元数据，以自然语言描述该资源。例如，您可能在镜像上设置了一个名为 description 的属性，其值为描述该镜像推荐用途的自然语言句子。您可以查询搜索 API 以查找与该字段中匹配该短语的响应。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

假设您使用如上所述的镜像上的 description 属性，并且您有兴趣找到任何被描述为“Preconfigured with a schmaltz to optimize the foobar.”的镜像。

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
查询	body	对象	一个 JSON 对象，包含用 Elasticsearch 查询领域特定语言 表示的请求查询。

请求示例

{
    "type": "OS::Glance::Image",
    "query": {
        "match_phrase": {
            "description": "Preconfigured with a schmaltz to optimize the foobar"
        }
    }
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例

{
  "hits": {
    "hits": [
      {
        "_score": 12.945373,
        "_type": "OS::Glance::Image",
        "_id": "7a99b58d-0b70-4138-8086-ab0cc4bd1ba3",
        "_source": {
          "container_format": "bare",
          "min_ram": 0,
          "updated_at": "2016-08-25T17:54:02Z",
          "cim_pasd_processorarchitecture": "Power",
          "owner": "158776c9face41a7a3026d6c1cae686a",
          "id": "7a99b58d-0b70-4138-8086-ab0cc4bd1ba3",
          "size": 5969,
          "image_type": "image",
          "disk_format": "raw",
          "project_id": "158776c9face41a7a3026d6c1cae686a",
          "status": "active",
          "description": "Preconfigured with a schmaltz to optimize the foobar",
          "tags": [],
          "hw_cpu_policy": "shared",
          "visibility": "public",
          "members": [],
          "min_disk": 0,
          "virtual_size": null,
          "name": "My Awesome Image",
          "checksum": null,
          "created_at": "2016-08-25T17:54:02Z",
          "protected": false
        },
        "_index": "searchlight-2016_08_25_18_48_30"
      }
    ],
    "total": 1,
    "max_score": 12.945373
  },
  "_shards": {
    "successful": 1,
    "failed": 0,
    "total": 1
  },
  "took": 4,
  "timed_out": false
}

POST

/v1/search

创建复合布尔搜索

详情

提交复合布尔搜索请求。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
查询	body	对象	一个 JSON 对象，包含用 Elasticsearch 查询领域特定语言 表示的请求查询。

请求示例

假设您想找到满足以下条件的所有镜像

• 镜像必须是公共的和活动的。（这是一个必须条件。）

• 镜像不能需要超过 4096 RAM。（这是一个带有范围查询的必须排除条件。）

• 镜像不能是 aki 或 ari。（这是一个必须排除条件）

• 名称或标签应包含“cirros”。（这是一个应该条件，最小匹配数为 1。）

• 在结果中，指示（“突出显示”）为什么这些结果包含在请求中。

{
    "type": "OS::Glance::Image",
    "query": {
        "bool" : {
            "must" : [
                { "term" : { "status" : "active" } },
                { "term" : { "visibility" : "public" } }
            ],
            "must_not" : [
                { "range" : { "min_ram" : { "gt" : 4096 } } },
                { "terms" : { "disk_format" : ["aki", "ari"] } }
            ],
            "should" : [
                { "match" : { "name" : "cirros" } },
                { "match" : { "tag" : "cirros" } }
            ],
            "minimum_should_match" : 1
        }
    },
    "highlight": {
       "fields": {
          "*":{}
       }
   }
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例

{
  "hits": {
    "hits": [
      {
        "_type": "OS::Glance::Image",
        "_source": {
          "status": "active",
          "created_at": "2016-08-25T17:32:41Z",
          "project_id": "98c05407d80c405aa6efa01b279385ce",
          "name": "cirros-0.3.4-x86_64-uec",
          "tags": [],
          "image_type": "image",
          "checksum": "eb9139e4942121f22bbc2afc0400b2a4",
          "min_ram": 0,
          "ramdisk_id": "f310fb51-29dc-47bf-8cbd-3ea1170fb4e3",
          "disk_format": "ami",
          "updated_at": "2016-08-25T17:32:42Z",
          "visibility": "public",
          "kernel_id": "34ddf1d2-b588-4a9a-a3d3-344768c04bfd",
          "protected": false,
          "members": [],
          "container_format": "ami",
          "min_disk": 0,
          "owner": "98c05407d80c405aa6efa01b279385ce",
          "virtual_size": null,
          "id": "23fa3971-3ed8-435a-a3c6-8addea5153aa",
          "size": 25165824
        },
        "_score": 3.3642778,
        "_index": "searchlight-2016_08_25_18_48_30",
        "highlight": {
          "status": [
            "<em>active</em>"
          ],
          "name": [
            "<em>cirros</em>-0.3.4-x86_64-uec"
          ],
          "visibility": [
            "<em>public</em>"
          ]
        },
        "_id": "23fa3971-3ed8-435a-a3c6-8addea5153aa"
      },
      {
        "_type": "OS::Glance::Image",
        "_source": {
          "status": "active",
          "created_at": "2016-08-25T17:32:34Z",
          "project_id": "98c05407d80c405aa6efa01b279385ce",
          "name": "cirros-0.3.4-x86_64-disk",
          "tags": [],
          "image_type": "image",
          "checksum": "ee1eca47dc88f4879d8a229cc70a07c6",
          "min_ram": 0,
          "disk_format": "qcow2",
          "updated_at": "2016-08-25T17:32:35Z",
          "visibility": "public",
          "owner": "98c05407d80c405aa6efa01b279385ce",
          "protected": false,
          "members": [],
          "container_format": "bare",
          "min_disk": 0,
          "virtual_size": null,
          "id": "f34de38c-7a5c-4b00-8015-70a7a63480e8",
          "size": 13287936
        },
        "_score": 3.3642778,
        "_index": "searchlight-2016_08_25_18_48_30",
        "highlight": {
          "status": [
            "<em>active</em>"
          ],
          "name": [
            "<em>cirros</em>-0.3.4-x86_64-disk"
          ],
          "visibility": [
            "<em>public</em>"
          ]
        },
        "_id": "f34de38c-7a5c-4b00-8015-70a7a63480e8"
      }
    ],
    "total": 2,
    "max_score": 3.3642778
  },
  "_shards": {
    "successful": 1,
    "failed": 0,
    "total": 1
  },
  "took": 1,
  "timed_out": false
}

POST

/v1/search

创建聚合搜索

详情

提交聚合搜索请求。

成功

代码	原因
200 - 正常	响应包含与请求的资源对应的实体。

错误

代码	原因
400 - 请求错误	服务器无法（或不愿）处理请求，因为存在客户端错误。
401 - 未授权	您要么忘记提供凭据，要么提供的凭据格式不正确或已过期。
403 - 禁止	您没有足够的权限来执行请求的操作。
500 - 内部服务器错误	服务器遇到阻止其完成请求的意外情况。

请求

名称	入参	类型	描述
Content-type	标头	字符串	请求体的 MIME 类型。必须为 application/json。
查询	body	对象	一个 JSON 对象，包含用 Elasticsearch 查询领域特定语言 表示的请求查询。

请求示例

假设您想找到所有镜像中不同名称和 container_format 的数量。

{
    "query": {
        "match_all": {}
    },
    "type": ["OS::Glance::Image"],
    "limit": 0,
    "aggregations": {
        "name": {"terms": {"field": "name"}},
        "container_format": {"terms": {"field": "container_format"}}
    }
}

响应

名称	入参	类型	描述
_shards	body	对象	一个 JSON 对象，包含以下字段 failed - 搜索无法执行的分片数 successful - 搜索成功的分片数 total - 参与处理查询的总分片数
hits	body	对象	一个 JSON 对象，包含搜索结果。它包含以下字段 hits - 搜索结果的数组（默认为前 25 个文档）。数组中的每个元素包含以下字段 _id - 在其 OpenStack 上下文中唯一标识资源（例如，Glance 镜像使用其镜像 ID） _index - 资源所属的服务（例如，searchlight） _score - 给定命中的相关性。默认情况下，这是对结果进行排序的字段 _source - 最初索引的文档，包含与 OpenStack 资源相关的所有数据。此字段是一个映射，其中每个键都是一个字段，其值可以是标量值、列表、嵌套对象或嵌套对象列表。 _type - 文档的 OpenStack 资源类型（例如，“OS::Neutron::Net”、“OS::Glance::Image”） _parent - (可选) 当资源类型与另一个资源类型具有子关系时，特定父资源的 ID 将出现在此处。 _routing - (可选) 当显式指定 Elasticsearch 路由时包含。 max_score - 任何与查询匹配的文档的最高 _score total - 匹配搜索标准的文档总数
aggregations	body	对象	一个 JSON 对象，包含聚合结果。它包含以下字段 buckets - 聚合结果的数组（默认为前十个术语）。每个术语都有一个 bucket。数组的每个元素包含以下字段 doc_count - 该术语出现的次数。 key - 该术语的值。 doc_count_error_upper_bound - 编译文档计数时误差的上限，因为计数是近似值。 sum_other_doc_count - 由于 bucket 数组中的元素数量可能有限制（默认值为十），因此不包含在 bucket 中的所有其他文档计数之和。
timed_out	body	布尔值	指示搜索是否超时。
took	body	数字	Elasticsearch 执行搜索所用的时间（以毫秒为单位）。

响应示例

{
    "_shards": {
        "successful": 1,
        "failed": 0,
        "total": 1
    },
    "aggregations": {
        "container_format": {
            "buckets": [
                {
                    "doc_count": 101,
                    "key": "bare"
                },
                {
                    "doc_count": 1,
                    "key": "aki"
                },
                {
                    "doc_count": 1,
                    "key": "ami"
                },
                {
                    "doc_count": 1,
                    "key": "ari"
                }
            ],
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0
        },
        "name": {
            "buckets": [
                {
                    "doc_count": 100,
                    "key": "image"
                },
                {
                    "doc_count": 3,
                    "key": "0.3.4"
                },
                {
                    "doc_count": 3,
                    "key": "cirros"
                },
                {
                    "doc_count": 3,
                    "key": "uec"
                },
                {
                    "doc_count": 3,
                    "key": "x86_64"
                }
            ],
            "doc_count_error_upper_bound": 0,
            "sum_other_doc_count": 0
        }
    },
    "hits": {
        "hits": [],
        "max_score": 0.0,
        "total": 104
    },
    "took": 5,
    "timed_out": false
}

说明

您在响应中看到的索引不是字面意义上的 ElasticSearch 索引。以下几点需要注意

• 由于架构原因（主要是为了允许零停机时间重新索引），Searchlight 不直接引用索引，而是使用索引别名。这对您作为 API 消费者产生的主要影响是，您将在某些 Search API 响应中看到对别名的引用，而不是直接对索引的引用。

• 所有对 ElasticSearch 的访问都通过别名进行，而不是直接通过索引。有关别名的更多详细信息，请参阅 列出插件 调用。别名背后的实际索引是临时的，因为每当 Searchlight 重新索引时，都会创建一个新的索引。

• 默认情况下，Searchlight 使用名为“searchlight”的单个索引。但是，操作员可以选择使用不同的名称。此外，操作员可以选择将不同类型的资源索引到不同的索引中，以便例如，“OS::Cinder::Volume”可以有一个 Elasticsearch 索引，“OS::Neutron::Net”可以有一个不同的 Elasticsearch 索引，而“OS::Neutron::SecurityGroup”可以有一个第三个单独的 Elasticsearch 索引。当这样做时，通过 Searchlight API 暴露的别名也会相应地更改。

参考

• 布尔查询

• 范围查询

• 高亮显示

• 复合查询

• 聚合查询