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

1. Inicie sesión en Azure Portal.

2. Asigne estos roles:

   • Propietario (acceso total a todas las operaciones del plano de datos y del plano de control, excepto los permisos de consulta)
   • Colaborador (igual que propietario, excepto los permisos para asignar roles)
   • Lector (aceptable para la supervisión y visualización de métricas)

Al usar PowerShell para asignar roles, indique el nombre de usuario o grupo de Azure y el ámbito de la asignación para llamar a New-AzRoleAssignment.

En este ejemplo, se crea una asignación de roles con el ámbito de un servicio de búsqueda:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

1. Inicie sesión en Azure Portal.

2. Asigne estos roles:

   • Colaborador del servicio de búsqueda (operaciones de creación, lectura, actualización y eliminación en índices, indexadores, conjuntos de aptitudes y otros objetos de nivel superior)
   • Colaborador de datos de índice de búsqueda (carga de documentos y ejecución de trabajos de indexación)
   • Lector de datos de índice de búsqueda (consultar un índice)

Al usar PowerShell para asignar roles, indique el nombre de usuario o grupo de Azure y el ámbito de la asignación para llamar a New-AzRoleAssignment.

En este ejemplo, se crea una asignación de roles con el ámbito de un servicio de búsqueda:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

En este ejemplo, se crea una asignación de roles con el ámbito de un índice específico:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

1. Inicie sesión en Azure Portal.

2. Seleccione el rol Lector de datos de índice de búsqueda.

Al usar PowerShell para asignar roles, indique el nombre de usuario o grupo de Azure y el ámbito de la asignación para llamar a New-AzRoleAssignment.

1. Obtenga el identificador de suscripción, el grupo de recursos del servicio de búsqueda y el nombre del servicio de búsqueda.

2. Obtenga el identificador de objeto del servicio de Azure, como Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Obtenga la definición de roles y revise los permisos para asegurarse de que este es el rol que desea.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Cree la asignación de roles, sustituyendo los valores válidos para los marcadores de posición.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Este es un ejemplo de una asignación de roles cuyo ámbito es un índice específico:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

1. Inicie sesión en Azure Portal.

2. Vaya al servicio de búsqueda.

3. En la página Información general, seleccione la pestaña Índices:

   • Los colaboradores del servicio de búsqueda pueden ver y crear cualquier objeto, pero no pueden cargar documentos ni consultar índices. Para comprobar los permisos, cree un índice de búsqueda.

   • Los colaboradores de datos de índice de búsqueda pueden cargar documentos. No hay ninguna opción de carga de documentos en Azure Portal fuera del Asistente para la importación de datos, pero puede restablecer y ejecutar un indexador para confirmar los permisos de carga de documentos.

   • Los lectores de datos de índice de búsqueda pueden consultar el índice. Para comprobar los permisos, use el Explorador de búsqueda. Debería poder enviar consultas y ver los resultados, pero no debería poder ver la definición de índice ni crear uno.

En este enfoque se supone que Visual Studio Code tiene una extensión de cliente REST.

1. Abra un shell de comandos para la CLI de Azure e inicie sesión en su suscripción de Azure.

   az login
   

2. Obtenga el id. de inquilino y el id. de suscripción. Use el identificador como una variable en un paso futuro.

   az account show
   

3. Obtén un token de acceso.

   az account get-access-token --query accessToken --output tsv
   

4. Pegue estas variables en un nuevo archivo de texto de Visual Studio Code.

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Pegue y envíe una solicitud que use las variables que especifique. Para el rol "Lector de datos de índice de búsqueda", puede enviar una consulta. Puede usar cualquier versión de API compatible.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2025-09-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Para obtener más información sobre cómo adquirir un token para un entorno específico, consulte Administración de un servicio de Búsqueda de Azure AI con API de REST y bibliotecas de autenticación de la plataforma de identidad de Microsoft.

1. Use el paquete Azure.Search.Documents.

2. Use Azure.Identity para .NET para la autenticación de tokens. Microsoft recomienda DefaultAzureCredential() para la mayoría de los escenarios.

