Integration Into Your Application: Azure Cognitive Search – Part 4

Learn how to use the Azure Cognitive Search, prepare your application data to make it searchable, and improve performance and quality of your search results. In the last articles of this series, we created an index and filled it with data from the PokeApi. Now it is time to show you how you can search this index and integrate the search into your application.

In diesem Artikel:

Article Series

  1. Part 1: Introduction to Azure Cognitive Search
  2. Part 2: The search index
  3. Part 3: Index your Data
  4. Part 4: Integrate Azure Cognitive Search Into Your Application ⬅

To search the data, Azure Cognitive Search offers different ways (also different query types) to query your index. The most common query type is the normal search. But there are other options for using Azure Cognitive Search to do autocomplete or suggestion searches. The result set is limited to the requested fields for these specific search types, and the search behavior differs from the standard search.

Search Your Data with the REST API

The simplest way to query the index of an Azure Cognitive Search instance is to use the Rest API. You can issue a GET or POST request to the URI https://[service name][index name]/docs?[query parameters]. The Rest API can only be used via HTTPs. Additionally, two mandatory parameters must be set when calling the API.

  • api-version: The version of the API of Azure Cognitive Search you are using. Consult the list of API versions for further details
  • api-key: The API key to authenticate your request. You can find it in the Azure Portal

The API version always has to be included in the URI as a query parameter. The api-key can be sent as a query parameter or as an http-header. This depends on what key you are using (see below). If you don’t send these parameters, you will get the status code 403 (Forbidden) or 400 (Bad Request) as a response. There are two different types of keys you can use to work with the API (or the SDKs):

  • Admin: The admin key is a key which has full access to all functionality of the Azure Cognitive Search. You are able to manage indexes, indexers, and data sources and query the index. This type of key is used in my Azure Function that deletes and creates the index and indexer. If you are using the REST API this key must be sent as HTTP header api-key.
  • Query: The query key is a read-only key to query the index and retrieve data. With this key, you are not allowed to modify the index or the indexer. This key is most suitable to use it in your application to query the Azure Cognitive Search. This type of key is used in the demo page that searches the index with the PokeAPI data. The Query key has to be sent as query parameter api-key.

Additional to these keys, the REST API is also secured by the CORS definitions that we had defined when we created the index. To do a simple search, there is additional information that has to be sent to the server. These parameters can be sent as query parameters (HTTP) or as request body (POST):

  • search: Search term you are searching for. There are two different kinds of how the syntax of the search term can look like. The default query syntax allows operators like * or and. If a more complex syntax is needed, you have to send a second parameter:

    • queryType: Values are simple or full. Simple is the default query syntax. Then full syntax allows using a more complex query syntax.
  • skip/take: Skip and take a number of result items. Useful if you want to page your search results.
  • count: Boolean if a count field should be included in the result.
  • orderBy: By which property should the search result be ordered.

Besides a regular search, you can also use two other search types:

  • SuggestSearch: This search type can be used to do a simple search after matches close to the search term.
  • Autocomplete: This search type can be used to do a search for autocompletion.

Both search types are using different URIs and have another search result than the default search. Also, these search types have the possibility to add pre/post highlighting tags, so you can directly use the response in your html/application.

Besides the REST API, there are also SDKs for different programming languages like .NET, JAVA, JavaScript, or Python. The SDKs are a wrapper around the REST API, so you have support creating the requests to query the index.

Integrate the Search in Your .NET API

If you want to include the search into your existing API, you can use the .NET SDK. To use this SDK, just add the (Microsoft.Azure.Search)[] (Version 10 is used in this article series). New features will be implemented only in version 11 of the API. There also will be a change of the package name. It will be released under the name Azure.Search.Documents instead of Microsoft.Azure.Search. To query the search index, you first have to create some data models you can work with. For the demo search, there are three models necessary:

					public partial class Pokemon
  [IsSortable, IsRetrievable(true)]
  public string Id { get; set; }
  [IsFilterable, IsFacetable, IsRetrievable(true), IsSortable]
  public int Height { get; set; }

  [IsFilterable, IsRetrievable(true), IsSearchable, IsSortable]
  public string Name { get; set; }
  public Sprites Sprites { get; set; }
  public Type[] Types { get; set; }
  [IsFacetable, IsFilterable, IsRetrievable(true)]
  public int Weight { get; set; }

public partial class Sprites
  public string FrontDefault { get; set; }

public partial class Type
  [IsFacetable, IsFilterable, IsRetrievable(true), IsSortable]
  public string Name { get; set; }


The Pokemon class is the main data model. There are two complex properties in this data model that need extra classes: Sprites and Type. For each property, you can define search attributes like if the property is filterable or sortable. These are the same properties that are set in the first article where I described the index in a JSON file.

