共用方式為

(Azure AI 搜尋 REST API) 建立同義字對應

  • 發行項

在 Azure AI 搜尋服務中，同義字對應包含擴充或重寫搜尋查詢至對等字詞的規則清單。

您可以在要求上使用 POST 或 PUT。 針對其中一個，要求本文中的 JSON 檔會提供物件定義。

POST https://[service name].search.windows.net/synonymmaps?api-version=[api-version]      
  Content-Type: application/json  
  api-key: [admin key]

或者，您也可以使用 PUT，並在 URI 中指定同義字地圖名稱。

PUT https://[service name].search.windows.net/synonymmaps/[synonymmap name]?api-version=[api-version]  
  Content-Type: application/json  
  api-key: [admin key]

所有服務要求都需使用 HTTPS。 如果同義字對應不存在，則會建立它。 如果已經存在，則會更新為新的定義。

注意

您可以建立的同義字對應數目上限會依定價層而有所不同。 如需詳細資訊，請參閱 服務限制。

URI 參數

參數 Description
服務名稱 必要。 將此設定為搜尋服務的唯一使用者定義名稱。
同義字對應名稱 如果使用 PUT，則為 URI 的必要專案。 名稱必須是小寫，開頭為字母或數位、沒有斜線或點，且少於 128 個字元。 以字母或數位開頭名稱之後，只要虛線不連續，其餘的名稱就可以包含任何字母、數位和虛線。
api-version 必要。 目前的穩定版本為 api-version=2020-06-30 。 如需更多版本，請參閱 API 版本 。

要求標頭

下表說明必要及選用的要求標頭。

欄位 Description
Content-Type 必要。 請設為 application/json
api-key 如果您使用 Azure 角色 ，而且要求會提供持有人權杖，則為選擇性，否則需要金鑰。 API 金鑰是唯一的系統產生字串，可驗證對搜尋服務的要求。 建立要求必須包含 api-key 設定為系統管理員金鑰的標頭 (，而不是查詢金鑰) 。 如需詳細資訊 ，請參閱使用金鑰驗證連線到 Azure AI 搜尋 服務。

要求本文

要求的主體包含同義字對應定義，其中包含同義字對應的格式，以及指定格式的規則清單。

下列 JSON 是定義主要部分的高階標記法。

{   
    "name" : (optional on PUT; required on POST) "Name of the synonym map",  
    "format" : (required) "Only Apache Solr format ('solr') is currently supported.",
    "synonyms" : (required) "Synonym rules separated by the new line ('\n') character.",
    "encryptionKey":(optional) { See below for details } 
}

要求可包含下列屬性：

屬性 Description
NAME 必要。 同義字對應的名稱。 同義字對應名稱只能包含小寫字母、數位或破折號，不能以破折號開頭或結尾，且限制為 128 個字元。
format 必要。 目前僅支援 Apache Solr 格式 (solr) 。
同義字 必要。 以新行分隔的同義字規則 ('\n') 字元。
encryptionKey 選擇性。 用來加密同義字對應，並使用您自己的金鑰，在 Azure 金鑰保存庫中管理。 可用於在 2019-01-01 之後建立的可計費搜尋服務。

區 encryptionKey 段包含使用者定義的 keyVaultKeyName (必要) 、系統產生的 keyVaultKeyVersion (必要) ，以及 keyVaultUri 提供所需的金鑰 (，也稱為 DNS 名稱) 。 範例 URI 可能是 「 https://my-keyvault-name.vault.azure.net" ;。

您可以選擇性地指定 accessCredentials 您是否未使用受控系統識別。 accessCredentials的屬性包括 applicationId (已授與指定 Azure 金鑰保存庫) 存取權限的 Azure Active Directory 應用程式識別碼，以及 applicationSecret 指定之 Azure AD 應用程式) 的 (驗證金鑰。 下一節中的範例說明語法。

回應

要求成功：「201 已建立」。

範例

範例：具有對等和明確對應的同義字清單。

對等對應規則會列出以逗號分隔的對等字詞或片語， (「USA，美國，美國美國」) 。 此規則會將搜尋展開至所有對等字詞或片語。 例如，包含 的 USA 搜尋檔將會比對包含字詞或詞 USA 組 "United States" 的查詢， 或 "United States of America" 。

明確對應是由箭號 => (「USA， U.S.， U.S.， 美國， 美國的美國 = > USA」) 表示。 指定時，符合 左側 => 的搜尋查詢字詞序列將會取代為右側的替代專案。 指定規則時，搜尋查詢 U.S. 或 "United States" 全都會重寫為 USA 。 明確對應僅適用于指定的方向，而且在此案例中不會重寫查詢 USA"United States" 。 請注意，「美國」 是引號括住的片語查詢。 如果您想要整個片語的相符專案，查詢字串必須以雙引號括住。 否則，會個別評估每個詞彙 「United」 和 「States」。

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA"
}

範例：加密金鑰

加密金鑰是客戶管理的金鑰，用於額外的加密。 如需詳細資訊，請參閱在 Azure 金鑰保存庫中使用客戶管理的金鑰進行加密。

{   
  "name" : "synonymmap1",  
  "format" : "solr",  
  "synonyms" : "United States, United States of America, USA\n
  Washington, Wash. => WA",
  "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
          "applicationId": "Azure AD Application ID that was granted access permissions to your specified Azure Key Vault",
          "applicationSecret": "Authentication key of the specified Azure AD application)"
      }
  }
}

另請參閱