JavaScript 客户端

OpenSearch JavaScript (JS) 客户端提供了一种更安全、更简单的方式与您的 OpenSearch 集群交互。您无需从浏览器使用 OpenSearch 并可能将数据暴露给公众，而是可以构建一个 OpenSearch 客户端来处理向集群发送请求。有关客户端的完整 API 文档和更多示例，请参阅JS 客户端 API 文档。

客户端包含一个 API 库，允许您对集群执行不同的操作并返回标准响应主体。这里的示例演示了一些基本操作，例如创建索引、添加文档和搜索数据。

您可以使用辅助方法来简化复杂 API 任务的使用。有关更多信息，请参阅辅助方法。有关更高级的索引操作，请参阅 GitHub 中的 opensearch-js 指南。

设置

要将客户端添加到您的项目，请从 npm 安装

npm install @opensearch-project/opensearch

要安装特定主版本的客户端，请运行以下命令

npm install @opensearch-project/opensearch@<version>

如果您更喜欢手动添加客户端或只想检查源代码，请参阅 GitHub 上的 opensearch-js。

然后引入客户端

const { Client } = require("@opensearch-project/opensearch");

连接到 OpenSearch

要连接到默认的 OpenSearch 主机，如果您使用安全插件，请使用地址 https://:9200 创建一个客户端对象

var host = "localhost";
var protocol = "https";
var port = 9200;
var auth = "admin:<custom-admin-password>"; // For testing only. Don't store credentials in code.
var ca_certs_path = "/full/path/to/root-ca.pem";

// Optional client certificates if you don't want to use HTTP basic authentication.
// var client_cert_path = '/full/path/to/client.pem'
// var client_key_path = '/full/path/to/client-key.pem'

// Create a client with SSL/TLS enabled.
var { Client } = require("@opensearch-project/opensearch");
var fs = require("fs");
var client = new Client({
  node: protocol + "://" + auth + "@" + host + ":" + port,
  ssl: {
    ca: fs.readFileSync(ca_certs_path),
    // You can turn off certificate verification (rejectUnauthorized: false) if you're using 
    // self-signed certificates with a hostname mismatch.
    // cert: fs.readFileSync(client_cert_path),
    // key: fs.readFileSync(client_key_path)
  },
});

如果您不使用安全插件，请使用地址 https://:9200 创建一个客户端对象

var host = "localhost";
var protocol = "http";
var port = 9200;

// Create a client
var { Client } = require("@opensearch-project/opensearch");
var client = new Client({
  node: protocol + "://" + host + ":" + port
});

使用 Amazon OpenSearch Service 进行身份验证：AWS Signature Version 4

使用以下代码通过 AWS V2 SDK 进行身份验证

const AWS = require('aws-sdk'); // V2 SDK.
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

const client = new Client({
  ...AwsSigv4Signer({
    region: 'us-west-2',
    service: 'es',
    // Must return a Promise that resolve to an AWS.Credentials object.
    // This function is used to acquire the credentials when the client start and
    // when the credentials are expired.
    // The Client will refresh the Credentials only when they are expired.
    // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.

    // Example with AWS SDK V2:
    getCredentials: () =>
      new Promise((resolve, reject) => {
        // Any other method to acquire a new Credentials object can be used.
        AWS.config.getCredentials((err, credentials) => {
          if (err) {
            reject(err);
          } else {
            resolve(credentials);
          }
        });
      }),
  }),
  node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
});

使用以下代码通过适用于 Amazon OpenSearch Serverless 的 AWS V2 SDK 进行身份验证

const AWS = require('aws-sdk'); // V2 SDK.
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

const client = new Client({
  ...AwsSigv4Signer({
    region: 'us-west-2',
    service: 'aoss',
    // Must return a Promise that resolve to an AWS.Credentials object.
    // This function is used to acquire the credentials when the client start and
    // when the credentials are expired.
    // The Client will refresh the Credentials only when they are expired.
    // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.

    // Example with AWS SDK V2:
    getCredentials: () =>
      new Promise((resolve, reject) => {
        // Any other method to acquire a new Credentials object can be used.
        AWS.config.getCredentials((err, credentials) => {
          if (err) {
            reject(err);
          } else {
            resolve(credentials);
          }
        });
      }),
  }),
  node: "https://xxx.region.aoss.amazonaws.com" // OpenSearch domain URL
});

使用以下代码通过 AWS V3 SDK 进行身份验证

const { defaultProvider } = require('@aws-sdk/credential-provider-node'); // V3 SDK.
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

