Criar ou Atualizar Alias (API REST de Pré-visualização)

  • Artigo

Aplica-se a: 2023-07-01-Preview, 2021-04-30-Preview

Importante

07-2023-01-Preview (sem alterações).

A Pré-visualização 2021-04-30 adiciona a API.

Na Pesquisa de IA do Azure, um alias é um nome secundário que pode ser utilizado para fazer referência a um índice para consultas, indexação e outras operações.

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

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

Para pedidos de atualização, utilize PUT e especifique o nome do alias no URI.

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

O HTTPS é necessário para todos os pedidos de serviço. No caso de PUT, se o alias não existir, é criado. Se já existir, será atualizado para a nova definição.

A criação de um alias estabelece um mapeamento entre um nome de alias e um nome de índice. Se o pedido for bem-sucedido, o alias pode ser utilizado para indexação, consulta e outras operações.

Atualizar um alias permite-lhe mapear esse alias para um índice de pesquisa diferente. Quando atualiza um alias existente, toda a definição é substituída pelo conteúdo do corpo do pedido. Em geral, o melhor padrão a utilizar para atualizações é obter a definição de alias com um GET, modificá-lo e, em seguida, atualizá-lo com PUT.

Nota

Uma atualização para um alias pode demorar até 10 segundos a ser propagada pelo sistema, pelo que deve aguardar pelo menos 10 segundos antes de eliminar o índice ao qual o alias foi previamente mapeado.

Nota

O número máximo de aliases que pode criar varia de acordo com 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 este valor como o nome exclusivo definido pelo utilizador do seu serviço de pesquisa.
nome do alias Necessário no URI se estiver a utilizar PUT. O nome tem de ser minúsculo, começar com uma letra ou número, não ter barras ou pontos e ter menos de 128 carateres. Depois de começar o nome com uma letra ou número, o resto do nome pode incluir qualquer letra, número e travessões, desde que os traços não sejam consecutivos.
api-version Obrigatório. A versão de pré-visualização atual é 2023-07-01-Preview. Veja Versões da API para obter mais versões.

Cabeçalhos de Pedido

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

Campos Description
Content-Type Obrigatório. Defina este valor 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. A opção Criar pedidos tem de incluir um api-key cabeçalho definido para a chave de administrador (em oposição a uma chave de consulta). Veja Connect to Azure AI Search using key authentication (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 alias, que inclui o nome de um alias e uma matriz com o nome de um único índice.

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

{   
    "name" : (optional on PUT; required on POST) "The name of the alias",  
    "indexes" : (required) ["The name of the index the alias is mapped to"]
}

O pedido contém as seguintes propriedades:

Propriedade Descrição
name Obrigatório. O nome do alias. Um nome de alias só tem de conter letras minúsculas, dígitos ou travessões, não pode começar ou terminar com travessões e está limitado a 128 carateres.
índices Obrigatório. O nome do índice para o que o alias está mapeado. Apenas um único nome de índice pode ser incluído na matriz.

Resposta

Para um pedido de criação bem-sucedido, deverá ver o código de estado "201 Criado".

Para um pedido de atualização bem-sucedido, deverá ver "204 Sem Conteúdo".

Exemplos

Exemplo: um alias de índice

{   
  "name" : "my-alias",  
  "indexes" : ["my-index"]
}

Ver também