使用 Node.js 摄取数据

本指南将介绍如何开始使用

• 使用 Node.js 安全连接到您的 Elastic Cloud Hosted 或 Elastic Cloud Enterprise 部署
• 将数据从您的应用程序摄取到您的部署中
• 搜索和修改您的数据

如果您是一位刚接触 Elastic Stack 的 Node.js 应用程序程序员，此内容将帮助您更轻松地上手。

所需时间：45 分钟

这些步骤适用于您现有的应用程序。如果您还没有，请使用此处包含的示例创建一个。

npm init
		

npm install @elastic/elasticsearch
npm install config
		

mkdir config
vi config/default.json
		

此处的示例展示了 config 软件包的预期内容。您需要在以下部分中使用您的部署详情更新 config/default.json

{
  "elastic": {
    "cloudID": "DEPLOYMENT_NAME:CLOUD_ID_DETAILS",
    "username": "elastic",
    "password": "LONGPASSWORD"
  }
}
		

1. 通过前往 Kibana 主菜单并选择 Management（管理）> Integrations（集成），然后选择 View deployment details（查看部署详情）来找到您的 Cloud ID。

连接到 Elastic Cloud Hosted 或 Elastic Cloud Enterprise 时，请使用 Cloud ID 指定连接详情。您必须传递在 Kibana 或云控制台中找到的 Cloud ID。

为了连接、向其流式传输数据以及发出查询，您需要考虑身份验证。支持两种身份验证机制：API 密钥和基本身份验证。为了让您快速上手，我们将在此展示如何使用基本身份验证，但您也可以按照稍后的说明生成 API 密钥。API 密钥更安全，是生产环境的首选。

对于基本身份验证，请使用您在创建部署时复制的相同部署凭据（username 和 password 参数）以及 Cloud ID。（如果您未保存密码，可以重置密码。）

该示例应用程序会连接到 Elasticsearch、创建一个索引、插入一些记录、执行搜索并更新一条记录。

读取之前创建的配置，并连接到 Elasticsearch

const { Client } = require('@elastic/elasticsearch')
const config = require('config');
const elasticConfig = config.get('elastic');

const client = new Client({
  cloud: {
    id: elasticConfig.cloudID
  },
  auth: {
    username: elasticConfig.username,
    password: elasticConfig.password
  }
})
		

现在，通过返回一些关于部署的信息来确认您已连接到部署

client.info()
  .then(response => console.log(response))
  .catch(error => console.error(error))
		

连接到部署后，您就可以开始索引和搜索数据了。让我们创建一个新索引，插入一些来自我们最喜爱角色的引语，并刷新索引以便搜索。刷新操作会使自上次刷新以来在索引上执行的所有操作都可供搜索。

async function run() {
  await client.index({
    index: 'game-of-thrones',
    body: {
      character: 'Ned Stark',
    quote: 'Winter is coming.'
    }
  })

  await client.index({
    index: 'game-of-thrones',
    body: {
      character: 'Daenerys Targaryen',
    quote: 'I am the blood of the dragon.'
    }
  })

  await client.index({
    index: 'game-of-thrones',
    body: {
      character: 'Tyrion Lannister',
    quote: 'A mind needs books like a sword needs whetstone.'
    }
  })

  await client.indices.refresh({index: 'game-of-thrones'})
}

run().catch(console.log)
		

使用 client.index API 时，如果 game-of-thrones 索引尚不存在，请求会自动创建它，如果未明确指定文档 ID，也会为每个索引的文档自动创建 ID。

在创建新索引并摄取一些数据后，您现在可以进行搜索了。让我们查找哪些角色提到过 winter

async function read() {
  const { body } = await client.search({
    index: 'game-of-thrones',
    body: {
      query: {
        match: { quote: 'winter' }
      }
    }
  })
  console.log(body.hits.hits)
}

read().catch(console.log)
		

搜索请求会返回 quote 字段中包含 'winter' 的文档内容，包括自动生成的文档 ID。您可以使用文档 ID 对特定文档进行更新。让我们为我们的角色添加一个出生地

async function update() {
  await client.update({
    index: 'game-of-thrones',
    id: <ID>,
    body: {
      script: {
        source: "ctx._source.birthplace = 'Winterfell'"
      }
    }
  })
  const { body } = await client.get({
    index: 'game-of-thrones',
    id: <ID>
  })

  console.log(body)
}