To search the index, you have to create a SearchServiceClient. For this, you just need your serviceName and your apiKey. With the created SearchServiceClient, you can get an ISearchIndexClient by calling the GetClient method with the index name as a parameter.

On this ISearchIndexClient, you can call the Search method on the Documents property. The method is typed. This is because by adding the type, you have full typings in the search results. As parameters of the search method, you have to pass the searchTerm (Pikachu) and the search parameters. The search parameters are the same search parameters you can use in the Rest API (see above). You will get a list of results on which you can access the documents that are typed because of the typed Search method call.

					var serviceClient = new SearchServiceClient("sj-search",new SearchCredentials("apiKey"));
var indexClient = serviceClient.Indexes.GetClient("pokeapi-index").
var results = indexClient.Documents.Search<Pokemon>("Pikachu", new SearchParameters());

foreach (SearchResult<Pokemon> result in results.Results)
    // Document is of type T = Pokemon

Integrating the search into your own API offers you the possibility to hide the search behind your own URI and also hide the API key from the application users. Also you are able to secure the search query access with protecting your API calls with some authentication.

A Small Demo Application

To demonstrate how the search works, I have used the Azure Portal to create a demo application that searches the PokeApi index and shows the result. The Azure Portal offers the possibility to create such a demo application to test your index. You can find the demo application on GitHub. To execute the demo application, just open the AzSearch.html in your browser. You will see an empty page with a search field. Now you can search for a Pokemon. For example, just type Pik*, and you will get a suggestion of all available Pokemon starting with Pik. Hitting enter will show you a full list of all found pokemon including preview pictures. In the left column of the page, you will see a slider where you can filter by the Pokemon’s weight.

If you are open the development tools of your browser and look into the network tab, you can see the search request for the search and the suggestion.


In this article series, you saw how to use the Azure Cognitive SearchI created an index, and filled it with data. In this last article of the series, I showed you two different ways (REST API, .NET SDK) to search your data and query the index. Now you should be able to index and search your data. This article series was only a first look into the Azure Cognitive Search. There are many additional options you can use to make your search faster and more specific. 

I hope this introduction could help create an overview of the Azure Cognitive Search and help you with the entry in this topic.

Have fun!

Mehr Artikel zu Cloud Native

Aktuelle Artikel, Screencasts, Webinare und Interviews unserer Experten für Sie

Verpassen Sie keine Inhalte zu Angular, .NET Core, Blazor, Azure und Kubernetes und melden Sie sich zu unserem kostenlosen monatlichen Dev-Newsletter an.

Newsletter Anmeldung
Diese Artikel könnten Sie interessieren
Cloud Native

Cloud Security: The 4C’s Of Cloud-Native Security – Part 5

In the last part of the article series on the 4C's of cloud-native security, we will look at securing the cloud environment itself. Although actual steps to harden your cloud infrastructure differ based on the cloud vendor and the services used to architecture your cloud-native application, many concepts and methodologies are quite similar.
Cloud Native

Code Security: The 4C’s Of Cloud-Native Security – Part 4

In this part of the article series on the 4C's of cloud-native security, we will take a closer look at code security. We will briefly inspect why code security is essential, why it should be addressed from the beginning, and why trends such as shift-left security are important aspects of overall security considerations.
Cloud Native

Cluster Security: The 4C’s Of Cloud-Native Security – Part 3

Securing the Kubernetes cluster (which may act as a runtime platform for several components of typical cloud-native applications) addresses one of the 4C's in cloud-native security. If you haven't heard about the 4C's of cloud-native security yet or want a quick refresher, you should read my corresponding introduction article.
Cloud Native

Container Security: The 4C’s Of Cloud-Native Security – Part 2

Securing the container images of your cloud-native application building blocks addresses one of the 4C's in cloud-native security. If you haven't heard about the 4C's of cloud-native security yet or want a quick refresher, you should read my corresponding introduction post.
Cloud Native

Code, Container, Cluster, Cloud: The 4C’s Of Cloud-Native Security – Part 1

Containers and cloud-native design patterns gained popularity over the past years. More and more organizations use containers in production and adopt cloud-native practices and methodologies to get even more value from existing containerized applications and underlying technologies such as container orchestrators like Kubernetes.
Cloud Native

Ausführen von Containern in Azure Container Instances (ACI) direkt über die Docker CLI

Vor einigen Monaten haben sowohl Microsoft als auch Docker eine nahtlose Integration von Azure Container Instances (ACI) und Docker CLI angekündigt. Als Container-Enthusiast musste ich mich natürlich mit dieser Integration befassen. Ich habe es in verschiedenen Szenarien getestet, um zu sehen, wie es mich unterstützen und meine Produktivität steigern könnte.