Gere o teu serviço Pesquisa de IA do Azure usando APIs REST

Aprenda a criar e configurar um serviço Pesquisa de IA do Azure usando as APIs REST Management. Apenas as APIs REST de Gestão têm garantia de acesso antecipado às funcionalidades de pré-visualização.

A API de Gestão REST está disponível em versões estáveis e de pré-visualização. Certifique-se de definir uma versão da API de pré-visualização se estiver a aceder a funcionalidades de pré-visualização.

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

Pré-requisitos

• Uma conta no Azure com uma subscrição ativa. Cria uma conta gratuitamente.

• Visual Studio Code com um cliente REST.

• CLI do Azure para obter um token de acesso, conforme descrito nos passos seguintes. Deve ser proprietário ou administrador na sua subscrição do Azure.

  As chamadas à API REST de gestão são autenticadas através do Microsoft Entra ID. Deve fornecer um token de acesso no pedido e permissões para criar e configurar um recurso. Além do CLI do Azure, pode usar Azure PowerShell para criar um token de acesso.

  1. Abra uma shell de comandos para o CLI do Azure.

  2. Inicie sessão na sua subscrição do Azure. Se tiver vários inquilinos ou subscrições, certifique-se de selecionar 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
     

     Deves ter um ID de arrendatário, ID de subscrição e token de portador. Vais colar esses valores no ficheiro .rest ou .http que criares no passo seguinte.

Configurar o Visual Studio Code

Se não está familiarizado com o cliente REST para Visual Studio Code, esta secção inclui a configuração para que possa completar as tarefas deste artigo.

1. Inicia Visual Studio Code e seleciona o mosaico Extensões.

2. Procure o cliente REST e selecione Instalar.

   

3. Abra ou crie um novo ficheiro cujo nome inclua a extensão de ficheiro .rest ou .http.

4. Forneça variáveis para os valores que recuperou no passo 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 na sua subscrição.

    ### 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 pedido. Uma resposta deve aparecer num painel adjacente. Se já tiveres serviços de pesquisa, eles estão listados. Caso contrário, a lista está vazia, mas desde que o código HTTP seja 200 OK, estás pronto para os próximos passos.

   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 subscrição atual. Este exemplo usa variáveis para o nome e região do serviço de pesquisa, que ainda não foram definidos. Ou fornece os nomes diretamente ou adiciona 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

Algumas funcionalidades do Pesquisa de IA do Azure só estão disponíveis para novos serviços. Para evitar a recreação do serviço e trazer estas capacidades para um serviço já existente, poderá conseguir atualizar o 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 os escalões de preços

Se precisar de mais ou menos capacidade, pode mudar para outro escalão de preço. Atualmente, só podes alternar entre os níveis Básico e Padrão (S1, S2 e S3). Use a sku propriedade para especificar o novo nível.

### 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 , utilize uma combinação de sku propriedades e hostingMode . Definir sku para standard3 e "hostingMode" para 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ções 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ços de Pesquisa

Configure o seu serviço de pesquisa para reconhecer um cabeçalho de autorização em pedidos de dados que forneçam um token de acesso OAuth2.

Para usar controlo de acesso baseado em papéis para operações de plano de dados, defina authOptions e aadOrApiKey, e então envie o pedido.

Para usar exclusivamente controlo de acesso baseado em funções, desative a autenticação por chave API fazendo um segundo pedido, desta vez definindo disableLocalAuth para verdadeiro.

### 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 computação confidencial

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

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

O tipo de computação é fixo durante toda a vida útil do seu serviço de pesquisa. Para configurar permanentemente a computação confidencial, defina a computeType propriedade para confidential num 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"
        }
    }

Aplicar uma política de chaves geridas pelo cliente

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

Quando ativa esta política, qualquer chamada REST que crie objetos contendo dados sensíveis, como o cadeia de ligação dentro de uma fonte de dados, falhará se não for fornecida uma chave de encriptação: "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"
            }
        }
    }

Desative cargas de trabalho que enviem dados para recursos externos

Pesquisa de IA do Azure escreve em fontes de dados externas ao atualizar um armazenamento de conhecimento, guardar o estado da sessão de depuração ou cachear enriquecimentos. O exemplo seguinte desativa estas cargas de trabalho ao 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"
        }
    }

Eliminar 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 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

Só podes regenerar uma chave API de administrador de cada 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 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 privadas de endpoint

### 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}}

Operações de pesquisa por listas

### 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óximos passos

Depois de configurar um serviço de pesquisa, os seus próximos passos incluem criar um índice ou consultar um índice usando o portal Azure, APIs REST ou um SDK do Azure.

• Crie um índice de Pesquisa de IA do Azure no portal Azure
• Configure um indexador para carregar dados de outros serviços
• Consultar um índice de Pesquisa de IA do Azure usando o explorador de pesquisa no portal Azure
• Como usar Pesquisa de IA do Azure em .NET