Gerenciar seu serviço Azure AI Search usando APIs REST

Saiba como criar e configurar um serviço Azure AI Search usando as APIs REST de gerenciamento. Somente as APIs REST de gerenciamento têm a garantia de fornecer acesso antecipado aos recursos de visualização.

A API REST de gerenciamento está disponível em versões estáveis e de visualização. Certifique-se de definir uma versão da API de visualização se estiver acessando os recursos de visualização.

• Criar ou atualizar um serviço
• Atualizar um serviço
• Alterar categorias de preços
• Habilitar o controlo de acesso do Azure baseado em função para o plano de dados
• Aplicar uma política de chaves gerenciada pelo cliente
• Desativar classificação semântica
• Desabilitar cargas de trabalho que enviam dados por push para recursos externos
• Criar uma chave de consulta
• Regenerar uma chave de administrador
• Listar conexões de ponto de extremidade privado
• Listar operações de pesquisa
• Excluir um serviço de pesquisa

Todas as APIs REST de gerenciamento têm exemplos. Se uma tarefa não for abordada neste artigo, consulte a referência da API.

Pré-requisitos

• Uma conta do Azure com uma assinatura ativa. Crie uma conta gratuitamente.

• Código do Visual Studio com um cliente REST.

• CLI do Azure para obter um token de acesso, conforme descrito nas etapas a seguir. Você deve ser um proprietário ou administrador em sua assinatura do Azure.

  As chamadas da API REST de gerenciamento são autenticadas por meio do Microsoft Entra ID. Você deve fornecer um token de acesso na solicitação e permissões para criar e configurar um recurso. Além da CLI do Azure, você pode usar o Azure PowerShell para criar um token de acesso.

  1. Abra um shell de comando para a CLI do Azure.

  2. Entre na sua assinatura do Azure. Se tiver vários inquilinos ou subscrições, certifique-se de que seleciona o correto.

     az login
     

  3. Obtenha o ID do inquilino e o ID da subscrição.

     az account show
     

  4. Obtenha um token de acesso.

     az account get-access-token --query accessToken --output tsv
     

     Você deve ter um ID de locatário, ID de assinatura e token de portador. Você colará esses valores no arquivo .rest ou no arquivo .http que irá criar na próxima etapa.

Configurar o Visual Studio Code

Se você não estiver familiarizado com o cliente REST para Visual Studio Code, esta seção inclui a instalação para que você possa concluir as tarefas neste artigo.

1. Inicie o Visual Studio Code e selecione o bloco Extensões .

2. Procure o cliente REST e selecione Instalar.

   

3. Abra ou crie um novo ficheiro nomeado com uma extensão .rest ou .http.

4. Forneça variáveis para os valores recuperados na etapa anterior.

   @tenantId = PASTE-YOUR-TENANT-ID-HERE
   @subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Verifique se a sessão está operacional listando os serviços de pesquisa na sua assinatura.

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
         Content-type: application/json
         Authorization: Bearer {{token}}
   

6. Selecione Enviar pedido. Uma resposta deve aparecer em um painel adjacente. Se você tiver serviços de pesquisa existentes, eles serão listados. Caso contrário, a lista estará vazia, mas desde que o código HTTP seja 200 OK, você estará pronto para as próximas etapas.

   HTTP/1.1 200 OK
   Cache-Control: no-cache
   Pragma: no-cache
   Content-Length: 22068
   Content-Type: application/json; charset=utf-8
   Expires: -1
   x-ms-ratelimit-remaining-subscription-reads: 11999
   x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
   x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
   x-ms-routing-request-id: WESTUS2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
   Strict-Transport-Security: max-age=31536000; includeSubDomains
   X-Content-Type-Options: nosniff
   X-Cache: CONFIG_NOCACHE
   X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
   Date: Thu, 14 Mar 2024 01:20:52 GMT
   Connection: close
   
   {
     "value": [ . . . ]
   }
   

