Link Search Menu Expand Document Documentation Menu
文档

与 OpenSearch 通信

您可以使用 REST API 或其中一个 OpenSearch 语言客户端与 OpenSearch 通信。本页介绍了 OpenSearch REST API。如果您需要在编程语言中与 OpenSearch 通信，请参阅客户端部分，获取可用客户端列表。

OpenSearch REST API

您可以使用 REST API 与 OpenSearch 集群交互，这提供了很大的灵活性。通过 REST API，您可以更改大多数 OpenSearch 设置、修改索引、检查集群健康状况、获取统计信息——几乎所有操作。您可以使用像 cURL 这样的客户端或任何可以发送 HTTP 请求的编程语言。

您可以在终端或 OpenSearch Dashboards 中的开发工具控制台中发送 HTTP 请求。

在终端中发送请求

在终端中发送 cURL 请求时，请求格式取决于您是否正在使用安全插件。例如，考虑一个对集群健康 API 的请求。

如果您没有使用安全插件，请发送以下请求

curl -X GET "https://:9200/_cluster/health"

如果您正在使用安全插件，请在请求中提供用户名和密码

curl -X GET "https://:9200/_cluster/health" -ku admin:<custom-admin-password>

默认用户名是 admin，密码在您的 docker-compose.yml 文件中的 OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> 设置中。

OpenSearch 默认通常以扁平 JSON 格式返回响应。为了获得更易读的响应体，请提供 pretty 查询参数

curl -X GET "https://:9200/_cluster/health?pretty"

有关 pretty 和其他有用查询参数的更多信息，请参阅通用 REST 参数。

对于包含请求体的请求，请指定 Content-Type 头部，并在 -d (数据) 选项中提供请求负载

curl -X GET "https://:9200/students/_search?pretty" -H 'Content-Type: application/json' -d'
{
  "query": {
    "match_all": {}
  }
}'

在开发工具中发送请求

OpenSearch Dashboards 中的开发工具控制台使用比 cURL 命令更简单的语法来格式化 REST 请求。要在开发工具中发送请求，请使用以下步骤

  1. 在运行 OpenSearch 集群的同一主机上，通过在 Web 浏览器中打开 https://:5601/ 访问 OpenSearch Dashboards。默认用户名是 admin，密码在您的 docker-compose.yml 文件中的 OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> 设置中。
  2. 在顶部菜单栏上，转到 管理 > 开发工具。
  3. 在控制台的左侧窗格中，输入以下请求
     GET _cluster/health

  4. 选择请求右上角的三角形图标以提交查询。您也可以通过按 Ctrl+Enter（Mac 用户为 Cmd+Enter）提交请求。要了解更多关于使用 OpenSearch Dashboards 控制台提交查询的信息，请参阅在控制台中运行查询。

在以下章节以及大多数 OpenSearch 文档中，请求均以开发工具控制台格式呈现。

索引文档

要将 JSON 文档添加到 OpenSearch 索引（即，对文档进行索引），您需要发送带有以下头部信息的 HTTP 请求

PUT https://<host>:<port>/<index-name>/_doc/<document-id>

例如，要索引一个代表学生的文档，您可以发送以下请求

PUT /students/_doc/1
{
  "name": "John Doe",
  "gpa": 3.89,
  "grad_year": 2022
}

发送上述请求后，OpenSearch 会创建一个名为 students 的索引，并将摄入的文档存储在该索引中。如果您没有为文档提供 ID，OpenSearch 会生成一个文档 ID。在上述请求中，文档 ID 被指定为学生 ID (1)。

要了解更多关于索引的信息，请参阅管理索引。

动态映射

当您索引文档时，OpenSearch 会从文档中提交的 JSON 类型推断字段类型。此过程称为动态映射。有关更多信息，请参阅动态映射。

要查看推断的字段类型，请向 _mapping 端点发送请求

GET /students/_mapping

OpenSearch 返回每个字段的 type 字段

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "long"
        },
        "name": {
          "type": "text",
          "fields": {
            "keyword": {
              "type": "keyword",
              "ignore_above": 256
            }
          }
        }
      }
    }
  }
}

OpenSearch 将数值字段映射到 float 和 long 类型。请注意，OpenSearch 将 name 文本字段映射到 text，并添加了一个映射到 keyword 的 name.keyword 子字段。映射到 text 的字段会被分析（小写并拆分为词条），可用于全文搜索。映射到 keyword 的字段用于精确词条搜索。

OpenSearch 将 grad_year 字段映射到 long。如果您想将其映射到 date 类型，则需要删除索引，然后重新创建，并明确指定映射。有关如何明确指定映射的说明，请参阅索引映射和设置。

搜索文档

要搜索文档，请指定要搜索的索引以及用于匹配文档的查询。最简单的查询是 match_all 查询，它匹配索引中的所有文档

GET /students/_search
{
  "query": {
    "match_all": {}
  }
}

OpenSearch 返回已索引的文档

{
  "took": 12,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 1,
    "hits": [
      {
        "_index": "students",
        "_id": "1",
        "_score": 1,
        "_source": {
          "name": "John Doe",
          "gpa": 3.89,
          "grad_year": 2022
        }
      }
    ]
  }
}

有关搜索的更多信息，请参阅搜索您的数据。

更新文档

在 OpenSearch 中，文档是不可变的。但是，您可以通过检索文档、更新其信息并重新索引来更新文档。您可以使用索引文档 API 更新整个文档，为文档中所有现有和新增字段提供值。例如，要更新 gpa 字段并向先前索引的文档添加 address 字段，请发送以下请求

PUT /students/_doc/1
{
  "name": "John Doe",
  "gpa": 3.91,
  "grad_year": 2022,
  "address": "123 Main St."
}

或者，您可以通过调用更新文档 API 来更新文档的部分内容

POST /students/_update/1/
{
  "doc": {
    "gpa": 3.91,
    "address": "123 Main St."
  }
}

有关部分文档更新的更多信息，请参阅更新文档 API。

删除文档

要删除文档，请发送删除请求并提供文档 ID

DELETE /students/_doc/1

删除索引

要删除索引，请发送以下请求

DELETE /students

索引映射和设置

OpenSearch 索引通过映射和设置进行配置

  • 映射是字段及其类型的一个集合。有关更多信息，请参阅映射和字段类型。
  • 设置包括索引名称、创建日期和分片数量等索引数据。有关更多信息，请参阅配置 OpenSearch。

您可以在一个请求中指定映射和设置。例如，以下请求指定了索引分片的数量，并将 name 字段映射到 text，将 grad_year 字段映射到 date

PUT /students
{
  "settings": {
    "index.number_of_shards": 1
  }, 
  "mappings": {
    "properties": {
      "name": {
        "type": "text"
      },
      "grad_year": {
        "type": "date"
      }
    }
  }
}

现在您可以索引与上一节中相同的文档

PUT /students/_doc/1
{
  "name": "John Doe",
  "gpa": 3.89,
  "grad_year": 2022
}

要查看索引字段的映射，请发送以下请求

GET /students/_mapping

OpenSearch 根据指定的类型映射了 name 和 grad_year 字段，并推断了 gpa 字段的类型

{
  "students": {
    "mappings": {
      "properties": {
        "gpa": {
          "type": "float"
        },
        "grad_year": {
          "type": "date"
        },
        "name": {
          "type": "text"
        }
      }
    }
  }
}

字段创建后，无法更改其类型。更改字段类型需要删除索引并使用新映射重新创建。

延伸阅读

后续步骤

剩余 350 字符

有问题？。

想要贡献？ 或 。