Synonym Maps - Create Or Update

服務:
Search Service
API 版本:
2025-08-01-preview

建立新的同義字對映，或更新同義字對映（如果已存在）。

PUT {endpoint}/synonymmaps('{synonymMapName}')?api-version=2025-08-01-preview

URI 參數

名稱 位於 必要 類型 Description
endpoint
 path True

string

搜尋服務的端點 URL。
synonymMapName
 path True

string

要建立或更新的同義字對映的名稱。
api-version
 query True

string

用戶端 API 版本。

要求標頭

名稱 必要 類型 Description
x-ms-client-request-id

string (uuid)

隨請求一起傳送的追蹤 ID，以協助偵錯。
If-Match

string

定義 If-Match 條件。 只有在伺服器上的 ETag 符合此值時，才會執行作業。
If-None-Match

string

定義 If-None-Match 條件。 只有在伺服器上的 ETag 不符合此值時，才會執行作業。
Prefer True

string

針對 HTTP PUT 要求，指示服務在成功時傳回建立/更新的資源。

要求本文

名稱 必要 類型 Description
format True

SynonymMapFormat

同義字對映的格式。 目前僅支援「solr」格式。
name True

string

同義字對映的名稱。
synonyms True

string

指定同義字對映格式的一系列同義字規則。 規則必須以換行符分隔。
@odata.etag

string

同義字對映的 ETag。
encryptionKey

SearchResourceEncryptionKey

您在 Azure 金鑰保存庫中建立的加密金鑰描述。 當您想要完全保證沒有人 （甚至 Microsoft） 無法解密您的數據時，此金鑰可用來為您的數據提供額外的待用加密層級。 加密資料後，資料將始終保持加密狀態。 搜尋服務會忽略嘗試將此屬性設定為 Null。 如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的資料不會受到影響。 使用客戶管理的金鑰進行加密不適用於免費搜尋服務，且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。

回應

名稱 類型 Description
200 OK

SynonymMap

201 Created

SynonymMap

Other Status Codes

ErrorResponse

錯誤回應。

範例

SearchServiceCreateOrUpdateSynonymMap

範例要求

PUT https://previewexampleservice.search.windows.net/synonymmaps('mysynonymmap')?api-version=2025-08-01-preview





{
  "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": "<applicationSecret>"
    }
  },
  "@odata.etag": "0x1234568AE7E58A1"
}

範例回覆

狀態碼:
200 
{
  "@odata.etag": "0x1234568AE7E58A1",
  "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": "<applicationSecret>"
    }
  }
}
狀態碼:
201 
{
  "@odata.etag": "0x1234568AE7E58A1",
  "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": "<applicationSecret>"
    }
  }
}

定義

名稱 Description
AzureActiveDirectoryApplicationCredentials

針對搜尋服務建立之已註冊應用程式認證，用於對儲存在 Azure 金鑰保存庫中的加密金鑰進行驗證存取。
ErrorAdditionalInfo

資源管理錯誤其他資訊。
ErrorDetail

錯誤詳細數據。
ErrorResponse

錯誤回應
SearchIndexerDataNoneIdentity

清除資料來源的身分識別屬性。
SearchIndexerDataUserAssignedIdentity

指定要使用的資料來源身分識別。
SearchResourceEncryptionKey

Azure Key Vault 中的客戶管理加密金鑰。 您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。
SynonymMap

代表同義字對映定義。
SynonymMapFormat

同義字對映的格式。 目前僅支援「solr」格式。

AzureActiveDirectoryApplicationCredentials

Object

針對搜尋服務建立之已註冊應用程式認證，用於對儲存在 Azure 金鑰保存庫中的加密金鑰進行驗證存取。

名稱 類型 Description
applicationId

string

已授與 Azure 金鑰保存庫所需存取權限的 AAD 應用程式識別碼，可在加密待用資料時使用。 應用程式識別碼不應與 AAD 應用程式的物件識別碼混淆。
applicationSecret

string

指定 AAD 應用程式的驗證金鑰。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱 類型 Description
info

object

其他資訊。
type

string

其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。
code

string

錯誤碼。
details

ErrorDetail[]

錯誤詳細資料。
message

string

錯誤訊息。
target

string

錯誤目標。

ErrorResponse

Object

錯誤回應

名稱 類型 Description
error

ErrorDetail

error 物件。

SearchIndexerDataNoneIdentity

Object

清除資料來源的身分識別屬性。

名稱 類型 Description
@odata.type string:

#Microsoft.Azure.Search.DataNoneIdentity

指定身分類型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

Object

指定要使用的資料來源身分識別。

名稱 類型 Description
@odata.type string:

#Microsoft.Azure.Search.DataUserAssignedIdentity

指定身分類型的 URI 片段。
userAssignedIdentity

string

使用者指派受控識別的完整 Azure 資源識別碼，通常採用「/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId」格式，應該已指派給搜尋服務。

SearchResourceEncryptionKey

Object

Azure Key Vault 中的客戶管理加密金鑰。 您建立和管理的金鑰可用來加密或解密靜態資料，例如索引和同義字對映。

名稱 類型 Description
accessCredentials

AzureActiveDirectoryApplicationCredentials

用來存取 Azure 金鑰保存庫的選擇性 Azure Active Directory 認證。 如果改用受控識別，則不需要。
identity SearchIndexerDataIdentity:

用於此加密金鑰的明確受控識別。 如果未指定且存取認證屬性為 Null，則會使用系統指派的受控識別。 更新資源時，如果未指定明確身分識別，則會保持不變。 如果指定 “none” ，則會清除此屬性的值。
keyVaultKeyName

string

要用來加密待用資料的 Azure 金鑰保存庫名稱。
keyVaultKeyVersion

string

要用來加密待用資料的 Azure 金鑰版本。
keyVaultUri

string

Azure 金鑰保存庫的 URI，也稱為 DNS 名稱，其中包含要用來加密待用資料的金鑰。 範例 URI 可能是 https://my-keyvault-name.vault.azure.net。

SynonymMap

Object

代表同義字對映定義。

名稱 類型 Description
@odata.etag

string

同義字對映的 ETag。
encryptionKey

SearchResourceEncryptionKey

您在 Azure 金鑰保存庫中建立的加密金鑰描述。 當您想要完全保證沒有人 （甚至 Microsoft） 無法解密您的數據時，此金鑰可用來為您的數據提供額外的待用加密層級。 加密資料後，資料將始終保持加密狀態。 搜尋服務會忽略嘗試將此屬性設定為 Null。 如果您想要輪替加密金鑰，您可以視需要變更此屬性;您的資料不會受到影響。 使用客戶管理的金鑰進行加密不適用於免費搜尋服務，且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
format

SynonymMapFormat

同義字對映的格式。 目前僅支援「solr」格式。
name

string

同義字對映的名稱。
synonyms

string

指定同義字對映格式的一系列同義字規則。 規則必須以換行符分隔。

SynonymMapFormat

列舉型別

同義字對映的格式。 目前僅支援「solr」格式。

值 Description
solr

選取同義字對映的 SOLR 格式。