Inicio rápido: conexión sin claves

2025-07-03

En esta guía rápida, configurará Azure AI Search para usar la autenticación de Microsoft Entra ID y el control de acceso basado en roles (RBAC) para conectarse desde tu sistema local sin necesidad de claves de API. Después, use cuadernos de Jupyter Notebook o un cliente REST para interactuar con el servicio de búsqueda.

Si completó otros inicios rápidos que se conectan mediante claves de API, en este inicio rápido se muestra cómo cambiar a la autenticación basada en identidades para evitar claves codificadas de forma rígida en el código de ejemplo.

Requisitos previos

Una cuenta de Azure con una suscripción activa. Cree una cuenta gratuita.
Un servicio Azure AI Search en cualquier región o nivel. Sin embargo, para configurar una identidad administrada para Azure AI Search, necesita el nivel Básico o superior.
Una herramienta de línea de comandos, como PowerShell o Bash, y la CLI de Azure.

Paso 1: Obtención de los identificadores de inquilino y suscripción de Azure

Necesita este paso si tiene más de una suscripción o inquilino.

Obtenga la suscripción y el inquilino de Azure para el servicio de búsqueda:
1. Inicie sesión en Azure Portal y vaya al servicio de búsqueda.
2. Observe el nombre y el id. de la suscripción en Información general>Essentials.
3. Ahora seleccione el nombre de la suscripción para ver el grupo de administración principal (id. de inquilino) en la página siguiente.
Ahora sabe bajo qué suscripción y inquilino está la Búsqueda de Azure AI. Cambie al dispositivo local y un símbolo del sistema e identifique la suscripción y el inquilino de Azure activos en el dispositivo:
```
az account show
```
Si la suscripción y el inquilino activos difieren de la información obtenida en el paso anterior, cambie el identificador de suscripción. A continuación, inicie sesión en Azure con el identificador de inquilino que encontró en el paso anterior:
```
 az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>
```

Paso 2: Configuración de la Búsqueda de Azure AI para RBAC

Inicie sesión en Azure Portal y vaya al servicio Búsqueda de Azure AI.
Habilitar el control de acceso basado en roles (RBAC):
1. Vaya a Configuración>Claves.
2. Elija Control basado en roles o Ambos si necesita tiempo para realizar la transición de los clientes al control de acceso basado en roles.
  
  Si elige Control basado en roles, asegúrese de asignarse a sí mismo todos los roles designados en la siguiente instrucción o no podrá completar tareas en Azure Portal o a través de un cliente local.
Asignar roles en Azure Portal:
1. Vaya al servicio de búsqueda.
2. Seleccione Control de acceso (IAM) en el panel izquierdo.
3. Seleccione Agregar>Agregar asignación de roles.
4. Elija un rol (Colaborador del servicio de búsqueda, Colaborador de datos de índice de búsqueda, Lector de datos de índice de búsqueda) y asígnelo a su identidad de grupo o usuario de Microsoft Entra.
  
  Repita el procedimiento para cada rol.
  
  Necesita los roles de Colaborador del servicio de búsqueda y Colaborador de datos de índice de búsqueda para crear, cargar y consultar objetos en la Búsqueda de Azure AI. Para obtener más información, consulte Conexión mediante roles.

Sugerencia

Más adelante, si recibe errores de autenticación, vuelva a comprobar la configuración de esta sección. Es posible que haya directivas en el nivel de suscripción o grupo de recursos que invaliden cualquier configuración de API que especifique.

Paso 3: Conexión desde el sistema local

Si aún no ha iniciado sesión en Azure:

az login

Usar Python y cuadernos de Jupyter

Instale las bibliotecas de Azure Identity y Azure Search:
```
pip install azure-identity azure-search-documents
```

Autenticación y conexión a Búsqueda de Azure AI:

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

Usar un cliente REST

Varios inicios rápidos y tutoriales usan un cliente REST, como Visual Studio Code con la extensión REST. Aquí se muestra cómo conectarse a Búsqueda de Azure AI desde Visual Studio Code.

Debe tener un archivo .rest o .http similar al descrito en Inicio rápido: Búsqueda de vectores.

Generar un token de acceso.

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

En la parte superior del archivo, establezca variables usadas para la conexión, pegando el punto de conexión de servicio de búsqueda completo y el token de acceso que obtuvo en el paso anterior. Las variables deben tener un aspecto similar al del siguiente ejemplo. Observe que los valores no están entre comillas.
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

Especifique el token de portador de autorización en una llamada REST:

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

Solución de errores 401

Compruebe la suscripción activa y el inquilino (az account show) y asegúrese de que es válido para el servicio de búsqueda.
Compruebe las opciones del servicio de búsqueda en Configuración>Claves en Azure Portal y confirme que el servicio está configurado para "Ambos" o Control de acceso basado en rol.
Solo para el cliente REST: compruebe el token y el punto de conexión especificados en el archivo y asegúrese de que no haya comillas circundantes ni espacios adicionales. Se produce un mensaje de token 401 no válido si el token del encabezado de solicitud incluye el @ símbolo. Por ejemplo, si la variable es @token, la referencia en la solicitud es simplemente {{token}}.

Si todo lo demás no funciona, reinicie el dispositivo para quitar los tokens almacenados en caché y, a continuación, repita los pasos de esta sección, empezando por az login.

Configuración adicional

Configure una identidad administrada para las conexiones salientes:

Configurar una identidad administrada asignada por el sistema o asignada por el usuario para el servicio de búsqueda.
Usar asignaciones de roles para autorizar el acceso a otros recursos de Azure.

Configurar acceso a la red:

Establecer reglas de entrada para aceptar o rechazar solicitudes en Búsqueda de Azure AI en función de la dirección IP.