Conexión a Búsqueda de Azure AI mediante claves

Azure AI Search admite la autenticación basada en identidades y basada en claves para las conexiones con el servicio de búsqueda. Una clave de API es una cadena única compuesta de 52 números y letras generados aleatoriamente.

En el código fuente, puede especificar directamente la clave de API en un encabezado de solicitud. Como alternativa, puede almacenarlo como una variable de entorno o una configuración de aplicación en el proyecto y, a continuación, hacer referencia a la variable en la solicitud.

Importante

Al crear un servicio de búsqueda, la autenticación basada en claves es la predeterminada, pero no es la opción más segura. Se recomienda reemplazarlo por el acceso basado en roles.

Habilitado de forma predeterminada

La autenticación basada en claves es el valor predeterminado para los nuevos servicios de búsqueda. Se acepta una solicitud realizada a un punto de conexión de servicio de búsqueda si la solicitud y la clave de API son válidas y si el servicio de búsqueda está configurado para permitir claves de API en una solicitud.

En Azure Portal, especifique la autenticación en la página Claves de configuración>. Las claves de API o Ambas proporcionan compatibilidad con claves.

Tipos de claves

Hay dos tipos de claves que se usan para autenticar una solicitud:

Tipo	Nivel del permiso	Cómo se crea	Máxima
Administrador	Acceso completo (lectura y escritura) para todas las operaciones de contenido	Dos claves de administración, conocidas como claves principal y secundaria en Azure Portal, se generan cuando se crea el servicio y pueden volver a generarse individualmente a petición.	2 ¹
Consulta	Acceso de solo lectura, con ámbito a la colección de documentos de un índice de búsqueda	Se genera una clave de consulta con el servicio. Un administrador de servicios de búsqueda puede crear más a petición.	50

¹ Tener dos le permite la rotación de una clave mientras se usa la segunda clave para un acceso continuado al servicio.

Visualmente, no hay distinción entre las claves de administración y de consulta. Ambas claves son cadenas formadas por 52 caracteres alfanuméricos generados aleatoriamente. Si necesita saber qué tipo de clave se especifica en la aplicación, puede comprobar los valores de las claves en Azure Portal.

Mapeo de clave a rol

Este artículo trata sobre las claves de API. Sin embargo, si desea realizar la transición al acceso basado en roles, resulta útil comprender cómo se asignan las claves a roles integrados en Azure AI Search:

Una clave de administrador corresponde a los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda .
Una clave de consulta corresponde al rol Lector de datos de índice de búsqueda .

Permisos para ver o administrar claves

Los permisos para ver y administrar claves de API se transmiten a través de asignaciones de roles. Los miembros de los roles siguientes pueden ver y regenerar las claves:

Propietario
Colaborador
Colaborador del servicio Search
Administrador y coadministrador (clásico)

Los siguientes roles no tienen acceso a las claves de API:

Lector
Colaborador de datos de índice de búsqueda
Lector de datos de índice de búsqueda

Encontrar las claves existentes

Puede ver y administrar claves de API mediante Azure Portal, PowerShell, la CLI de Azure o la API REST.

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En el panel izquierdo, seleccione Claves de configuración> para ver las claves de administrador y consulta.

Instalación del módulo Az.Search:
```
Install-Module Az.Search
```

Devolver claves de administrador:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Devolver claves de consulta:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Use los siguientes comandos para devolver claves de API de administración y consulta, respectivamente:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Use Enumerar claves de administrador o Enumerar claves de consulta en la API de REST de administración para devolver claves de API.

Debe tener una asignación de roles válida para devolver o actualizar las claves de API. Consulte Administración del servicio Azure AI Search con las API de REST para obtener instrucciones sobre cómo cumplir los requisitos de rol mediante las API de REST.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01

Uso de claves en conexiones

Las claves de API se usan para las solicitudes del plano de datos (contenido), como crear o acceder a un índice o a cualquier otra solicitud representada en las API REST del servicio de búsqueda.

Puede usar una clave de API o roles para las solicitudes del plano de control (servicio). Cuando se usa una clave de API:

Las claves de administrador se usan para crear, modificar o eliminar objetos. Las claves de administrador también se usan para obtener definiciones de objetos e información del sistema, como índices LIST o GET Service Statistics.
Las claves de consulta se distribuyen normalmente a las aplicaciones cliente que emiten consultas.

Establezca una clave de administrador en el encabezado de solicitud. No puede pasar claves de administrador en el URI o en el cuerpo de la solicitud.

Este es un ejemplo de uso de clave de API de administración en una solicitud de creación de índice:

@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

Establezca una clave de consulta en un encabezado de solicitud para POST o en el URI para GET. Las claves de consulta se usan para las operaciones destinadas a la colección de index/docs: Buscar documentos, Autocompletar, Sugerir o GET Document.

Este es un ejemplo de uso de la clave de API de consulta en una solicitud de documentos de búsqueda (GET):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2025-09-01&api-key={{queryApiKey}}

Nota:

Se considera una práctica poco segura pasar datos confidenciales, como una api-key en el identificador URI de la solicitud. Por este motivo, Azure AI Search solo acepta una clave de consulta como un api-key en la cadena de consulta. Como regla general, se recomienda pasar la api-key como un encabezado de solicitud.

Se recomienda establecer la clave de API como una variable de entorno, pero por motivos de simplicidad, en este ejemplo se muestra como una cadena. En el ejemplo se usa una clave de API de consulta para una operación de consulta.

# Import libraries
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

Establezca las claves de API en el encabezado de solicitud mediante la siguiente sintaxis:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Use una variable para contener la consulta completamente calificada.

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2025-09-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

Envíe la solicitud al servicio de búsqueda:

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Puede encontrar más ejemplos de script para otras operaciones en Inicio rápido: Creación de un índice de Azure AI Search en PowerShell mediante las API REST.

Creación de claves de consulta

Las claves de consulta se usan para el acceso de solo lectura a los documentos dentro de un índice para las operaciones destinadas a una colección de documentos. Las consultas de búsqueda, filtro y sugerencias son todas las operaciones que toman una clave de consulta. Cualquier operación de solo lectura que devuelve definiciones de objetos o datos del sistema, como una definición del índice o el estado del indexador, requiere una clave de administración.

Restringir el acceso y las operaciones en las aplicaciones cliente es esencial para proteger los activos de búsqueda en el servicio. Use siempre una clave de consulta en lugar de una clave de administración para cualquier consulta originada desde una aplicación cliente.

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En el panel izquierdo, seleccione Claves de configuración> para ver las claves de API.
En Administrar claves de consulta, use la clave de consulta ya generada para el servicio o cree nuevas claves de consulta. La clave de consulta predeterminada no se denomina, pero se pueden denominar otras generadas para la capacidad de administración.

Use Crear claves de consulta en la API de REST de administración.

Debe tener una asignación de roles válida para crear o administrar claves de API. Consulte Administración del servicio Azure AI Search con las API de REST para obtener instrucciones sobre cómo cumplir los requisitos de rol mediante las API de REST.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2025-05-01

Regeneración de claves de administración

Se crean dos claves de administración para cada servicio para que pueda rotar una clave principal mientras usa la clave secundaria para la continuidad empresarial.

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En el panel izquierdo, seleccione Configuración>Claves.
Copie la clave secundaria.
Para todas las aplicaciones, actualice la configuración de la clave de API para usar la clave secundaria.
Regenere la clave principal
Actualice todas las aplicaciones para usar la nueva clave principal.

Si regenera las claves al mismo tiempo sin querer, se producirá un error HTTP 403 Prohibido en todas las solicitudes de cliente que usen esas claves. Sin embargo, el contenido no se elimina ni se bloquea permanentemente.

Puede seguir accediendo al servicio a través de Azure Portal o mediante programación. Las funciones de administración están operativas a través de un identificador de suscripción que no es una clave de API de servicio y, por tanto, siguen estando disponibles aunque las claves de API no lo estén.

Después de crear nuevas claves a través del portal o del nivel de administración, el acceso se restaura al contenido (índices, indexadores, orígenes de datos, mapas de sinónimos) una vez que proporcione esas claves en las solicitudes.

Claves seguras

Use asignaciones de roles para restringir el acceso a las claves de API.

No es posible usar el cifrado de claves administradas por el cliente para cifrar las claves de API. Solo los datos confidenciales dentro del propio servicio de búsqueda (por ejemplo, el contenido del índice o las cadenas de conexión en las definiciones de objetos de origen de datos) pueden cifrarse con CMK.

Inicie sesión en Azure Portal y busque su servicio de búsqueda.
En el panel izquierdo, seleccione Control de acceso (IAM) y, a continuación, seleccione la pestaña Asignaciones de roles.
En el filtro Rol, seleccione los roles que tienen permiso para ver o administrar claves (Propietario, Colaborador, Colaborador del servicio de búsqueda). Las entidades de seguridad resultantes asignadas a esos roles tienen permisos clave en el servicio de búsqueda.
Como medida de precaución, compruebe también la pestaña Administradores clásicos para determinar si los administradores y coadministradores tienen acceso.

Procedimientos recomendados

En el caso de las cargas de trabajo de producción, cambie a Microsoft Entra ID y acceso basado en rol. Como alternativa, si desea seguir usando claves de API, asegúrese de supervisar siempre quién tiene acceso a las claves de API y volver a generar claves de API con una cadencia regular.
Use solo las claves de API si la divulgación de datos no es un riesgo (por ejemplo, al usar datos de ejemplo) y si está trabajando detrás de un firewall. La exposición de claves de API pone los datos y el servicio de búsqueda en riesgo de uso no autorizado.
Si usa una clave de API, almacénela de forma segura en otro lugar, como en Azure Key Vault. No incluya la clave de API directamente en el código ni la exponga nunca públicamente.
Compruebe siempre el código, los ejemplos y el material de entrenamiento antes de publicar para asegurarse de que no exponga accidentalmente una clave de API.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2025-12-02