3. Este es un ejemplo de una conexión de cliente mediante DefaultAzureCredential():

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Este es otro ejemplo de uso de una credencial de secreto de cliente:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

1. Use azure.search.documents (Azure SDK para Python).

2. Use Azure.Identity para Python para la autenticación de tokens.

3. Use DefaultAzureCredential si el cliente de Python es una aplicación que se ejecuta en el lado servidor. Habilite la autenticación interactiva si la aplicación se ejecuta en un explorador.

4. Este es un ejemplo:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

1. Use la versión 11.3 de @azure/search-documents (Azure SDK para JavaScript).

2. Use Azure.Identity para JavaScript para la autenticación de tokens.

3. Si usa React, utilice InteractiveBrowserCredential para la autenticación de Microsoft Entra en Search. Consulte Cuándo usar @azure/identity para obtener más información.

1. Use azure-search-documents (Azure SDK para Java).

2. Use Azure.Identity para Java para la autenticación de tokens.

3. Use DefaultAzureCredential para las aplicaciones que se ejecutan en Azure.

Estos pasos se derivan del artículo Creación o actualización de roles personalizados de Azure mediante Azure Portal. Una página del servicio de búsqueda admite la clonación de un rol existente.

Estos pasos crean un rol personalizado que aumenta los derechos de consulta de búsqueda para incluir índices de enumeración por nombre. Normalmente, la enumeración de índices se considera una función de administrador.

1. En Azure Portal, vaya al servicio de búsqueda.

2. En el panel de navegación izquierdo, seleccione Access Control (IAM).

3. En la barra de acciones, seleccione Roles.

4. Haga clic con el botón derecho en Lector de datos de índice de búsqueda (u otro rol) y seleccione Clonar para abrir el Asistente para crear un rol personalizado.

5. En la pestaña Aspectos básicos, proporcione un nombre para el rol personalizado, como "Explorador de datos de índice de búsqueda" y, luego, seleccione Siguiente.

6. En la pestaña "Permisos", seleccione Agregar permiso.

7. En la pestaña "Agregar permisos", busque y seleccione el icono Búsqueda de Microsoft.

8. Establezca los permisos del rol personalizado. En la parte superior de la página, use la selección de acciones predeterminada:

   • En Microsoft.Search/operations, seleccione Leer: Enumerar todas las operaciones disponibles.
   • En Microsoft.Search/searchServices/indexes, seleccione Leer : Leer índice.

9. En la misma página, cambie a Acciones de datos y, en Microsoft.Search/searchServices/indexes/documents, seleccione Leer: Leer documentos.

   El código JSON resultante tendrá un aspecto similar al siguiente:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. Seleccione Revisar y crear para crear el rol. Ahora puede asignar usuarios y grupos al rol.

En el ejemplo de PowerShell se muestra la sintaxis JSON para crear un rol personalizado que es un clon del Lector de datos de índice de búsqueda, pero con la capacidad de enumerar todos los índices por nombre.

1. Revise la lista de permisos atómicos para determinar cuáles necesita. Para este ejemplo, necesita los siguientes permisos:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Configure una sesión de PowerShell para crear el rol personalizado. Para obtener instrucciones detalladas, consulte Azure PowerShell.

3. Proporcione la definición de roles como un documento JSON. El ejemplo siguiente muestra la sintaxis para crear un rol personalizado con PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

1. Revise la lista de permisos atómicos para determinar cuáles necesita.

2. Consulte Creación o actualización de roles personalizados de Azure con la API REST para obtener los pasos.

3. Copie o cree un rol, o use JSON para especificar el rol personalizado (consulte la pestaña PowerShell para ver la sintaxis JSON).

1. Revise la lista de permisos atómicos para determinar cuáles necesita.

2. Consulte Creación o actualización de roles personalizados de Azure con la CLI de Azure para obtener los pasos.

3. Consulte la pestaña de PowerShell para ver la sintaxis JSON.