From 38724104d4fec1fad3c7423001a05feaf0dc98fd Mon Sep 17 00:00:00 2001 From: Sima Zhu <48036328+sima-zhu@users.noreply.github.com> Date: Fri, 1 May 2020 16:45:18 -0700 Subject: [PATCH] Update readme and changelog for preview 3 release (#10672) --- .../azure-search-documents/CHANGELOG.md | 7 ++- sdk/search/azure-search-documents/README.md | 46 ++++++++++--------- .../azure/search/documents/ReadmeSamples.java | 22 ++++----- 3 files changed, 40 insertions(+), 35 deletions(-) diff --git a/sdk/search/azure-search-documents/CHANGELOG.md b/sdk/search/azure-search-documents/CHANGELOG.md index 73f391ee38d7d..a44db5e21aa05 100644 --- a/sdk/search/azure-search-documents/CHANGELOG.md +++ b/sdk/search/azure-search-documents/CHANGELOG.md @@ -1,7 +1,10 @@ # Release History -## 1.0.0-beta.3 (Unreleased) -- Change `createOrUpdate*` and `delete*` APIs in `SearchServiceClient` to use boolean `onlyIfUnchanged` instead of `MatchConditioans`. +## 1.0.0-beta.3 (2020-05-05) +- Replaced `isRetrievable` API with `isHidden`, parameter name changed from `retrievable` to `hidden`. +- Changed Azure Search service version from `2019-05-06` to `2019-05-06-Preview` +- Changed `createOrUpdate` and `delete` APIs in `SearchServiceClient` to use boolean `onlyIfUnchanged` instead of `MatchConditions`. +- Updated reactor core to `3.3.5.RELEASE`. ## 1.0.0-beta.2 (2020-04-06) diff --git a/sdk/search/azure-search-documents/README.md b/sdk/search/azure-search-documents/README.md index 382e7b00c2aa8..51b917ded1107 100644 --- a/sdk/search/azure-search-documents/README.md +++ b/sdk/search/azure-search-documents/README.md @@ -23,14 +23,14 @@ create and manage indexes, load data, implement search features, execute queries ### Prerequisites -- Java Development Kit (JDK) with version 8 or above +- [Java Development Kit (JDK) with version 8 or above][jdk] - [Azure subscription][azure_subscription] -- [Cognitive Search service][search] +- [Azure Cognitive Search service][search] ### Authenticate the client -In order to interact with the Cognitive Search service you'll need to create an instance of the Search Client class. -To make this possible you will need an [api-key of the Cognitive Search service](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys). +In order to interact with the Azure Cognitive Search service you'll need to create an instance of the Search Client class. +To make this possible you will need an [api-key of the Azure Cognitive Search service](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys). The SDK provides two clients. @@ -39,12 +39,12 @@ The SDK provides two clients. #### Create a SearchServiceClient -Once you have the values of the Cognitive Search Service [URL endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint) -and [admin key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys) you can create the Search Service client: +Once you have the values of the Azure Cognitive Search service [URL endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint) +and [admin key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys) you can create the SearchServiceClient: ```Java -SearchServiceClient client = new SearchServiceClientBuilder() +SearchServiceClient searchServiceClient = new SearchServiceClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(adminKey)) .buildClient(); @@ -54,7 +54,7 @@ or ```Java -SearchServiceAsyncClient client = new SearchServiceClientBuilder() +SearchServiceAsyncClient searchServiceAsyncClient = new SearchServiceClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(adminKey)) .buildAsyncClient(); @@ -62,14 +62,14 @@ SearchServiceAsyncClient client = new SearchServiceClientBuilder() #### Create a SearchIndexClient -To create a SearchIndexClient, you will need an existing index name as well as the values of the Cognitive Search Service +To create a SearchIndexClient, you will need an existing index name as well as the values of the Azure Cognitive Search service [URL endpoint](https://docs.microsoft.com/en-us/azure/search/search-create-service-portal#get-a-key-and-url-endpoint) and [query key](https://docs.microsoft.com/en-us/azure/search/search-security-api-keys). Note that you will need an admin key to index documents (query keys only work for queries). ```Java -SearchIndexClient client = new SearchIndexClientBuilder() +SearchIndexClient searchIndexClient = new SearchIndexClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(apiKey)) .indexName(indexName) @@ -80,7 +80,7 @@ or ```Java -SearchIndexAsyncClient client = new SearchIndexClientBuilder() +SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(apiKey)) .indexName(indexName) @@ -89,7 +89,7 @@ SearchIndexAsyncClient client = new SearchIndexClientBuilder() ## Key concepts -Azure Cognitive Search has the concepts of search services and indexes and documents, where a search service contains +Azure Cognitive Search service has the concepts of search services and indexes and documents, where a search service contains one or more indexes that provides persistent storage of searchable data, and data is loaded in the form of JSON documents. Data can be pushed to an index from an external data source, but if you use an indexer, it's possible to crawl a data source to extract and load data into an index. @@ -106,7 +106,7 @@ There are several types of operations that can be executed against the service: ### Create an index -Create Index using `SearchIndexClient` create in above [section](Create-a-SearchIndexClient) +Create Index using `searchIndexClient` instantiated in [Create a SearchServiceClient](#create-a-searchserviceclient) ```java @@ -121,11 +121,11 @@ Index newIndex = new Index() .setName("Cuisine") .setType(DataType.EDM_STRING))); // Create index. -searchClient.createIndex(newIndex); +searchServiceClient.createIndex(newIndex); ``` ### Upload a Document -Upload hotel document to Search Index. +Upload hotel document to Search Index using `searchIndexClient` instantiated [Create a SearchIndexClient](#create-a-searchindexclient) ```java @@ -134,17 +134,17 @@ hotels.add(new Hotel().setHotelId("100")); hotels.add(new Hotel().setHotelId("200")); hotels.add(new Hotel().setHotelId("300")); // Upload hotel. -indexClient.uploadDocuments(hotels); +searchIndexClient.uploadDocuments(hotels); ``` ### Search on hotel name -Search hotel using keyword. +Search hotel using keyword using `searchIndexClient` instantiated in [Create a SearchIndexClient](#create-a-searchindexclient) ```java // Perform a text-based search -for (SearchResult result : indexClient.search("luxury hotel", +for (SearchResult result : searchIndexClient.search("luxury hotel", new SearchOptions(), new RequestOptions(), Context.NONE)) { // Each result is a dynamic Map @@ -156,6 +156,8 @@ for (SearchResult result : indexClient.search("luxury hotel", } ``` +- Samples are explained in detail [here][samples_readme]. + ## Troubleshooting ### General @@ -195,10 +197,10 @@ This project has adopted the [Microsoft Open Source Code of Conduct][coc]. For m or contact [opencode@microsoft.com][coc_contact] with any additional questions or comments. - +[jdk]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable [api_documentation]: https://aka.ms/java-docs -[search]: https://azure.microsoft.com/en-us/services/search/ -[search_docs]: https://docs.microsoft.com/en-us/azure/search/ +[search]: https://azure.microsoft.com/services/search/ +[search_docs]: https://docs.microsoft.com/azure/search/ [azure_subscription]: https://azure.microsoft.com/free [maven]: https://maven.apache.org/ [package]: https://search.maven.org/artifact/com.azure/azure-search-documents @@ -211,6 +213,6 @@ or contact [opencode@microsoft.com][coc_contact] with any additional questions o [coc_faq]: https://opensource.microsoft.com/codeofconduct/faq/ [coc_contact]: mailto:opencode@microsoft.com [add_headers_from_context_policy]: https://github.com/Azure/azure-sdk-for-java/blob/master/sdk/core/azure-core/src/main/java/com/azure/core/http/policy/AddHeadersFromContextPolicy.java -[rest_api]: https://docs.microsoft.com/en-us/rest/api/searchservice/http-status-codes +[rest_api]: https://docs.microsoft.com/rest/api/searchservice/http-status-codes ![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-java%2Fsdk%2Fsearch%2Fazure-search-documents%2FREADME.png) diff --git a/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/ReadmeSamples.java b/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/ReadmeSamples.java index fdc0feb47742a..4ecd3e795e084 100644 --- a/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/ReadmeSamples.java +++ b/sdk/search/azure-search-documents/src/samples/java/com/azure/search/documents/ReadmeSamples.java @@ -33,25 +33,25 @@ public class ReadmeSamples { private String adminKey = "admin key"; private String apiKey = "api key"; private String indexName = "index name"; - private SearchServiceClient searchClient = new SearchServiceClientBuilder().buildClient(); - private SearchIndexClient indexClient = new SearchIndexClientBuilder().buildClient(); + private SearchServiceClient searchServiceClient = new SearchServiceClientBuilder().buildClient(); + private SearchIndexClient searchIndexClient = new SearchIndexClientBuilder().buildClient(); public void createSearchClient() { - SearchServiceClient client = new SearchServiceClientBuilder() + SearchServiceClient searchServiceClient = new SearchServiceClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(adminKey)) .buildClient(); } public void createAsyncSearchClient() { - SearchServiceAsyncClient client = new SearchServiceClientBuilder() + SearchServiceAsyncClient searchServiceAsyncClient = new SearchServiceClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(adminKey)) .buildAsyncClient(); } public void createIndexClient() { - SearchIndexClient client = new SearchIndexClientBuilder() + SearchIndexClient searchIndexClient = new SearchIndexClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(apiKey)) .indexName(indexName) @@ -59,7 +59,7 @@ public void createIndexClient() { } public void createAsyncIndexClient() { - SearchIndexAsyncClient client = new SearchIndexClientBuilder() + SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder() .endpoint(endpoint) .credential(new AzureKeyCredential(apiKey)) .indexName(indexName) @@ -73,7 +73,7 @@ public void customHeaders() { headers.put("my-header3", "my-header3-value"); // Call API by passing headers in Context. Index index = new Index().setName(indexName); - searchClient.createIndexWithResponse( + searchServiceClient.createIndexWithResponse( index, new RequestOptions(), new Context(AddHeadersFromContextPolicy.AZURE_REQUEST_HTTP_HEADERS_KEY, headers)); @@ -82,7 +82,7 @@ public void customHeaders() { public void handleErrorsWithSyncClient() { try { - Iterable results = indexClient.search("hotel"); + Iterable results = searchIndexClient.search("hotel"); } catch (HttpResponseException ex) { // The exception contains the HTTP status code and the detailed message // returned from the search service @@ -104,7 +104,7 @@ public void createIndexWithSyncClient() { .setName("Cuisine") .setType(DataType.EDM_STRING))); // Create index. - searchClient.createIndex(newIndex); + searchServiceClient.createIndex(newIndex); } public void uploadDocumentWithSyncClient() { @@ -113,12 +113,12 @@ public void uploadDocumentWithSyncClient() { hotels.add(new Hotel().setHotelId("200")); hotels.add(new Hotel().setHotelId("300")); // Upload hotel. - indexClient.uploadDocuments(hotels); + searchIndexClient.uploadDocuments(hotels); } public void searchTextWithSyncClient() { // Perform a text-based search - for (SearchResult result : indexClient.search("luxury hotel", + for (SearchResult result : searchIndexClient.search("luxury hotel", new SearchOptions(), new RequestOptions(), Context.NONE)) { // Each result is a dynamic Map