Inicio rápido: Conexión a un servicio de búsqueda

En este inicio rápido, usará el control de acceso basado en rol (RBAC) y el identificador de Microsoft Entra para establecer una conexión sin clave con el servicio Azure AI Search. Después, use Python en Visual Studio Code para interactuar con el servicio.

Las conexiones sin claves proporcionan seguridad mejorada mediante permisos granulares y autenticación basada en identidades. No se recomiendan claves de API codificadas de forma rígida, pero si lo prefiere, consulte Conexión a Azure AI Search mediante claves.

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.

• La CLI de Azure para la autenticación sin clave con Microsoft Entra ID.

• Visual Studio Code con la extensión de Python y el paquete de Jupyter.

Configuración del acceso basado en roles

En esta sección, habilitará RBAC en el servicio Azure AI Search y asignará los roles necesarios para crear, cargar y consultar objetos de búsqueda. Para más información sobre estos pasos, consulte Conexión a Azure AI Search mediante roles.

Para configurar el acceso:

1. Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.

2. En el panel izquierdo, seleccione Claves de configuración>.

3. Seleccione Control de acceso basado en roles o Ambos si necesita tiempo para realizar la transición de clientes a RBAC.

   

4. En el panel izquierdo, seleccione Control de acceso (IAM) .

5. Seleccione Agregar>Agregar asignación de rol.

   

6. Asigne el rol Colaborador del servicio de búsqueda a su cuenta de usuario o identidad administrada.

7. Repita la asignación de roles para Colaborador de datos de índice de búsqueda.

Obtención de información del servicio

En esta sección, recuperará el identificador de suscripción y el punto de conexión del servicio Azure AI Search. Si solo tiene una suscripción, omita el identificador de suscripción y recupere solo el punto de conexión. Estos valores se usan en las secciones restantes de este inicio rápido.

Para obtener la información del servicio:

1. Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.

2. En el panel izquierdo, seleccione Información general.

3. Anote el identificador y el punto de conexión de la suscripción.

   

Inicio de sesión en Azure

Antes de conectarse al servicio Azure AI Search, use la CLI de Azure para iniciar sesión en la suscripción que contiene el servicio. Este paso establece la identidad de Microsoft Entra, que DefaultAzureCredential usa para autenticar solicitudes en la sección siguiente.

Para iniciar sesión:

1. En el sistema local, abra una herramienta de línea de comandos.

2. Compruebe la suscripción activa y el inquilino en el entorno local.

   az account show
   

3. Si la suscripción activa y el inquilino no son válidos para el servicio de búsqueda, ejecute los siguientes comandos para actualizar sus valores. Puede encontrar el identificador de suscripción en la página información general del servicio de búsqueda en Azure Portal. Para buscar el identificador de inquilino, seleccione el nombre de la suscripción en la página Información general y, a continuación, busque el valor del grupo de administración primario .

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

Conectar a Azure AI Search

Puede usar cuadernos de Python en Visual Studio Code para enviar solicitudes al servicio Azure AI Search. Para la autenticación de solicitud, use la DefaultAzureCredential clase de la biblioteca de identidades de Azure.

Para conectarse mediante Python:

1. En el sistema local, abra Visual Studio Code.

2. Cree un archivo .ipynb.

3. Cree una celda de código para instalar las bibliotecas azure-identity y azure-search-documents.

   pip install azure-identity azure-search-documents
   

4. Cree otra celda de código para autenticarse y conectarse al servicio de búsqueda.

   from azure.identity import DefaultAzureCredential
   from azure.search.documents.indexes import SearchIndexClient
   
   service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
   credential = DefaultAzureCredential()
   client = SearchIndexClient(endpoint = service_endpoint, credential = credential)
   
   # List existing indexes
   indexes = client.list_indexes()
   
   for index in indexes:
      index_dict = index.as_dict()
      print(json.dumps(index_dict, indent = 2))
   

5. Establezca service_endpoint en el valor que obtuvo en Obtener información del servicio.

6. Seleccione Ejecutar todo para ejecutar ambas celdas de código.

   La salida debe enumerar los índices existentes (si los hay) en el servicio de búsqueda, lo que indica una conexión correcta.

Solución de errores 401

Si se produce un error 401, siga estos pasos de solución de problemas:

• Vuelva a consultar Configuración del acceso basado en rol. El servicio de búsqueda debe tener el control de acceso basado en rol o Ambos habilitados. Las directivas en el nivel de suscripción o grupo de recursos pueden invalidar las asignaciones de roles.

• Regrese a Iniciar sesión en Azure. Debe iniciar sesión en la suscripción que contiene el servicio de búsqueda.

• Asegúrese de que la variable de punto de conexión esté entre comillas.

• Si se produce un error en todo lo demás, reinicie el dispositivo para quitar tokens almacenados en caché y, a continuación, repita los pasos de este inicio rápido, empezando por Iniciar sesión en Azure.

