Usar a Pesquisa de IA do Azure sem chaves

No código do aplicativo, você pode configurar uma conexão sem chave com o Azure AI Search que usa a ID do Microsoft Entra e funções para autenticação e autorização. As solicitações de aplicativo para a maioria dos serviços do Azure devem ser autenticadas com chaves ou conexões sem chave. Os desenvolvedores devem ser diligentes para nunca expor as chaves em um local não seguro. Qualquer pessoa que obtenha acesso à chave pode autenticar-se no serviço. A autenticação sem chave oferece benefícios aprimorados de gerenciamento e segurança em relação à chave da conta, pois não há nenhuma chave (ou cadeia de conexão) para armazenar.

As conexões sem chave são habilitadas com as seguintes etapas:

• Configure sua autenticação.
• Defina variáveis de ambiente, conforme necessário.
• Use um tipo de credencial da biblioteca de Identidade do Azure para criar um objeto de cliente do Azure AI Search.

Pré-requisitos

As seguintes etapas precisam ser concluídas para cargas de trabalho de desenvolvimento local e produção:

• Criar um recurso de pesquisa de IA
• Habilitar o acesso baseado em função em seu serviço de pesquisa
• Instalar a biblioteca de cliente do Azure Identity

Criar um recurso de pesquisa de IA

Antes de continuar com este artigo, você precisa de um recurso do Azure AI Search para trabalhar. Se você não tiver um recurso, crie seu recurso agora. Habilite o controle de acesso baseado em função (RBAC) para o recurso.

Instalar a biblioteca de cliente do Azure Identity

Para usar uma abordagem sem chave, atualize seu código habilitado para Pesquisa de IA com a biblioteca de cliente do Azure Identity.

dotnet add package Azure.Identity

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.10.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

npm install --save @azure/identity

pip install azure-identity

Atualizar o código-fonte para usar DefaultAzureCredential

A biblioteca de Identidade do DefaultAzureCredential Azure permite executar o mesmo código no ambiente de desenvolvimento local e na nuvem do Azure. Crie uma única credencial e reutilize a instância de credencial conforme necessário para aproveitar o cache de token.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.windows.net"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

Desenvolvimento local

O desenvolvimento local usando funções inclui estas etapas:

• Atribua sua identidade pessoal a funções RBAC no recurso específico.
• Use uma ferramenta como a CLI do Azure ou o Azure PowerShell para autenticar com o Azure.
• Estabeleça variáveis de ambiente para seu recurso.

Papéis para o desenvolvimento local

Como um desenvolvedor local, sua identidade do Azure precisa de controle total sobre as operações do plano de dados. Estas são as funções sugeridas:

• Colaborador do Serviço de Pesquisa, criar e gerenciar objetos
• Contribuidor de dados de índice de pesquisa, carregar um índice
• Pesquisar Leitor de Dados de Índice, consultar um índice

Encontre a sua identidade pessoal com uma das seguintes ferramentas. Use essa identidade como o <identity-id> valor.

Quando aplicável, substitua <identity-id>, <subscription-id>e <resource-group-name> pelos seus valores reais.

Autenticação para desenvolvimento local

Use uma ferramenta em seu ambiente de desenvolvimento local para autenticação na identidade do Azure. Depois de autenticado, a DefaultAzureCredential instância no código-fonte localiza e usa a autenticação.

Configurar variáveis de ambiente para desenvolvimento local

Para se conectar ao Azure AI Search, seu código precisa conhecer seu ponto de extremidade de recurso.

Crie uma variável de ambiente nomeada AZURE_SEARCH_ENDPOINT para seu ponto de extremidade do Azure AI Search. Este URL geralmente tem o formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.

Cargas de trabalho de produção

Implantar cargas de trabalho de produção inclui estas etapas:

• Escolha funções RBAC que respeitem o princípio do menor privilégio.
• Atribua funções RBAC à sua identidade de produção no recurso específico.
• Configure variáveis de ambiente para seu recurso.

Funções para cargas de trabalho de produção

Para criar seus recursos de produção, você precisa criar uma identidade gerenciada atribuída ao usuário e, em seguida, atribuir essa identidade aos seus recursos com as funções corretas.

A seguinte função é sugerida para um aplicativo de produção:

Autenticação para cargas de trabalho de produção

Use o seguinte modelo do Azure AI Search Bicep para criar o recurso e definir a autenticação para o identityId. O bíceps requer o ID da função. O name mostrado neste trecho do Bicep não é a função do Azure, é específica para a implantação do Bicep.

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

O main.bicep arquivo chama o seguinte código Bicep genérico para criar qualquer função. Você tem a opção de criar várias funções RBAC, como uma para o usuário e outra para produção. Isso permite habilitar ambientes de desenvolvimento e produção dentro da mesma implantação do Bicep.

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

Configurar variáveis de ambiente para cargas de trabalho de produção

Para se conectar ao Azure AI Search, seu código precisa conhecer seu ponto de extremidade de recurso e a ID da identidade gerenciada.

Crie variáveis de ambiente para seu recurso de Pesquisa de IA do Azure implantado e sem chave:

• AZURE_SEARCH_ENDPOINT: Este URL é o ponto de acesso para o seu recurso Azure AI Search. Este URL geralmente tem o formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.
• AZURE_CLIENT_ID: Esta é a identidade para autenticar como.

Conteúdos relacionados

• Guia do desenvolvedor de conexões sem chave
• Funções incorporadas do Azure
• Definir variáveis de ambiente