Synonym Maps - Create

Reference

Service:: Search Service

API Version:: 2023-11-01

Creates a new synonym map.

POST {endpoint}/synonymmaps?api-version=2023-11-01

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The endpoint URL of the search service.
api-version	query	True	string	Client Api Version.

Request Header

Name	Required	Type	Description
x-ms-client-request-id		string uuid	The tracking ID sent with the request to help with debugging.

Request Body

Name	Required	Type	Description
format	True	SynonymMapFormat	The format of the synonym map. Only the 'solr' format is currently supported.
name	True	string	The name of the synonym map.
synonyms	True	string	A series of synonym rules in the specified synonym map format. The rules must be separated by newlines.
@odata.etag		string	The ETag of the synonym map.
encryptionKey		SearchResourceEncryptionKey	A description of an encryption key that you create in Azure Key Vault. This key is used to provide an additional level of encryption-at-rest for your data when you want full assurance that no one, not even Microsoft, can decrypt your sensitive data. Once you have encrypted your data, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your data will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.

Responses

Name	Type	Description
201 Created	SynonymMap
Other Status Codes	SearchError	Error response.

Examples

SearchServiceCreateSynonymMap

Sample request

HTTP

POST https://myservice.search.windows.net/synonymmaps?api-version=2023-11-01

{
  "name": "mysynonymmap",
  "format": "solr",
  "synonyms": "United States, United States of America, USA\nWashington, Wash. => WA",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "myApplicationSecret"
    }
  }
}

Sample response

Status code:: 201

{
  "name": "mysynonymmap",
  "format": "solr",
  "synonyms": "United States, United States of America, USA\nWashington, Wash. => WA",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": null
    }
  }
}

Definitions

Name	Description
AzureActiveDirectoryApplicationCredentials	Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.
SearchError	Describes an error condition for the API.
SearchResourceEncryptionKey	A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest on your search service, such as indexes and synonym maps.
SynonymMap	Represents a synonym map definition.
SynonymMapFormat	The format of the synonym map. Only the 'solr' format is currently supported.

AzureActiveDirectoryApplicationCredentials

Credentials of a registered application created for your search service, used for authenticated access to the encryption keys stored in Azure Key Vault.

Name	Type	Description
applicationId	string	An AAD Application ID that was granted the required access permissions to the Azure Key Vault that is to be used when encrypting your data at rest. The Application ID should not be confused with the Object ID for your AAD Application.
applicationSecret	string	The authentication key of the specified AAD application.

SearchError

Describes an error condition for the API.

Name	Type	Description
code	string	One of a server-defined set of error codes.
details	SearchError[]	An array of details about specific errors that led to this reported error.
message	string	A human-readable representation of the error.

SearchResourceEncryptionKey

A customer-managed encryption key in Azure Key Vault. Keys that you create and manage can be used to encrypt or decrypt data-at-rest on your search service, such as indexes and synonym maps.

Name	Type	Description
accessCredentials	AzureActiveDirectoryApplicationCredentials	Optional Azure Active Directory credentials used for accessing your Azure Key Vault. Not required if using managed identity instead.
keyVaultKeyName	string	The name of your Azure Key Vault key to be used to encrypt your data at rest.
keyVaultKeyVersion	string	The version of your Azure Key Vault key to be used to encrypt your data at rest.
keyVaultUri	string	The URI of your Azure Key Vault, also referred to as DNS name, that contains the key to be used to encrypt your data at rest. An example URI might be `https://my-keyvault-name.vault.azure.net`.

SynonymMap

Represents a synonym map definition.

Name	Type	Description
@odata.etag	string	The ETag of the synonym map.
encryptionKey	SearchResourceEncryptionKey	A description of an encryption key that you create in Azure Key Vault. This key is used to provide an additional level of encryption-at-rest for your data when you want full assurance that no one, not even Microsoft, can decrypt your sensitive data. Once you have encrypted your data, it will always remain encrypted. The search service will ignore attempts to set this property to null. You can change this property as needed if you want to rotate your encryption key; Your data will be unaffected. Encryption with customer-managed keys is not available for free search services, and is only available for paid services created on or after January 1, 2019.
format	SynonymMapFormat	The format of the synonym map. Only the 'solr' format is currently supported.
name	string	The name of the synonym map.
synonyms	string	A series of synonym rules in the specified synonym map format. The rules must be separated by newlines.

SynonymMapFormat

The format of the synonym map. Only the 'solr' format is currently supported.

Name	Type	Description
solr	string	Selects the SOLR format for synonym maps.

Share via