Manage your Azure AI Search service with REST APIs
In this article, learn how to create and configure an Azure AI Search service using the Management REST APIs. Only the Management REST APIs are guaranteed to provide early access to preview features.
The Management REST API is available in stable and preview versions. Be sure to set a preview API version if you're accessing preview features.
- Create or update a service
- Enable Azure role-based access control for data plane
- Enforce a customer-managed key policy
- Disable semantic ranking
- Disable workloads that push data to external resources
- Create a query key
- Regenerate an admin key
- List private endpoint connections
- List search operations
- Delete a search services
All of the Management REST APIs have examples. If a task isn't covered in this article, see the API reference instead.
Prerequisites
An Azure subscription - Create one for free.
Visual Studio Code with a REST client.
Azure CLI used to get an access token. You must be an owner or administrator in your Azure subscription.
Get an access token
Management REST API calls are authenticated through Microsoft Entra ID. You need to provide an access token on the request, along with permissions to create and configure a resource.
You can use the Azure CLI or Azure PowerShell to create an access token.
Open a command shell for Azure CLI.
Sign in to your Azure subscription.
az loginGet the tenant ID and subscription ID. If you have multiple tenants or subscriptions, make sure you use the correct one.
az account showGet an access token.
az account get-access-token --query accessToken --output tsv
Set up Visual Studio Code
If you're not familiar with the REST client for Visual Studio Code, this section includes setup so that you can complete the tasks in this quickstart.
Start Visual Studio Code and select the Extensions tile.
Search for the REST client and select Install.
Open or create new file named with either a
.restor.httpfile extension.Provide variables for the values you retrieved in the previous step.
@tenantId = PASTE-YOUR-TENANT-ID-HERE @subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE @token = PASTE-YOUR-TOKEN-HEREVerify the session is operational by listing search services in your subscription.
### List search services GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01 Content-type: application/json Authorization: Bearer {{token}}Select Send request. A response should appear in an adjacent pane. If you have existing search services, they're listed. Otherwise, the list is empty, but as long as the HTTP code is 200 OK, you're ready for the next steps.
HTTP/1.1 200 OK Cache-Control: no-cache Pragma: no-cache Content-Length: 22068 Content-Type: application/json; charset=utf-8 Expires: -1 x-ms-ratelimit-remaining-subscription-reads: 11999 x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c Strict-Transport-Security: max-age=31536000; includeSubDomains X-Content-Type-Options: nosniff X-Cache: CONFIG_NOCACHE X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z Date: Thu, 14 Mar 2024 01:20:52 GMT Connection: close { "value": [ . . . ] }
Create or update a service
Creates or updates a search service under the current subscription. This example uses variables for the search service name and region, which haven't been defined yet. Either provide the names directly, or add new variables to the collection.
### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "North Central US",
"sku": {
"name": "basic"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "default"
}
}
Create an S3HD service
To create an S3HD service, use a combination of sku and hostingMode properties. Set sku to standard3 and "hostingMode" to HighDensity.
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"location": "{{region}}",
"sku": {
"name": "standard3"
},
"properties": {
"replicaCount": 1,
"partitionCount": 1,
"hostingMode": "HighDensity"
}
}
Configure role-based access for data plane
Applies to: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor
In this step, configure your search service to recognize an authorization header on data requests that provide an OAuth2 access token.
To use role-based access control for data plane operations, set authOptions to aadOrApiKey and then send the request.
To use role-based access control exclusively, turn off API key authentication by following up with a second request, this time setting disableLocalAuth to true.
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"disableLocalAuth": false,
"authOptions": {
"aadOrApiKey": {
"aadAuthFailureMode": "http401WithBearerChallenge"
}
}
}
}
Enforce a customer-managed key policy
If you're using customer-managed encryption, you can enable "encryptionWithCMK" with "enforcement" set to "Enabled" if you want the search service to report its compliance status.
When you enable this policy, any REST calls that create objects containing sensitive data, such as the connection string within a data source, will fail if an encryption key isn't provided: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Disabled",
"encryptionComplianceStatus": "Compliant"
},
}
}
Disable semantic ranking
Although semantic ranking isn't enabled by default, you could lock down the feature at the service level.
### disable semantic ranking
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"semanticSearch": "Disabled"
}
}
Disable workloads that push data to external resources
Azure AI Search writes to external data sources when updating a knowledge store, saving debug session state, or caching enrichments. The following example disables these workloads at the service level.
### disable-external-access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"publicNetworkAccess": "Disabled"
}
}
Delete a search service
### delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
List admin API keys
### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Regenerate admin API keys
You can only regenerate one admin API key at a time.
### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer
Create query API keys
### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
List private endpoint connections
### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
List search operations
### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
Next steps
After a search service is configured, next steps include create an index or query an index using the portal, REST APIs, or an Azure SDK.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for