Synonym Maps - Create Or Update

服務:
Search Service
API 版本:
2026-04-01

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

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

URI 參數

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

string (uri)

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

string

同義字對應的名稱。
api-version
 query True

string

minLength: 1

用於此作業的 API 版本。

要求標頭

名稱 必要 類型 Description
Accept

Accept

接受標頭。
If-Match

string

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

string

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

Prefer

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

string (uuid)

一個不透明、全域唯一、由客戶端產生的請求字串識別碼。

要求本文

名稱 必要 類型 Description
format True enum:

solr

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

string

同義字對應的名稱。
synonyms True

string

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

string

同義字對應的 ETag。
encryptionKey

SearchResourceEncryptionKey

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

回應

名稱 類型 Description
200 OK

SynonymMap

要求已成功。
201 Created

SynonymMap

要求已成功，因此已建立新的資源。
Other Status Codes

ErrorResponse

未預期的錯誤回應。

安全性

api-key

類型: apiKey
位於: header

OAuth2Auth

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

範圍

名稱 Description
https://search.azure.com/.default

範例

SearchServiceCreateOrUpdateSynonymMap

範例要求

PUT https://exampleservice.search.windows.net/synonymmaps('mysynonymmap')?api-version=2026-04-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": "<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
Accept

接受標頭。
ErrorAdditionalInfo

資源管理錯誤附加資訊。
ErrorDetail

錯誤詳細資料。
ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。 （這也遵循 OData 錯誤回應格式。）。
Prefer

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

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

指定要使用之數據源的身分識別。
SearchResourceEncryptionKey

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

表示同義字對應定義。

Accept

列舉型別

接受標頭。

值 Description
application/json;odata.metadata=minimal

ErrorAdditionalInfo

Object

資源管理錯誤附加資訊。

名稱 類型 Description
info

附加資訊。
type

string

其他資訊類型。

ErrorDetail

Object

錯誤詳細資料。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤附加資訊。
code

string

錯誤碼。
details

ErrorDetail[]

錯誤詳情
message

string

錯誤訊息。
target

string

錯誤目標。

ErrorResponse

Object

所有 Azure Resource Manager API 的常見錯誤回應，用於回傳失敗操作的錯誤細節。 （這也遵循 OData 錯誤回應格式。）。

名稱 類型 Description
error

ErrorDetail

錯誤物件。

Prefer

列舉型別

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

值 Description
return=representation

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-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”。

SearchResourceEncryptionKey

Object

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

名稱 類型 Description
accessCredentials.applicationId

string

AAD 應用程式識別碼，已將待用數據加密時要使用的 Azure Key Vault 所需訪問許可權授與。 應用程式標識碼不應與 AAD 應用程式的物件標識元混淆。
accessCredentials.applicationSecret

string

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

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

string

要用來加密待用數據的 Azure Key Vault 金鑰名稱。
keyVaultKeyVersion

string

要用來加密待用數據的 Azure Key Vault 金鑰版本。
keyVaultUri

string

Azure Key Vault 的 URI，也稱為 DNS 名稱，其中包含用來加密待用數據的密鑰。 範例 URI 可能會 https://my-keyvault-name.vault.azure.net。

SynonymMap

Object

表示同義字對應定義。

名稱 類型 Description
@odata.etag

string

同義字對應的 ETag。
encryptionKey

SearchResourceEncryptionKey

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

solr

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

string

同義字對應的名稱。
synonyms

string

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