update().catch(console.log)
		

这个更全面的 API 示例列表包括批量操作、检查文档是否存在、按查询更新、删除、滚动（scrolling）和 SQL 查询。要了解更多信息，请查看完整的 API 参考。

在入门阶段，对 Elasticsearch 的身份验证使用了 elastic 超级用户和密码，但 API 密钥更安全，是生产环境的最佳实践。

在接下来的示例中，将创建一个具有集群 monitor（监控）权限的 API 密钥，该权限提供用于确定集群状态的只读访问权限。一些额外的权限还允许对指定索引执行 create_index（创建索引）、write（写入）、read（读取）和 manage（管理）操作。添加索引的 manage 权限是为了启用索引刷新。

security.createApiKey 函数返回一个 id 和 api_key 值，然后可以将它们连接起来并进行 base64 编码

async function generateApiKeys (opts) {
  const { body } = await client.security.createApiKey({
    body: {
      name: 'nodejs_example',
      role_descriptors: {
        'nodejs_example_writer': {
          'cluster': ['monitor'],
          'index': [
            {
              'names': ['game-of-thrones'],
              'privileges': ['create_index', 'write', 'read', 'manage']
            }
          ]
        }
      }
    }
  })

  return Buffer.from(`${body.id}:${body.api_key}`).toString('base64')
}

generateApiKeys()
  .then(console.log)
  .catch(err => {
  console.error(err)
  process.exit(1)
})
		

base64 编码后的输出如下所示，已准备好添加到配置文件中

API_KEY_DETAILS
		

编辑您之前创建的 config/default.json 配置文件并添加此 API 密钥

{
  "elastic-cloud": {
    "cloudID": "DEPLOYMENT_NAME:CLOUD_ID_DETAILS",
    "username": "elastic",
    "password": "LONGPASSWORD",
    "apiKey": "API_KEY_DETAILS"
  }
}
		

现在可以使用 API 密钥代替用户名和密码。客户端连接变为

const elasticConfig = config.get('elastic-cloud');

const client = new Client({
  cloud: {
    id: elasticConfig.cloudID
  },
  auth: {
    apiKey: elasticConfig.apiKey
  }
})
		

查看 Create API key API（创建 API 密钥 API）以了解有关 API 密钥的更多信息，并查看 Security privileges（安全权限）以了解所需的权限。如果您不确定适合您的自定义应用程序的权限组合是什么，可以启用 Elasticsearch 上的 audit logging（审计日志记录）来找出正在使用哪些权限。要了解有关 Elastic Cloud Hosted 或 Elastic Cloud Enterprise 上日志记录工作原理的更多信息，请查看 Monitoring Elastic Cloud deployment logs and metrics（监控 Elastic Cloud 部署日志和指标）。

安全

连接到 Elastic Cloud Hosted 或 Elastic Cloud Enterprise 时，客户端默认会自动启用请求和响应压缩，因为它能显著提高吞吐量。此外，除非另有指定，否则客户端还会将 SSL 选项 secureProtocol 设置为 TLSv1_2_method。您仍然可以通过配置来覆盖此选项。

使用 Elastic Cloud Hosted 或 Elastic Cloud Enterprise 时，请勿启用嗅探（sniffing），因为节点位于负载均衡器后面。Elastic Cloud Hosted 和 Elastic Cloud Enterprise 会为您处理一切。如果您想了解更多信息，请参阅 Elasticsearch 嗅探最佳实践：内容、时间、原因、方式。

连接（仅限 Elastic Cloud Hosted）

如果连接到 Elastic Cloud Hosted 的应用程序在 Java 安全管理器下运行，您至少应该禁用正向主机名解析的缓存。要了解更多信息，请查看 Java API Client 文档。

架构

当运行示例代码时，系统自动创建了索引映射。字段类型是 Elasticsearch 根据摄取第一条记录时看到的内容选择的，并随着数据中出现新字段而更新。为了优化性能，提前指定字段和字段类型会更有效。在为生产用例设计架构时，请参考 Elastic Common Schema 文档和字段类型文档。

摄取 (Ingest)

对于更高级的场景，此 bulk ingestion（批量摄取）参考提供了 bulk API 的示例，该示例可以在单个调用中执行多个操作。此批量示例还明确指定了文档 ID。如果您有大量文档需要索引，使用批量操作来处理文档比单独提交请求要快得多。