Criar mapa de sinônimos (API REST do Azure AI Search)

  • 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.

Você pode usar POST ou PUT na solicitação. Para qualquer um deles, o documento JSON no corpo da solicitação fornece a definição de objeto.

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

Como alternativa, use PUT e especifique o nome do mapa de sinônimos no URI.

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

HTTPS é necessário para todas as solicitações de serviço. Se o mapa de sinônimos não existir, ele será criado. Se ele já existir, ele será atualizado para a nova definição.

Observação

O número máximo de mapas de sinônimos que você pode criar varia de acordo com o tipo de preço. Para saber mais, confira Limites do serviço.

Parâmetros de URI

Parâmetro Descrição
nome do serviço Obrigatórios. Defina isso como o nome exclusivo definido pelo usuário do serviço de pesquisa.
nome do mapa de sinônimos Necessário no URI se estiver usando PUT. O nome deve ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 caracteres. Depois de iniciar o nome com uma letra ou número, o restante do nome pode incluir qualquer letra, número e traços, desde que os traços não sejam consecutivos.
api-version Obrigatórios. A versão estável atual é api-version=2020-06-30. Confira Versões de API para obter mais versões.

Cabeçalhos de solicitação

A tabela a seguir descreve os cabeçalhos de solicitação necessários e opcionais

Campos Descrição
Tipo de conteúdo Obrigatórios. Defina-o como application/json
chave de API Opcional se você estiver usando funções do Azure e um token de portador for fornecido na solicitação, caso contrário, uma chave será necessária. Uma chave de api é uma cadeia de caracteres exclusiva gerada pelo sistema que autentica a solicitação para o serviço de pesquisa. As solicitações de criação devem incluir um api-key cabeçalho definido como sua chave de administrador (em vez de uma chave de consulta). Confira Conectar-se ao Azure AI Search usando a autenticação de chave para obter detalhes.

Corpo da solicitação

O corpo da solicitação 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 JSON a seguir é uma representação de alto nível das partes main 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 } 
}

A contém as seguintes propriedades:

Propriedade Descrição
name Obrigatórios. O nome do mapa de sinônimos. Um nome de mapa de sinônimo deve conter apenas letras minúsculas, dígitos ou traços, não pode iniciar ou terminar com traços e está limitado a 128 caracteres.
format Obrigatórios. No momento, há suporte apenas para o formato Apache Solr (solr).
sinônimos Obrigatórios. Regras de sinônimo separadas pelo caractere de nova linha ('\n').
encryptionKey Opcional. Usado para criptografar um mapa de sinônimos, com suas próprias chaves, gerenciado no Key Vault do Azure. Disponível para serviços de pesquisa faturáveis criados em ou após 01-01/2019.

Uma encryptionKey seção contém um definido keyVaultKeyName pelo usuário (obrigatório), um gerado pelo keyVaultKeyVersion sistema (obrigatório) e um keyVaultUri que fornece a chave (obrigatório, também conhecido como nome DNS). Um exemplo de URI pode ser "https://my-keyvault-name.vault.azure.net".

Opcionalmente, você pode especificar accessCredentials se não está usando uma identidade do sistema gerenciado. Propriedades de include applicationId (ID de accessCredentials aplicativo do Azure Active Directory que recebeu permissões de acesso para o Azure Key Vault especificado) e applicationSecret (chave de autenticação do aplicativo Azure AD especificado). Um exemplo na próxima seção ilustra a sintaxe.

Resposta

Para uma solicitação bem-sucedida: "201 Criado".

Exemplos

Exemplo: lista de sinônimos com mapeamentos equivalentes e explícitos.

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

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

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

Exemplo: chaves de criptografia

As chaves de criptografia são chaves gerenciadas pelo cliente usadas para criptografia extra. Para obter mais informações, consulte Criptografia usando chaves gerenciadas 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)"
      }
  }
}

Confira também