Creación de un mapa de sinónimos (API REST de Azure AI Search)

  • Artículo

En Azure AI Search, un mapa de sinónimos contiene una lista de reglas para expandir o volver a escribir una consulta de búsqueda en términos equivalentes.

Puede usar POST o PUT en la solicitud. Para cualquiera de ellos, el documento JSON del cuerpo de la solicitud proporciona la definición de objeto.

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

De forma alternativa, puede usar PUT y especificar el nombre de asignación del sinónimo en el identificador URI.

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

HTTPS es necesario para todas las solicitudes de servicio. Si el mapa de sinónimos no existe, se crea. Si ya existe, se actualiza a la nueva definición.

Nota

El número máximo de asignaciones de sinónimos que puede crear varía según el plan de tarifa. Para más información, consulte los límites del servicio.

Parámetros de identificador URI

Parámetro Descripción
nombre del servicio Necesario. Establézcalo en el nombre único definido por el usuario del servicio de búsqueda.
nombre del mapa de sinónimos Obligatorio en el URI si usa PUT. El nombre debe estar en minúsculas, empezar con una letra o un número, no tener barras diagonales ni puntos y tener menos de 128 caracteres. Después de iniciar el nombre con una letra o un número, el resto del nombre puede incluir cualquier letra, número y guiones, siempre y cuando los guiones no sean consecutivos.
api-version Necesario. La versión estable actual es api-version=2020-06-30. Consulte Versiones de API para obtener más versiones.

Encabezados de solicitud

En la siguiente tabla se describen los encabezados de solicitud obligatorios y opcionales.

Campos Descripción
Content-Type Necesario. Establézcalo en application/json
api-key Opcional si usa roles de Azure y se proporciona un token de portador en la solicitud; de lo contrario, se requiere una clave. Una clave de API es una cadena única generada por el sistema que autentica la solicitud en el servicio de búsqueda. Las solicitudes de creación deben incluir un api-key encabezado establecido en la clave de administrador (en lugar de una clave de consulta). Consulte Conexión a Azure AI Search mediante la autenticación de claves para más información.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene una definición de mapa de sinónimos, que incluye el formato de la asignación de sinónimos y la lista de reglas en el formato especificado.

El siguiente JSON es una representación de alto nivel de las partes principales de la definición.

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

La solicitud contiene las siguientes propiedades:

Propiedad Descripción
name Necesario. Nombre del mapa de sinónimos. Un nombre de mapa de sinónimos solo debe contener letras minúsculas, dígitos o guiones, no puede empezar ni terminar con guiones y está limitado a 128 caracteres.
format Necesario. Actualmente solo se admite el formato Apache Solr (solr).
Sinónimos Necesario. Reglas de sinónimos separadas por el carácter de nueva línea ('\n').
claveDeCifrado Opcional. Se usa para cifrar un mapa de sinónimos, con sus propias claves, administradas en azure Key Vault. Disponible para los servicios de búsqueda facturables creados en o después del 2019-01-01.

Una encryptionKey sección contiene un elemento definido keyVaultKeyName por el usuario (obligatorio), generado por el sistema keyVaultKeyVersion (obligatorio) y un elemento keyVaultUri que proporciona la clave (necesaria, también denominada nombre DNS). Un URI de ejemplo podría ser "https://my-keyvault-name.vault.azure.net".

Opcionalmente, puede especificar accessCredentials si no usa una identidad de sistema administrada. Las propiedades de incluyen applicationId (identificador de aplicación de accessCredentials Azure Active Directory al que se concedieron permisos de acceso a la Key Vault de Azure especificada) y applicationSecret (clave de autenticación de la aplicación de Azure AD especificada). Un ejemplo de la sección siguiente ilustra la sintaxis.

Response

Para obtener una solicitud correcta: "201 Creado".

Ejemplos

Ejemplo: lista de sinónimos con asignaciones equivalentes y explícitas.

Una regla de asignación equivalente enumera términos o frases equivalentes separados por comas ("USA, Estados Unidos, Estados Unidos of America"). La regla expande la búsqueda a todos los términos o frases equivalentes. Por ejemplo, un documento de búsqueda que contenga USA coincidirá con las consultas que contienen el término USA o las frases "United States", o "United States of America".

La asignación explícita se indica mediante una flecha => ("EE. UU., EE.UU., EE.UU., Estados Unidos, Estados Unidos de América => EE. UU."). Cuando se especifica, una secuencia de términos de una consulta de búsqueda que coincida con el lado izquierdo de => se reemplazará por las alternativas del lado derecho. Dada la regla, las consultas U.S. de búsqueda o "United States" todas se volverán a escribir en USA. La asignación explícita solo se aplica en la dirección especificada y no vuelve a "United States" escribir la consulta USA en en este caso. Observe que "Estados Unidos" es una consulta de frases entre comillas. Si desea una coincidencia en toda la frase, la cadena de consulta debe incluirse entre comillas dobles. De lo contrario, cada término, "United" y "States", se evalúa por separado.

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

Ejemplo: Claves de cifrado

Las claves de cifrado son claves administradas por el cliente que se usan para el cifrado adicional. Para más información, consulte Cifrado mediante claves administradas por el cliente en Azure Key Vault.

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

Consulte también