En este inicio rápido, usará el control de acceso basado en rol (RBAC) y el identificador de Microsoft Entra para establecer una conexión sin clave con el servicio Azure AI Search. Después, use REST en Visual Studio Code para interactuar con el servicio.

Las conexiones sin claves proporcionan seguridad mejorada mediante permisos granulares y autenticación basada en identidades. No se recomiendan claves de API codificadas de forma rígida, pero si lo prefiere, consulte Conexión a Azure AI Search mediante claves.

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.

• La CLI de Azure para la autenticación sin clave con Microsoft Entra ID.

• Visual Studio Code con la extensión de cliente REST.

Configuración del acceso basado en roles

En esta sección, habilitará RBAC en el servicio Azure AI Search y asignará los roles necesarios para crear, cargar y consultar objetos de búsqueda. Para más información sobre estos pasos, consulte Conexión a Azure AI Search mediante roles.

Para configurar el acceso:

1. Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.

2. En el panel izquierdo, seleccione Claves de configuración>.

3. Seleccione Control de acceso basado en roles o Ambos si necesita tiempo para realizar la transición de clientes a RBAC.

   

4. En el panel izquierdo, seleccione Control de acceso (IAM) .

5. Seleccione Agregar>Agregar asignación de rol.

   

6. Asigne el rol Colaborador del servicio de búsqueda a su cuenta de usuario o identidad administrada.

7. Repita la asignación de roles para Colaborador de datos de índice de búsqueda.

Obtención de información del servicio

En esta sección, recuperará el identificador de suscripción y el punto de conexión del servicio Azure AI Search. Si solo tiene una suscripción, omita el identificador de suscripción y recupere solo el punto de conexión. Estos valores se usan en las secciones restantes de este inicio rápido.

Para obtener la información del servicio:

1. Inicie sesión en Azure Portal y seleccione el servicio de búsqueda.

2. En el panel izquierdo, seleccione Información general.

3. Anote el identificador y el punto de conexión de la suscripción.

   

Inicio de sesión en Azure

Antes de conectarse al servicio Azure AI Search, use la CLI de Azure para iniciar sesión en la suscripción que contiene el servicio.

Para iniciar sesión:

1. En el sistema local, abra una herramienta de línea de comandos.

2. Compruebe la suscripción activa y el tenant en su entorno local.

   az account show
   

3. Si la suscripción activa y el inquilino no son válidos para el servicio de búsqueda, ejecute los siguientes comandos para actualizar sus valores. Puede encontrar el identificador de suscripción en la página información general del servicio de búsqueda en Azure Portal. Para buscar el identificador de inquilino, seleccione el nombre de la suscripción en la página Información general y, a continuación, busque el valor del grupo de administración primario .

    az account set --subscription <your-subscription-id>
   
    az login --tenant <your-tenant-id>
   

Obtener el token

Las llamadas a la API REST requieren la inclusión de un token de ID de Microsoft Entra. Este token se usa para autenticar las solicitudes en la sección siguiente.

Para obtener el token:

1. Con la misma herramienta de línea de comandos, genere un token de acceso.

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

2. Anote la salida del token.

Conectar a Azure AI Search

Puede usar la extensión de cliente REST en Visual Studio Code para enviar solicitudes al servicio Azure AI Search. Para la autenticación de solicitudes, incluya un encabezado Authorization con el token de Microsoft Entra ID que generó anteriormente.

Para conectarse mediante REST:

1. En el sistema local, abra Visual Studio Code.

2. Cree un archivo .rest o .http.

3. Pegue las siguientes variables y agregue la solicitud en el archivo.

   @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
   @token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE
   
   ### List existing indexes
   GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
      Content-Type: application/json
      Authorization: Bearer {{token}}
   

4. Establezca @baseUrl en el valor que obtuvo en Obtener información del servicio.

5. Establezca @token en el valor que obtuvo en Obtener token.

6. En ### List existing indexes, seleccione Enviar solicitud.

   Debe recibir la HTTP/1.1 200 OK respuesta, lo que indica una conexión exitosa al servicio de búsqueda.

Solución de errores 401

Si se produce un error 401, siga estos pasos de solución de problemas:

• Vuelva a consultar Configuración del acceso basado en rol. El servicio de búsqueda debe tener el control de acceso basado en rol o Ambos habilitados. Las directivas en el nivel de suscripción o grupo de recursos pueden invalidar las asignaciones de roles.

• Regrese a Iniciar sesión en Azure. Debe iniciar sesión en la suscripción que contiene el servicio de búsqueda.

• Asegúrese de que las variables de punto de conexión y token no tienen comillas circundantes ni espacios adicionales.

• Asegúrese de que el token no tiene el @ símbolo en el encabezado de solicitud. Por ejemplo, si la variable es @token, la referencia de la solicitud debe ser {{token}}.

• Si se produce un error en todo lo demás, reinicie el dispositivo para quitar tokens almacenados en caché y, a continuación, repita los pasos de este inicio rápido, empezando por Iniciar sesión en Azure.