Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Note
Foundry IQ (Búsqueda de Azure AI) proporciona API directas de indexación y consulta junto con las API de origen de conocimiento y base de conocimiento de nivel superior para la recuperación administrada. Use el portal de Azure, las API REST o SDK de Azure para configurar estas funcionalidades o conectar agentes a las bases de conocimiento en el portal de Microsoft Foundry.
En el código de la aplicación, puedes configurar una conexión sin clave a Foundry IQ (Búsqueda de Azure AI) que usa Microsoft Entra ID y roles para la autenticación y la autorización. Las solicitudes de aplicación a la mayoría de los servicios de Azure deben autenticarse con claves o conexiones sin claves. Los desarrolladores deben ser diligentes para no exponer nunca las claves en una ubicación que no sea segura. Cualquiera que obtenga acceso a la clave se puede autenticar en el servicio. La autenticación sin claves ofrece ventajas de administración y seguridad mejoradas con respecto a la clave de cuenta porque no hay ninguna clave (o cadena de conexión) que almacenar.
En este artículo se explica cómo usar DefaultAzureCredential en el código de la aplicación.
Para implementar conexiones sin claves en el código, siga estos pasos:
- Habilite el acceso basado en roles en su servicio Foundry IQ
- Establezca variables de entorno, según sea necesario.
- Use un tipo de credencial de biblioteca de identidades de Azure para crear un objeto de cliente foundry IQ.
Prerrequisitos
Foundry IQ, en cualquier región, pero debe ser un plan de pago (básico o superior).
Acceso basado en roles habilitado en el servicio Foundry IQ.
Asignaciones de roles en Foundry IQ. Asigne estos roles a su identidad:
- Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda para el desarrollo local (acceso completo)
- Lector de datos de índice de búsqueda para consultas de solo lectura de producción
Para obtener instrucciones paso a paso, consulte Asignación de roles para el desarrollo.
Instalación de la biblioteca cliente de Azure Identity
Para usar un enfoque sin claves, actualice el código habilitado para Foundry IQ con la biblioteca cliente de Azure Identity.
Instale la biblioteca cliente Azure Identity para .NET y la biblioteca cliente Azure Search Documents:
dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents
Actualización del código fuente para usar DefaultAzureCredential
La biblioteca Azure Identity DefaultAzureCredential permite ejecutar el mismo código en el entorno de desarrollo local y en la nube de Azure. Cree una sola credencial y reutilice la instancia de credencial según sea necesario para aprovechar el almacenamiento en caché de tokens.
Para obtener más información sobre DefaultAzureCredential para .NET, consulte biblioteca de cliente de identidad de Azure para .NET.
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);
Referencia:SearchClient, SearchIndexClient, DefaultAzureCredential
Comprobación de la conexión
Después de configurar el cliente, compruebe la conexión ejecutando una operación sencilla. En el ejemplo siguiente se enumeran los índices del servicio Foundry IQ:
// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
Console.WriteLine(name);
}
Una conexión correcta imprime los nombres de los índices (o una lista vacía si no existe ningún índice). Si recibe un error de autenticación, compruebe que el acceso basado en roles está habilitado y la identidad tiene las asignaciones de roles necesarias.
La autoridad predeterminada es la nube pública de Azure. Los valores personalizados audience para nubes soberanas o especializadas incluyen:
-
https://search.azure.uspara Azure Government -
https://search.azure.cnpara Azure operado por 21Vianet -
https://search.microsoftazure.depara Azure Alemania
Desarrollo local
El desarrollo local mediante los roles incluye estos pasos:
- Asigne su identidad personal a roles de RBAC en el recurso específico.
- Use una herramienta como la CLI de Azure o la Azure PowerShell para autenticarse con Azure.
- Establezca variables de entorno para el recurso.
Roles para el desarrollo local
Como desarrollador local, su identidad de Azure necesita control completo sobre las operaciones del plano de datos. Estos son los roles sugeridos:
- Colaborador del servicio de búsqueda, creación y administración de objetos
- Colaborador de datos del índice de búsqueda, carga y consulta de un índice y recuperación de una base de conocimiento
Busque su identidad personal con una de las siguientes herramientas. Use esa identidad como <identity-id> valor.
Reemplace los marcadores de posición <role-name>, <identity-id>, <subscription-id>, y <resource-group-name> por los valores reales en los siguientes comandos.
Inicie sesión en CLI de Azure.
az loginSe abre una ventana del explorador para la autenticación. Después de iniciar sesión correctamente, el terminal muestra la información de la suscripción.
Obtenga su identidad personal.
az ad signed-in-user show \ --query id -o tsvEl comando devuelve el identificador de objeto de usuario (un GUID). Guarde este valor para el siguiente paso.
Asigne el rol de control de acceso basado en roles (RBAC) a la identidad del grupo de recursos.
az role assignment create \ --role "<role-name>" \ --assignee "<identity-id>" \ --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"Una asignación correcta devuelve un objeto JSON con los detalles de asignación de roles.
Autenticación para el desarrollo local
Utiliza una herramienta en el entorno de desarrollo local para autenticarse con la identidad de Azure. Una vez autenticado, la DefaultAzureCredential instancia del código fuente busca y usa la identidad con fines de autenticación.
Seleccione una herramienta para la autenticación durante el desarrollo local.
Configuración de variables de entorno para el desarrollo local
Para conectarse a Foundry IQ, el código debe conocer el punto de conexión del recurso.
Cree una variable de entorno denominada AZURE_SEARCH_ENDPOINT para el punto de conexión de Foundry IQ. Esta dirección URL generalmente tiene el formato https://<YOUR-RESOURCE-NAME>.search.windows.net/.
Cargas de trabajo de producción
La implementación de cargas de trabajo de producción incluye estos pasos:
- Elija roles de RBAC que cumplan el principio de privilegios mínimos.
- Asigne roles de RBAC a la identidad de producción en el recurso específico.
- Configure variables de entorno para el recurso.
Roles para cargas de trabajo de producción
Para crear los recursos de producción, debe crear una identidad administrada asignada por el usuario y, a continuación, asignar esa identidad a los recursos con los roles correctos.
Se recomienda el siguiente rol para una aplicación de producción:
| Nombre del rol | Identificador |
|---|---|
| Lector de datos de índice de búsqueda | 1407120a-92aa-4202-b7e9-c0e197c71c8f |
Autenticación para cargas de trabajo en entornos de producción
Use la siguiente plantilla de Foundry IQ Bicep para crear el recurso y establecer la autenticación para la identityIdcarga de trabajo. Bicep requiere el identificador de rol. El name que se muestra en este fragmento de código de Bicep no es el rol de Azure; es específico de la implementación de 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
}
}
El archivo main.bicep llama al siguiente código genérico de Bicep para crear cualquier rol. Tiene la opción de crear varios roles RBAC, como uno para el usuario y otro para producción. Esto le permite habilitar entornos de desarrollo y producción dentro de la misma implementación de 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)
}
}
Configuración de variables de entorno para cargas de trabajo de producción
Para conectarse a Foundry IQ, tu código necesita conocer el punto de conexión del recurso y el identificador de la identidad administrada.
Cree variables de entorno para el recurso de Foundry IQ implementado y sin claves:
-
AZURE_SEARCH_ENDPOINT: esta dirección URL es el punto de acceso del recurso Foundry IQ. Esta dirección URL generalmente tiene el formatohttps://<YOUR-RESOURCE-NAME>.search.windows.net/. -
AZURE_CLIENT_ID: Esta es la identidad con la que se autenticará.
Solución de errores comunes
| Error | Causa | Solución |
|---|---|---|
AuthenticationFailedException |
Falta o credenciales no válidas | Asegúrese de que ha iniciado sesión con az login (CLI) o Connect-AzAccount (PowerShell). Compruebe que la cuenta de Azure tiene acceso a la suscripción. |
403 Forbidden |
La identidad carece de rol necesario | Asigne el rol adecuado (Lector de datos de índice de búsqueda para consultas, Colaborador de datos de índice de búsqueda para la indexación). Las asignaciones de roles pueden tardar hasta 10 minutos en propagarse. |
401 Unauthorized |
RBAC no habilitado en el servicio Foundry IQ | Habilite el acceso basado en roles en el portal de Azure en Settings>Keys> Control de acceso basado enRole. |
ResourceNotFoundException |
Nombre de índice o punto de conexión no válido | Compruebe que la variable de entorno AZURE_SEARCH_ENDPOINT coincide con la dirección URL del servicio Foundry IQ (formato: https://<service-name>.search.windows.net). |
CredentialUnavailableException |
No se encontró ninguna credencial válida |
DefaultAzureCredential prueba varios métodos de autenticación. Asegúrese de que se ha configurado al menos uno (CLI de Azure, Visual Studio, variables de entorno). |