Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Saiba como criar e configurar um serviço do 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 em versão prévia.
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.
- Criar ou atualizar um serviço
- Atualizar um serviço
- Alterar os tipos de preço
- Ativar controle de acesso baseado em funções do Azure para o plano de dados
- Aplicar uma política de chaves gerenciada pelo cliente
- Desativar classificador semântico
- Desabilitar cargas de trabalho que enviam dados para recursos externos
- Crie uma chave de consulta
- Gerar novamente 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, confira a referência de API.
Pré-requisitos
Uma conta do 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 proprietário ou administrador da sua assinatura do Azure.
As chamadas à 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.
Abra um shell de comando para a CLI do Azure.
Entre em sua assinatura do Azure. Se você tiver vários locatários ou assinaturas, certifique-se de selecionar o correto.
az login
Obtenha o ID do locatário e o ID da assinatura.
az account show
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
criado 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 incluirá a instalação para que você possa concluir as tarefas neste artigo.
Inicie o Visual Studio Code e selecione o bloco Extensões.
Pesquise o cliente REST e selecione Instalar.
Abra ou crie um novo arquivo nomeado com uma extensão de arquivo
.rest
ou.http
.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
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}}
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
Crie ou atualize 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 = 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 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ê 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 tipos de preço
Se você precisar de mais capacidade, poderá mudar para um tipo de preço mais alto. Atualmente, você só pode mover para cima entre as camadas Basic e Standard (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 propriedades sku
e hostingMode
. 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: 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 authOptions
comoaadOrApiKey
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 com uma segunda solicitação, dessa vez configurando 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"
}
}
}
}
Impor uma política de chave gerenciada pelo cliente
Se você estiver usando a criptografia gerenciada pelo cliente, você pode habilitar "encryptionWithCMK" com a "obrigatoriedade" definida como "Habilitado" para que o serviço de pesquisa informe seu status de conformidade.
Quando você habilita essa política, as chamadas REST que criam objetos com dados confidenciais, como a cadeia de conexão em uma fonte de dados, falham caso uma chave de criptografia não seja 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 classificador semântico
O classificador semântico é habilitado por padrão no plano gratuito que permite até 1.000 solicitações por mês sem custo. Você pode bloquear o recurso no nível de serviço para impedir 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"
}
}
Desabilitar cargas de trabalho que enviam 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
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 administrador por 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 endpoints privados
### 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óximas etapas
Depois que um serviço de pesquisa é 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.