diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 6cd7b04b07..905b5021da 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -2,15 +2,17 @@ - [User Guide](#user-guide) - [Sample data](#sample-data) + - [IndexData class](#indexdata-class) - [Create a client](#create-a-client) - [Create an index](#create-an-index) - [Index data](#index-data) - - [Search for the document](#search-for-the-documents) + - [Search for the documents](#search-for-the-documents) - [Search documents using a match query](#search-documents-using-a-match-query) - [Aggregations](#aggregations) - [Delete the document](#delete-the-document) - [Delete the index](#delete-the-index) - - [Aggregations](#aggregations) +- [Using different transport options](#using-different-transport-options) + - [Amazon Managed OpenSearch](#amazon-managed-opensearch) ## Sample data @@ -136,3 +138,28 @@ client.delete(d -> d.index(index).id("1")); DeleteIndexRequest deleteIndexRequest = new DeleteRequest.Builder().index(index).build(); DeleteIndexResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest); ``` + +# Using different transport options + +## Amazon Managed OpenSearch + +Use `AwsSdk2Transport` to make requests to Amazon Managed OpenSearch. + +```java +SdkHttpClient httpClient = ApacheHttpClient.builder().build(); + +OpenSearchClient client = new OpenSearchClient( + new AwsSdk2Transport( + httpClient, + "search-...us-west-2.es.amazonaws.com", // OpenSearch endpoint, without https:// + "es" // signing service name + Region.US_WEST_2, // OpenSearch endpoint region + AwsSdk2TransportOptions.builder().build() + ) +); + +InfoResponse info = client.info(); +System.out.println(info.version().distribution() + ": " + info.version().number()); + +httpClient.close(); +``` diff --git a/java-client/build.gradle.kts b/java-client/build.gradle.kts index 81e04806b1..a69194b161 100644 --- a/java-client/build.gradle.kts +++ b/java-client/build.gradle.kts @@ -135,6 +135,8 @@ val integrationTest = task("integrationTest") { systemProperty("password", System.getProperty("password", "admin")) systemProperty("tests.awsSdk2support.domainHost", System.getProperty("tests.awsSdk2support.domainHost", null)) + systemProperty("tests.awsSdk2support.domainServiceName", + System.getProperty("tests.awsSdk2support.domainServiceName", "es")) systemProperty("tests.awsSdk2support.domainRegion", System.getProperty("tests.awsSdk2support.domainRegion", "us-east-1")) } diff --git a/java-client/src/main/java/org/opensearch/client/transport/aws/AwsSdk2Transport.java b/java-client/src/main/java/org/opensearch/client/transport/aws/AwsSdk2Transport.java index 1069cf7832..f5273e32b7 100644 --- a/java-client/src/main/java/org/opensearch/client/transport/aws/AwsSdk2Transport.java +++ b/java-client/src/main/java/org/opensearch/client/transport/aws/AwsSdk2Transport.java @@ -73,6 +73,7 @@ public class AwsSdk2Transport implements OpenSearchTransport { private final SdkHttpClient httpClient; private final SdkAsyncHttpClient asyncHttpClient; private final String host; + private final String signingServiceName; private final Region signingRegion; private final JsonpMapper defaultMapper; private final AwsSdk2TransportOptions transportOptions; @@ -96,7 +97,31 @@ public AwsSdk2Transport( @Nonnull String host, @Nonnull Region signingRegion, @CheckForNull AwsSdk2TransportOptions options) { - this(httpClient, null, host, signingRegion, options); + this(httpClient, null, host, "es", signingRegion, options); + } + + /** + * Create an {@link OpenSearchTransport} with a SYNCHRONOUS AWS Http client + *

+ * Note that asynchronous OpenSearch requests sent through this transport will be dispatched + * *synchronously* on the calling thread. + * + * @param httpClient HTTP client to use for OpenSearch requests + * @param host The fully qualified domain name to connect to + * @param signingServiceName The AWS signing service name, one of `es` (Amazon OpenSearch) or `aoss` (Amazon OpenSearch Serverless). + * @param signingRegion The AWS region for which requests will be signed. This should typically match + * the region in `host`. + * @param options Options that apply to all requests. Can be null. Create with + * {@link AwsSdk2TransportOptions#builder()} and use these to specify non-default credentials, + * compression options, etc. + */ + public AwsSdk2Transport( + @Nonnull SdkHttpClient httpClient, + @Nonnull String host, + @Nonnull String signingServiceName, + @Nonnull Region signingRegion, + @CheckForNull AwsSdk2TransportOptions options) { + this(httpClient, null, host, signingServiceName, signingRegion, options); } /** @@ -118,7 +143,54 @@ public AwsSdk2Transport( @Nonnull String host, @Nonnull Region signingRegion, @CheckForNull AwsSdk2TransportOptions options) { - this(null, asyncHttpClient, host, signingRegion, options); + this(null, asyncHttpClient, host, "es", signingRegion, options); + } + + /** + * Create an {@link OpenSearchTransport} with an ASYNCHRONOUS AWS Http client + *

+ * Note that synchronous OpenSearch requests sent through this transport will be dispatched + * using the asynchronous client, but the calling thread will block until they are complete. + * + * @param asyncHttpClient HTTP client to use for OpenSearch requests + * @param host The target host + * @param signingRegion The AWS region for which requests will be signed. This should typically match + * the region in `host`. + * @param options Options that apply to all requests. Can be null. Create with + * {@link AwsSdk2TransportOptions#builder()} and use these to specify non-default credentials, + * compression options, etc. + */ + public AwsSdk2Transport( + @Nonnull SdkAsyncHttpClient asyncHttpClient, + @Nonnull String host, + @Nonnull String signingSericeName, + @Nonnull Region signingRegion, + @CheckForNull AwsSdk2TransportOptions options) { + this(null, asyncHttpClient, host, signingSericeName, signingRegion, options); + } + + /** + * Create an {@link OpenSearchTransport} with both synchronous and asynchronous AWS HTTP clients. + *

+ * The synchronous client will be used for synchronous OpenSearch requests, and the asynchronous client + * will be used for asynchronous HTTP requests. + * + * @param httpClient HTTP client to use for OpenSearch requests + * @param asyncHttpClient HTTP client to use for synchronous OpenSearch requests + * @param host The fully qualified domain name to connect to + * @param signingRegion The AWS region for which requests will be signed. This should typically match + * the region in `host`. + * @param options Options that apply to all requests. Can be null. Create with + * {@link AwsSdk2TransportOptions#builder()} and use these to specify non-default credentials, + * compression options, etc. + */ + public AwsSdk2Transport( + @CheckForNull SdkHttpClient httpClient, + @CheckForNull SdkAsyncHttpClient asyncHttpClient, + @Nonnull String host, + @Nonnull Region signingRegion, + @CheckForNull AwsSdk2TransportOptions options) { + this(httpClient, asyncHttpClient, host, "es", signingRegion, options); } /** @@ -132,6 +204,7 @@ public AwsSdk2Transport( * @param host The fully qualified domain name to connect to * @param signingRegion The AWS region for which requests will be signed. This should typically match * the region in `host`. + * @param signingServiceName The AWS signing service name, one of `es` (Amazon OpenSearch) or `aoss` (Amazon OpenSearch Serverless). * @param options Options that apply to all requests. Can be null. Create with * {@link AwsSdk2TransportOptions#builder()} and use these to specify non-default credentials, * compression options, etc. @@ -140,6 +213,7 @@ public AwsSdk2Transport( @CheckForNull SdkHttpClient httpClient, @CheckForNull SdkAsyncHttpClient asyncHttpClient, @Nonnull String host, + @Nonnull String signingServiceName, @Nonnull Region signingRegion, @CheckForNull AwsSdk2TransportOptions options) { if (httpClient == null && asyncHttpClient == null) @@ -150,6 +224,7 @@ public AwsSdk2Transport( this.httpClient = httpClient; this.asyncHttpClient = asyncHttpClient; this.host = host; + this.signingServiceName = signingServiceName; this.signingRegion = signingRegion; this.transportOptions = options != null ? options : AwsSdk2TransportOptions.builder().build(); this.defaultMapper = Optional.ofNullable(options) @@ -314,7 +389,7 @@ private SdkHttpFullRequest prepareRequest( Aws4SignerParams signerParams = Aws4SignerParams.builder() .awsCredentials(credentials.resolveCredentials()) - .signingName("es") + .signingName(this.signingServiceName) .signingRegion(signingRegion) .build(); return Aws4Signer.create().sign(req.build(), signerParams); diff --git a/java-client/src/test/java/org/opensearch/client/opensearch/integTest/aws/AwsSdk2TransportTestCase.java b/java-client/src/test/java/org/opensearch/client/opensearch/integTest/aws/AwsSdk2TransportTestCase.java index 05421559d1..1995611d7f 100644 --- a/java-client/src/test/java/org/opensearch/client/opensearch/integTest/aws/AwsSdk2TransportTestCase.java +++ b/java-client/src/test/java/org/opensearch/client/opensearch/integTest/aws/AwsSdk2TransportTestCase.java @@ -83,6 +83,7 @@ protected OpenSearchClient getClient( transport = new AwsSdk2Transport( getAsyncHttpClient(), getTestClusterHost(), + getTestClusterServiceName(), getTestClusterRegion(), getTransportOptions().build() ); @@ -90,6 +91,7 @@ protected OpenSearchClient getClient( transport = new AwsSdk2Transport( getHttpClient(), getTestClusterHost(), + getTestClusterServiceName(), getTestClusterRegion(), getTransportOptions().build() ); @@ -107,6 +109,7 @@ protected OpenSearchAsyncClient getAsyncClient( transport = new AwsSdk2Transport( getAsyncHttpClient(), getTestClusterHost(), + getTestClusterServiceName(), getTestClusterRegion(), getTransportOptions().build() ); @@ -114,6 +117,7 @@ protected OpenSearchAsyncClient getAsyncClient( transport = new AwsSdk2Transport( getHttpClient(), getTestClusterHost(), + getTestClusterServiceName(), getTestClusterRegion(), getTransportOptions().build() ); @@ -131,6 +135,7 @@ protected OpenSearchIndicesClient getIndexesClient( transport = new AwsSdk2Transport( getAsyncHttpClient(), getTestClusterHost(), + getTestClusterServiceName(), getTestClusterRegion(), getTransportOptions().build() ); @@ -138,6 +143,7 @@ protected OpenSearchIndicesClient getIndexesClient( transport = new AwsSdk2Transport( getHttpClient(), getTestClusterHost(), + getTestClusterServiceName(), getTestClusterRegion(), getTransportOptions().build() ); @@ -150,6 +156,11 @@ protected String getTestClusterHost() { return cluster; } + protected String getTestClusterServiceName() { + String cluster = System.getProperty("tests.awsSdk2support.domainServiceName"); + return cluster; + } + protected Region getTestClusterRegion() { String region = System.getProperty("tests.awsSdk2support.domainRegion"); return region != null ? Region.of(region) : Region.US_EAST_1;