Criar Mapa de Sinónimos (API REST da Pesquisa de IA do Azure)

  • Artigo

No Azure AI Search, um mapa de sinónimos contém uma lista de regras para expandir ou reescrever uma consulta de pesquisa para termos equivalentes.

Pode utilizar POST ou PUT no pedido. Para qualquer um deles, o documento JSON no corpo do pedido fornece a definição do objeto.

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

Em alternativa, pode utilizar PUT e especificar o nome do mapa do sinónimo no URI.

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

O HTTPS é necessário para todos os pedidos de serviço. Se o mapa de sinónimos não existir, será criado. Se já existir, será atualizado para a nova definição.

Nota

O número máximo de mapas de sinónimos que pode criar varia consondo o escalão de preço. Para obter mais informações, veja Limites de serviço.

Parâmetros do URI

Parâmetro Description
nome do serviço Obrigatório. Defina-o como o nome exclusivo e definido pelo utilizador do seu serviço de pesquisa.
nome do mapa do sinónimo Necessário no URI se utilizar PUT. O nome tem de ser minúscula, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. Depois de iniciar o nome com uma letra ou número, o resto do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos.
api-version Obrigatório. A versão estável atual é api-version=2020-06-30. Veja Versões da API para obter mais versões.

Cabeçalhos do Pedido

A tabela seguinte descreve os cabeçalhos de pedido obrigatórios e opcionais.

Campos Description
Content-Type Obrigatório. Defina esta opção como application/json
api-key Opcional se estiver a utilizar funções do Azure e for fornecido um token de portador no pedido, caso contrário, é necessária uma chave. Uma chave de api é uma cadeia exclusiva gerada pelo sistema que autentica o pedido no seu serviço de pesquisa. Criar pedidos tem de incluir um api-key cabeçalho definido para a sua chave de administrador (em oposição a uma chave de consulta). Veja Ligar à Pesquisa de IA do Azure com a autenticação de chaves para obter detalhes.

Corpo do Pedido

O corpo do pedido contém uma definição de mapa de sinónimos, que inclui o formato do mapa de sinónimos e a lista de regras no formato especificado.

O seguinte JSON é uma representação de alto nível das partes principais da definição.

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

O pedido contém as seguintes propriedades:

Propriedade Descrição
name Obrigatório. O nome do mapa de sinónimos. Um nome de mapa de sinónimos só tem de conter letras minúsculas, dígitos ou traços, não pode iniciar ou terminar com traços e está limitado a 128 carateres.
formato Obrigatório. Apenas o formato Do Apache Solr (solr) é atualmente suportado.
sinónimos Obrigatório. Regras de sinónimos separadas pelo caráter de nova linha ('\n').
encryptionKey Opcional. Utilizado para encriptar um mapa de sinónimos, com as suas próprias chaves, gerido no seu Key Vault do Azure. Disponível para serviços de pesquisa faturáveis criados em ou depois de 2019-01-01.

Uma encryptionKey secção contém uma definição do keyVaultKeyName utilizador (necessária), uma gerada pelo keyVaultKeyVersion sistema (necessária) e uma keyVaultUri chave fornecida (necessária, também referida como nome DNS). Um URI de exemplo pode ser "https://my-keyvault-name.vault.azure.net".

Opcionalmente, pode especificar accessCredentials se não está a utilizar uma identidade de sistema gerida. Propriedades de inclusão applicationId (ID da accessCredentials Aplicação do Azure Active Directory a quem foram concedidas permissões de acesso à sua Key Vault do Azure especificada) e applicationSecret (chave de autenticação da aplicação Azure AD especificada). Um exemplo na secção seguinte ilustra a sintaxe.

Resposta

Para um pedido com êxito: 201 Criado.

Exemplos

Exemplo: Lista de sinónimos com mapeamentos equivalentes e explícitos.

Uma regra de mapeamento equivalente lista termos ou expressões equivalentes separados por vírgulas ("EUA, Estados Unidos, Estados Unidos da América"). A regra expande a pesquisa para todos os termos ou expressões equivalentes. Por exemplo, um documento de pesquisa que contenha USA corresponderá a consultas que contenham o termo USA ou as expressões "United States", ou "United States of America".

O mapeamento explícito é indicado por uma seta => ("EUA, E.U.A., E.U.A., E.U.A., Estados Unidos, Estados Unidos da América => EUA"). Quando especificado, uma sequência de termos de uma consulta de pesquisa que corresponda ao lado esquerdo do => será substituída pelas alternativas no lado direito. Dada a regra, as consultas U.S. de pesquisa ou "United States" todas serão reescritas para USA. O mapeamento explícito aplica-se apenas na direção especificada e não reescreve a consulta USA neste "United States" caso. Repare que "Estados Unidos" é uma consulta de expressão entre aspas. Se quiser uma correspondência na expressão inteira, a cadeia de consulta tem de estar entre aspas duplas. Caso contrário, cada termo, "Unidos" e "Estados", é avaliado separadamente.

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

Exemplo: Chaves de encriptação

As chaves de encriptação são chaves geridas pelo cliente utilizadas para encriptação extra. Para obter mais informações, veja Encriptação com chaves geridas pelo cliente no 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)"
      }
  }
}

Ver também