Search Management

  • Article

The Management REST APIs of Azure Cognitive Search provide programmatic access to administrative operations:

  • Create, update, and delete a search service
  • Retrieve search service information
  • Create, regenerate, or retrieve api-keys (query or admin keys)
  • Add or remove replicas and partitions (adjust capacity)
  • Configure a search service to use a private endpoint
  • Enable or disable Azure role-based access control

For all other tasks, such as creating and querying an index, use the Search Service REST APIs instead.

To fully administer your service programmatically, you work with two APIs: the Management REST API of Azure Cognitive Search documented here, plus the common Azure Resource Manager REST API. The Resource Manager API is used for general-purpose operations that aren't service specific, such as querying subscription data, listing geo-locations, and so forth.

Permissions and access control

Administration rights are conveyed through built-in roles in Azure Active Directory (Azure AD):

  • Owner or Contributor assignments are required for most tasks.
  • Reader role has limited access to service information (GET operations, except for API keys which require Owner or Contributor permissions).

For more information, see Use Azure role-based access controls in Azure Cognitive Search.

A best practice is to assign roles to groups rather than individual users. An Azure subscription owner or global administrator manages these assignments. For more information, see Assign Azure AD roles to groups.

Connect to the management endpoint

When setting up the connection, start with the Resource Manager endpoint https://management.azure.com and then add the subscription ID, provider (Microsoft.Search), and API version. Operations are specified in the body of the request.

A fully specified endpoint has the following components:

https://management.azure.com/subscriptions/[subscriptionId]/resourceGroups/[resourceGroupName]/providers/Microsoft.Search/searchServices/[serviceName]?api-version=2020-08-01

The following clients are commonly used to call the management REST APIs:

Client Instructions and examples
Azure PowerShell using the Az.Search module Manage Cognitive Search using Azure PowerShell
Azure Command-Line Interface (CLI) Manage Cognitive Search using the Azure CLI
Postman Manage Cognitive Search using REST

You can also manage a search service using the Azure portal.

Management APIs in other SDKs

The REST APIs are foundational to Azure Cognitive Search, and any changes to the programming model are reflected in the REST APIs first.

Alternatives include the following Azure SDKs, which are independently updated on separate release schedules:

See also