Synonym Maps - Create Or Update

Reference

Service:: Search Service

API Version:: 2024-07-01

Creates a new synonym map or updates a synonym map if it already exists.

PUT {endpoint}/synonymmaps('{synonymMapName}')?api-version=2024-07-01

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string	The endpoint URL of the search service.
synonymMapName	path	True	string	The name of the synonym map to create or update.
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.
If-Match		string	Defines the If-Match condition. The operation will be performed only if the ETag on the server matches this value.
If-None-Match		string	Defines the If-None-Match condition. The operation will be performed only if the ETag on the server does not match this value.
Prefer	True	string	For HTTP PUT requests, instructs the service to return the created/updated resource on success.

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 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
200 OK	SynonymMap
201 Created	SynonymMap
Other Status Codes	ErrorResponse	Error response.

Examples

SearchServiceCreateOrUpdateSynonymMap

Sample request

HTTP

PUT https://myservice.search.windows.net/synonymmaps('mysynonymmap')?api-version=2024-07-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": null
  }
}

Sample response

Status code:: 200

{
  "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": null
  }
}

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": 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.
ErrorAdditionalInfo	The resource management error additional info.
ErrorDetail	The error detail.
ErrorResponse	Error response
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, 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.

ErrorAdditionalInfo

The resource management error additional info.

Name	Type	Description
info	object	The additional info.
type	string	The additional info type.

ErrorDetail

The error detail.

Name	Type	Description
additionalInfo	ErrorAdditionalInfo[]	The error additional info.
code	string	The error code.
details	ErrorDetail[]	The error details.
message	string	The error message.
target	string	The error target.

ErrorResponse

Error response

Name	Type	Description
error	ErrorDetail	The error object.

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, 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 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