Services - Check Name Availability

Checks whether or not the given search service name is available for use. Search service names must be globally unique since they are part of the service URI (https://.search.windows.net).

POST https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.Search/checkNameAvailability?api-version=2023-11-01

URI Parameters

Name In Required Type Description
subscriptionId
path True

string

The unique identifier for a Microsoft Azure subscription. You can obtain this value from the Azure Resource Manager API, command line tools, or the portal.

api-version
query True

string

The API version to use for each request.

Request Header

Name Required Type Description
x-ms-client-request-id

string

uuid

A client-generated GUID value that identifies this request. If specified, this will be included in response information as a way to track the request.

Request Body

Name Required Type Description
name True

string

The search service name to validate. Search service names must only contain lowercase letters, digits or dashes, cannot use dash as the first two or last one characters, cannot contain consecutive dashes, and must be between 2 and 60 characters in length.

type True

ResourceType

The type of the resource whose name is to be validated. This value must always be 'searchServices'.

Responses

Name Type Description
200 OK

CheckNameAvailabilityOutput

The name check completed. The response contains details of whether the name is valid and available. If the name is invalid, the response also contains a message explaining why not.

Other Status Codes

CloudError

HTTP 400 (Bad Request): The given resource type is not 'searchServices'.

Security

azure_auth

Microsoft Entra ID OAuth2 authorization flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
user_impersonation impersonate your user account

Examples

SearchCheckNameAvailability

Sample request

POST https://management.azure.com/subscriptions/subid/providers/Microsoft.Search/checkNameAvailability?api-version=2023-11-01

{
  "name": "mysearchservice",
  "type": "searchServices"
}

Sample response

{
  "nameAvailable": false,
  "reason": "AlreadyExists",
  "message": ""
}

Definitions

Name Description
CheckNameAvailabilityInput

Input of check name availability API.

CheckNameAvailabilityOutput

Output of check name availability API.

CloudError

Contains information about an API error.

CloudErrorBody

Describes a particular API error with an error code and a message.

ResourceType

The type of the resource whose name is to be validated. This value must always be 'searchServices'.

UnavailableNameReason

The reason why the name is not available. 'Invalid' indicates the name provided does not match the naming requirements (incorrect length, unsupported characters, etc.). 'AlreadyExists' indicates that the name is already in use and is therefore unavailable.

CheckNameAvailabilityInput

Input of check name availability API.

Name Type Description
name

string

The search service name to validate. Search service names must only contain lowercase letters, digits or dashes, cannot use dash as the first two or last one characters, cannot contain consecutive dashes, and must be between 2 and 60 characters in length.

type

ResourceType

The type of the resource whose name is to be validated. This value must always be 'searchServices'.

CheckNameAvailabilityOutput

Output of check name availability API.

Name Type Description
message

string

A message that explains why the name is invalid and provides resource naming requirements. Available only if 'Invalid' is returned in the 'reason' property.

nameAvailable

boolean

A value indicating whether the name is available.

reason

UnavailableNameReason

The reason why the name is not available. 'Invalid' indicates the name provided does not match the naming requirements (incorrect length, unsupported characters, etc.). 'AlreadyExists' indicates that the name is already in use and is therefore unavailable.

CloudError

Contains information about an API error.

Name Type Description
error

CloudErrorBody

Describes a particular API error with an error code and a message.

CloudErrorBody

Describes a particular API error with an error code and a message.

Name Type Description
code

string

An error code that describes the error condition more precisely than an HTTP status code. Can be used to programmatically handle specific error cases.

details

CloudErrorBody[]

Contains nested errors that are related to this error.

message

string

A message that describes the error in detail and provides debugging information.

target

string

The target of the particular error (for example, the name of the property in error).

ResourceType

The type of the resource whose name is to be validated. This value must always be 'searchServices'.

Name Type Description
searchServices

string

'searchServices' is the only resource type whose name can be validated.

UnavailableNameReason

The reason why the name is not available. 'Invalid' indicates the name provided does not match the naming requirements (incorrect length, unsupported characters, etc.). 'AlreadyExists' indicates that the name is already in use and is therefore unavailable.

Name Type Description
AlreadyExists

string

The search service name is already assigned to a different search service.

Invalid

string

The search service name does not match naming requirements.