const client = new Client({
  ...AwsSigv4Signer({
    region: 'us-east-1',
    service: 'es',  // 'aoss' for OpenSearch Serverless
    // Must return a Promise that resolve to an AWS.Credentials object.
    // This function is used to acquire the credentials when the client start and
    // when the credentials are expired.
    // The Client will refresh the Credentials only when they are expired.
    // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.

    // Example with AWS SDK V3:
    getCredentials: () => {
      // Any other method to acquire a new Credentials object can be used.
      const credentialsProvider = defaultProvider();
      return credentialsProvider();
    },
  }),
  node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
  // node: "https://xxx.region.aoss.amazonaws.com" for OpenSearch Serverless
});

使用以下代码通过适用于 Amazon OpenSearch Serverless 的 AWS V3 SDK 进行身份验证

const { defaultProvider } = require('@aws-sdk/credential-provider-node'); // V3 SDK.
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

const client = new Client({
  ...AwsSigv4Signer({
    region: 'us-east-1',
    service: 'aoss',
    // Must return a Promise that resolve to an AWS.Credentials object.
    // This function is used to acquire the credentials when the client start and
    // when the credentials are expired.
    // The Client will refresh the Credentials only when they are expired.
    // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.

    // Example with AWS SDK V3:
    getCredentials: () => {
      // Any other method to acquire a new Credentials object can be used.
      const credentialsProvider = defaultProvider();
      return credentialsProvider();
    },
  }),
  node: "https://xxx.region.aoss.amazonaws.com" // OpenSearch domain URL
});

从 AWS Lambda 函数内部进行身份验证

在 AWS Lambda 函数内部，在处理程序函数外部声明的对象会保留其初始化状态。有关更多信息，请参阅Lambda 执行环境。因此，您必须在处理程序函数外部初始化 OpenSearch 客户端，以确保在后续调用中重复使用原始连接。这可以提高效率，并省去了每次都创建新连接的需要。

在处理程序函数内部初始化客户端可能会导致遇到 ConnectionError: getaddrinfo EMFILE error 错误。当在后续调用中创建多个连接，超出系统的文件描述符限制时，会发生此错误。

以下示例 AWS Lambda 函数代码演示了 OpenSearch 客户端的正确初始化

const { defaultProvider } = require('@aws-sdk/credential-provider-node'); // V3 SDK.
const { Client } = require('@opensearch-project/opensearch');
const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');

const client = new Client({
  ...AwsSigv4Signer({
    region: 'us-east-1',
    service: 'es',  // 'aoss' for OpenSearch Serverless
    // Must return a Promise that resolve to an AWS.Credentials object.
    // This function is used to acquire the credentials when the client start and
    // when the credentials are expired.
    // The Client will refresh the Credentials only when they are expired.
    // With AWS SDK V2, Credentials.refreshPromise is used when available to refresh the credentials.

    // Example with AWS SDK V3:
    getCredentials: () => {
      // Any other method to acquire a new Credentials object can be used.
      const credentialsProvider = defaultProvider();
      return credentialsProvider();
    },
  }),
  node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
  // node: "https://xxx.region.aoss.amazonaws.com" for OpenSearch Serverless
});

export const handler = async (event, context) => {
  const indexName = "books";

  const settings = {
    settings: {
      index: {
        number_of_shards: 4,
        number_of_replicas: 3,
      },
    },
  };

  // Use the already initialized client
  const response = await client.indices.create({
    index: indexName,
    body: settings,
  });

};

创建索引

要创建 OpenSearch 索引，请使用 indices.create() 方法。您可以使用以下代码构造一个带有自定义设置的 JSON 对象

var index_name = "books";

var settings = {
  settings: {
    index: {
      number_of_shards: 4,
      number_of_replicas: 3,
    },
  },
};

var response = await client.indices.create({
  index: index_name,
  body: settings,
});

索引文档

您可以使用客户端的 index 方法将文档索引到 OpenSearch 中

var document = {
  title: "The Outsider",
  author: "Stephen King",
  year: "2018",
  genre: "Crime fiction",
};

var id = "1";

var response = await client.index({
  id: id,
  index: index_name,
  body: document,
  refresh: true,
});

搜索文档

搜索文档最简单的方法是构造查询字符串。以下代码使用 match 查询来搜索标题字段中的“The Outsider”

var query = {
  query: {
    match: {
      title: {
        query: "The Outsider",
      },
    },
  },
};

var response = await client.search({
  index: index_name,
  body: query,
});

更新文档

您可以使用客户端的 update 方法更新文档

var response = await client.update({
  index: index_name,
  id: id,
  body: {
    doc: {
      // Specify the fields and their updated values here
      field1: "new_value1",
      field2: "new_value2",
      // Add more fields as needed
    }
  }
});