Criar ou atualizar um serviço

Cria ou atualiza um serviço de pesquisa sob a assinatura atual. Este exemplo usa variáveis para o nome e a região do serviço de pesquisa, que ainda não foram definidas. Forneça os nomes diretamente ou adicione novas variáveis à coleção.

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "North Central US",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

Atualizar um serviço

Alguns recursos do Azure AI Search estão disponíveis apenas para novos serviços. Para evitar a recreação de serviço e trazer esses recursos para um serviço existente, você pode atualizar seu serviço.

### Upgrade a search service
@resource-group = my-rg
@search-service-name = my-search
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/upgrade?api-version=2025-02-01-preview  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Alterar escalão de preço

Se precisar de mais capacidade, pode mudar para um escalão de preços mais elevado. Atualmente, você só pode subir entre as camadas Básico e Padrão (S1, S2 e S3). Use a sku propriedade para especificar a camada superior .

### Change pricing tiers
@resource-group = my-rg
@search-service-name = my-search
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2025-02-01-preview HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

Criar um serviço S3HD

Para criar um serviço S3HD , use uma combinação de sku e hostingMode propriedades. Defina sku como standard3 e "hostingMode" como HighDensity.

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

Configurar o acesso baseado em função para o plano de dados

Aplica-se a: Contribuidor de Dados de Índice de Pesquisa, Leitor de Dados de Índice de Pesquisa, Colaborador de Serviço de Pesquisa

Configure seu serviço de pesquisa para reconhecer um cabeçalho de autorização em solicitações de dados que fornecem um token de acesso OAuth2.

Para usar o controle de acesso baseado em função para operações de plano de dados, defina authOptions como aadOrApiKey e envie a solicitação.

Para usar exclusivamente o controlo de acesso baseado em função, desative a autenticação de chave de API seguindo com uma segunda solicitação, desta vez definindo disableLocalAuth como verdadeiro.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

Aplicar uma política de chaves gerenciada pelo cliente

Se estiver a utilizar encriptação gerida pelo cliente, pode ativar "encryptionWithCMK" com "enforcement" definido como "Enabled" se pretender que o serviço de pesquisa reporte o seu estado de conformidade.

Quando você habilita essa política, quaisquer chamadas REST que criem objetos contendo dados confidenciais, como a cadeia de conexão em uma fonte de dados, falharão se uma chave de criptografia não for fornecida: "Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

Desativar classificação semântica

O ranker semântico é ativado por padrão no plano gratuito que permite até 1.000 solicitações por mês sem nenhum custo. Você pode bloquear o recurso no nível de serviço para evitar o uso.

### Disable semantic ranker
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

Desativar cargas de trabalho que transmitem dados para fontes externas

O Azure AI Search grava em fontes de dados externas ao atualizar um repositório de conhecimento, salvar o estado da sessão de depuração ou armazenar enriquecimentos em cache. O exemplo a seguir desabilita essas cargas de trabalho no nível de serviço.

### Disable external access
PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Excluir um serviço de pesquisa

### Delete a search service
DELETE https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Listar chaves de API de administrador

### List admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Regenerar chaves de API de administrador

Você só pode regenerar uma chave de API de administração de cada vez.

### Regnerate admin keys
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Criar chaves de API de consulta

### Create a query key
@query-key-name = myQueryKey
POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Listar conexões de ponto de extremidade privado

### List private endpoint connections
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Listar operações de pesquisa

### List search operations
GET https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Próximos passos

Depois que um serviço de pesquisa for configurado, suas próximas etapas incluem criar um índice ou consultar um índice usando o portal do Azure, APIs REST ou um SDK do Azure.

• Criar um índice do Azure AI Search no portal do Azure
• Configurar um indexador para carregar dados de outros serviços
• Consultar um índice da Pesquisa do Azure AI usando o Gerenciador de Pesquisa no portal do Azure
• Como usar o Azure AI Search no .NET