Synonym Maps - Create Or Update

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

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

{
  "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
  }
}
{
  "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.