例如，以下代码更新了 genre 字段并向由 id 指定的文档添加了 tv_adapted 字段

var response = await client.update({
    index: index_name,
    id: id,
    body: {
      doc: {
        genre: "Detective fiction",
        tv_adapted: true
      }
    },
    refresh: true
  });

删除文档

您可以使用客户端的 delete 方法删除文档

var response = await client.delete({
  index: index_name,
  id: id,
});

删除索引

您可以使用 indices.delete() 方法删除索引

var response = await client.indices.delete({
  index: index_name,
});

示例程序

以下示例程序创建一个客户端，添加一个带有非默认设置的索引，插入一个文档，搜索该文档，删除该文档，然后删除该索引

"use strict";

var host = "localhost";
var protocol = "https";
var port = 9200;
var auth = "admin:<custom-admin-password>"; // For testing only. Don't store credentials in code.
var ca_certs_path = "/full/path/to/root-ca.pem";

// Optional client certificates if you don't want to use HTTP basic authentication
// var client_cert_path = '/full/path/to/client.pem'
// var client_key_path = '/full/path/to/client-key.pem'

// Create a client with SSL/TLS enabled
var { Client } = require("@opensearch-project/opensearch");
var fs = require("fs");
var client = new Client({
  node: protocol + "://" + auth + "@" + host + ":" + port,
  ssl: {
    ca: fs.readFileSync(ca_certs_path),
    // You can turn off certificate verification (rejectUnauthorized: false) if you're using 
    // self-signed certificates with a hostname mismatch.
    // cert: fs.readFileSync(client_cert_path),
    // key: fs.readFileSync(client_key_path)
  },
});

async function search() {
  // Create an index with non-default settings
  var index_name = "books";
  
  var settings = {
    settings: {
      index: {
        number_of_shards: 4,
        number_of_replicas: 3,
      },
    },
  };

  var response = await client.indices.create({
    index: index_name,
    body: settings,
  });

  console.log("Creating index:");
  console.log(response.body);

  // Add a document to the index
  var document = {
    title: "The Outsider",
    author: "Stephen King",
    year: "2018",
    genre: "Crime fiction",
  };

  var id = "1";

  var response = await client.index({
    id: id,
    index: index_name,
    body: document,
    refresh: true,
  });

  console.log("Adding document:");
  console.log(response.body);

  // Search for the document
  var query = {
    query: {
      match: {
        title: {
          query: "The Outsider",
        },
      },
    },
  };

  var response = await client.search({
    index: index_name,
    body: query,
  });

  console.log("Search results:");
  console.log(JSON.stringify(response.body.hits, null, "  "));

  // Update a document
  var response = await client.update({
    index: index_name,
    id: id,
    body: {
      doc: {
        genre: "Detective fiction",
        tv_adapted: true
      }
    },
    refresh: true
  });

  // Search for the updated document
  var query = {
    query: {
      match: {
        title: {
          query: "The Outsider",
        },
      },
    },
  };

  var response = await client.search({
    index: index_name,
    body: query,
  });

  console.log("Search results:");
  console.log(JSON.stringify(response.body.hits, null, "  "));

  // Delete the document
  var response = await client.delete({
    index: index_name,
    id: id,
  });

  console.log("Deleting document:");
  console.log(response.body);

  // Delete the index
  var response = await client.indices.delete({
    index: index_name,
  });

  console.log("Deleting index:");
  console.log(response.body);
}

search().catch(console.log);

熔断器

memoryCircuitBreaker 选项可用于防止因响应有效负载过大而无法放入客户端可用堆内存中导致的错误。

memoryCircuitBreaker 对象包含两个字段

enabled：一个布尔值，用于打开或关闭熔断器。默认为 false。
maxPercentage：确定熔断器是否触发的阈值。有效值是 [0, 1] 范围内的浮点数，表示小数形式的百分比。任何超出该范围的值都将更正为 1.0。

以下示例实例化了一个启用了熔断器且其阈值设置为可用堆大小限制的 80% 的客户端

var client = new Client({
  memoryCircuitBreaker: {
    enabled: true,
    maxPercentage: 0.8,
  },
});

辅助方法

设置
连接到 OpenSearch
使用 Amazon OpenSearch Service 进行身份验证：AWS Signature Version 4
- 从 AWS Lambda 函数内部进行身份验证
创建索引
索引文档
搜索文档
更新文档
删除文档
删除索引
示例程序
熔断器

此页面有帮助吗？

✔ 是 ✖ 否

告诉我们原因

剩余 350 字符

有问题？在 OpenSearch 论坛上提问。

想要贡献？编辑此页面或创建问题。