通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

(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 参数

参数 说明
服务名称 必需。 将此设置为搜索服务的唯一用户定义名称。
同义词映射名称 如果使用 PUT，则对 URI 是必需的。 名称必须为小写，以字母或数字开头，没有斜杠或点，并且少于 128 个字符。 以字母或数字开头的名称后，名称的其余部分可以包含任何字母、数字和短划线，只要短划线不是连续的。
api-version 必需。 当前稳定版本为 api-version=2020-06-30。 有关更多 版本，请参阅 API 版本。

请求标头

下表介绍必需和可选的请求标头。

字段 说明
Content-Type 必需。 将其设置为 application/json
api-key 如果使用 Azure 角色 并且请求中提供了持有者令牌，则为可选，否则需要密钥。 api-key 是系统生成的唯一字符串，用于对搜索服务的请求进行身份验证。 创建请求必须包含 api-key 设置为管理密钥 (而不是查询密钥) 的标头。 有关详细信息 ，请参阅使用密钥身份验证连接到 Azure AI 搜索 。

请求正文

请求正文包含同义词映射定义，其中包括同义词映射的格式和指定格式的规则列表。

以下 JSON 是定义main部分的高级表示形式。

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

请求包含以下属性：

属性 说明
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 应用程序 ID，以及 applicationSecret (指定 Azure AD 应用程序) 的身份验证密钥。 下一部分中的示例演示了语法。

响应

对于成功的请求：“201 已创建”。

示例

示例：具有等效映射和显式映射的同义词列表。

等效映射规则列出用逗号分隔的等效术语或短语 (“美国，美国，美国美国”) 。 规则将搜索扩展到所有等效的字词或短语。 例如，包含 的 USA 搜索文档将在包含术语 USA 或短语 "United States"、 或 "United States of America"的查询上匹配。

显式映射由箭头=>表示 (“USA， U.S.A.， U.S.， 美国， 美国 of America => 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)"
      }
  }
}

另请参阅