Gerenciar seu serviço de Pesquisa de IA do Azure  usando APIs REST

Saiba como criar e configurar um serviço de Pesquisa de IA do Azure  usando as APIs REST Management. 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 versão prévia. Certifique-se de definir uma versão da API de visualização se você estiver acessando recursos de visualização.

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

Pré-requisitos

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

• Visual Studio Code 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 de Azure.

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

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

  2. Entre em sua assinatura Azure. Se você tiver vários locatários ou assinaturas, certifique-se de selecionar o correto.

     az login
     

  3. Obtenha a ID do locatário e a ID da assinatura.

     az account show
     

  4. Obtenha um token de acesso.

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

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

Configurar Visual Studio Code

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

1. Inicie Visual Studio Code e selecione o bloco Extensions.

2. Pesquise o cliente REST e selecione Instalar.

   

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

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

   @tenant-id = PUT-YOUR-TENANT-ID-HERE
   @subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
   @token = PUT-YOUR-TOKEN-HERE
   

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

    ### List search services
    GET https://management.azure.com/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
         Content-type: application/json
         Authorization: Bearer {{token}}
   

6. Selecione Enviar solicitação. 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 enquanto o código HTTP estiver 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 na assinatura atual. Este exemplo usa variáveis para o nome e a região do serviço de pesquisa, que ainda não foram definidos. Forneça os nomes diretamente ou adicione novas variáveis à coleção.

### Create a search service (provide an existing resource group)
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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 de Pesquisa de IA do Azure  só estão disponíveis para novos serviços. Para evitar a recriação do serviço e trazer esses recursos para um serviço existente, você poderá atualizar seu serviço.

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Alterar as faixas de preço

Se você precisar de mais ou menos capacidade, poderá alternar para um tipo de preço diferente. Atualmente, você só pode alternar entre as camadas Basic e Standard (S1, S2 e S3). Use a sku propriedade para especificar a nova camada.

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  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 das propriedades sku e hostingMode. Definir sku como standard3 e "hostingMode" como HighDensity.

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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: Colaborador de dados de índice de pesquisa, leitor de dados de índice de pesquisa, colaborador do 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 authOptionscomoaadOrApiKey e envie a solicitação.

Para usar exclusivamente o controle de acesso baseado em função, desative a autenticação de chave de API seguindo uma segunda solicitação, desta vez configurando disableLocalAuth como true.

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

Configurar a computação confidencial

A computação confidencial é um tipo de computação opcional para proteção de dados em uso. Quando configurado, o serviço de pesquisa é implantado em VMs confidenciais (DCasv5 ou DCesv5) em vez de VMs padrão. Esse tipo de computação também incorre em uma sobretaxa de 10% para camadas faturáveis. Para obter mais informações, consulte a página de preços.

Para uso diário, a computação confidencial não é necessária. Recomendamos apenas esse tipo de computação para requisitos regulatórios, de conformidade ou de segurança rigorosos. Para obter mais informações, consulte casos de uso de computação confidencial.

O tipo de computação é fixado para a duração do serviço de pesquisa. Para configurar permanentemente a computação confidencial, defina a computeType propriedade como confidential em um novo serviço.

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
    Content-type: application/json
    Authorization: Bearer {{token}}
    {
        "location": "{{region}}",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

Impor uma política de chave gerenciada pelo cliente

Se você estiver usando criptografia gerenciada pelo cliente, poderá habilitar "encryptionWithCMK" com "enforcement" definido para "Enabled" se quiser que o serviço de pesquisa relate sobre seu status de conformidade.

Quando você habilita essa política, todas as chamadas REST que criam objetos que contêm dados confidenciais, como o 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."

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

Desabilitar cargas de trabalho que efetuam push de dados para recursos externos

A Pesquisa de IA do Azure grava em fontes de dados externas ao atualizar um repositório de conhecimento, salvando o estado da sessão de depuração ou armazenando os enriquecimentos em cache. O exemplo a seguir desabilita essas cargas de trabalho no nível do serviço.

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
     
     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

Excluir um serviço de pesquisa

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Listar chaves de API de administrador

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-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 administrador por vez.

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Criar chaves de API de consulta

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

Listar conexões de ponto de extremidade privado

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-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/{{subscription-id}}/resourcegroups?api-version=2021-04-01  HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

Próximas etapas

Depois que um serviço de pesquisa é configurado, as próximas etapas incluem criação de um índice ou consultando um índice usando o portal Azure, APIs REST ou um SDK do Azure.

• Criar um índice Pesquisa de IA do Azure  no portal do Azure
• Configurar um indexador para carregar dados de outros serviços
• Fazer uma consulta em um índice do Pesquisa de IA do Azure  usando o Explorador de Pesquisa no portal do Azure
• Como usar Pesquisa de IA do Azure  no .NET