Conexión a Azure Cosmos DB mediante una identidad administrada (Búsqueda de Azure AI)

Nota

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

En este artículo se explica cómo configurar una conexión de indexador a una base de datos de Azure Cosmos DB mediante una identidad administrada en lugar de proporcionar credenciales en el cadena de conexión.

Puede usar una identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario. Las identidades administradas son inicios de sesión de Microsoft Entra y requieren asignaciones de roles de Azure para acceder a los datos de Azure Cosmos DB. Opcionalmente, puede imponer el acceso basado en roles como el único método de autenticación para las conexiones de datos estableciendo disableLocalAuth en true para su cuenta de Azure Cosmos DB para NoSQL.

Requisitos previos

Limitaciones

  • Los indexadores que se conectan a Azure Cosmos DB para Gremlin y MongoDB (actualmente en versión preliminar) solo admiten el enfoque legacy.

Enfoques admitidos para la autenticación de identidad administrada

Búsqueda de Azure AI admite dos mecanismos para conectarse a Azure Cosmos DB mediante la identidad administrada.

  • El enfoque heredado requiere configurar la identidad administrada para tener permisos de lector en el plano de control de la cuenta de Azure Cosmos DB de destino. Búsqueda de Azure AI utiliza esa identidad para capturar las claves de cuenta de la cuenta de Cosmos DB en segundo plano para acceder a los datos. Este enfoque no funcionará si la cuenta de Cosmos DB tiene "disableLocalAuth": true.

  • El enfoque moderno requiere configurar los roles adecuados de identidad administrada en el plano de control y datos de la cuenta de Azure Cosmos DB de destino. Búsqueda de Azure AI solicitará un token de acceso para acceder a los datos de la cuenta de Cosmos DB. Este enfoque funciona incluso si la cuenta de Cosmos DB tiene "disableLocalAuth": true.

Los indexadores que se conectan a Azure Cosmos DB para NoSQL admiten tanto el enfoque legacy y el enfoque modern: el enfoque modern se recomienda.

Conexión a Azure Cosmos DB para NoSQL

En esta sección se describen los pasos para configurar la conexión a Azure Cosmos DB para NoSQL a través del enfoque modern.

Configurar asignaciones de roles del plano de control

  1. Inicie sesión en Azure portal y busque la cuenta de Cosmos DB para NoSQL.

  2. Seleccione Control de acceso (IAM) .

  3. Seleccione Agregar y, a continuación, seleccione Asignación de roles.

  4. En la lista de roles de trabajo, seleccione Lector de cuentas de Cosmos DB.

  5. Seleccione Siguiente.

  6. Seleccione Identidad administrada y, a continuación, seleccione Miembros.

  7. Filtre por identidades administradas asignadas por el sistema o identidades administradas asignadas por el usuario. Debería ver la identidad administrada que creó anteriormente para el servicio de búsqueda. Si no tiene una, consulte Configuración de la búsqueda para usar una identidad administrada. Si ya ha configurado uno pero no está disponible, déle unos minutos.

  8. Seleccione la identidad y guarde la asignación de roles.

Para obtener más información, consulte Uso del control de acceso basado en roles del plano de control con Azure Cosmos DB for NoSQL.

Configuración de asignaciones de roles del plano de datos

La identidad administrada debe tener un rol asignado para poder acceder al plano de datos de la cuenta de Cosmos DB. El identificador de objeto (principal) de la identidad asignada por el sistema o el usuario del servicio de búsqueda se puede encontrar en la pestaña "Identidad" del servicio de búsqueda. Este paso solo se puede realizar a través de CLI de Azure actualmente.

Establecer variables:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription ID>
$system_assigned_principal = <Object (principal) ID for the search service's system/user assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdb_acc_name --resource-group $resource_group --query id --output tsv)

Defina una asignación de roles para la identidad asignada por el sistema:

az cosmosdb sql role assignment create --account-name $cosmosdb_acc_name --resource-group $resource_group --role-definition-id $readOnlyRoleDefinitionId --principal-id $system_assigned_principal --scope $scope

Para obtener más información, consulte Usar el control de acceso basado en roles en el plano de datos con Azure Cosmos DB para NoSQL

Configuración de la definición del origen de datos

Una vez que haya configurado ambas asignaciones de roles de plano de control y de plano de datos en la cuenta de Azure Cosmos DB para NoSQL, puede establecer una conexión con ella que opere bajo este rol.

Los indexadores usan un objeto de origen de datos para las conexiones a un origen de datos externo. En esta sección se explica cómo especificar una identidad administrada asignada por el sistema o una identidad administrada asignada por el usuario en la cadena de conexión de un origen de datos. Puede encontrar más ejemplos de cadenas de conexión en el artículo de identidad administrada.

Sugerencia

Puede crear una conexión de origen de datos a Cosmos DB en el portal de Azure, especificando una identidad administrada de sistema o asignada por el usuario, y luego ver la definición JSON para ver cómo se formula la cadena de conexión.

El REST API, Azure portal y el SDK de .NET admite el uso de una identidad administrada asignada por el sistema o asignada por el usuario.

Conexión a través de la identidad asignada por el sistema

Al conectarse con una identidad administrada asignada por el sistema, el único cambio en la definición del origen de datos es el formato de la propiedad "credentials". Proporcione un nombre de base de datos y un ResourceId que no tenga ninguna clave de cuenta ni contraseña. ResourceId debe incluir el identificador de suscripción de Azure Cosmos DB, el grupo de recursos y el nombre de la cuenta de Azure Cosmos DB.

Este es un ejemplo mediante la API REST Create Data Source que ejerce el enfoque moderno .

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]" }
}

Nota

Si la propiedad IdentityAuthType no forma parte de la cadena de conexión, Búsqueda de Azure AI utiliza el enfoque legacy por defecto para garantizar la compatibilidad con versiones anteriores.

Conexión a través de la identidad asignada por el usuario

Debe agregar una propiedad "identity" a la definición del origen de datos, donde especifique la identidad específica (de varias que se pueden asignar al servicio de búsqueda), que se usarán para conectarse a la cuenta de Azure Cosmos DB.

Este es un ejemplo de uso de la identidad asignada por el usuario mediante el enfoque moderno.

POST https://[service name].search.windows.net/datasources?api-version=2026-04-01
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];IdentityAuthType=AccessToken"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Conexión a Azure Cosmos DB para Gremlin/MongoDB (versión preliminar)

En esta sección se describen los pasos para configurar la conexión a Azure Cosmos DB para Gremlin/Mongo a través del enfoque legacy.

Configurar asignaciones de roles del plano de control

Siga los mismos pasos que antes para asignar los roles adecuados en el plano de control del Azure Cosmos DB para Gremlin/MongoDB.

Establece la cadena de conexión

  • En el caso de las colecciones de MongoDB, agregue "ApiKind=MongoDb" a la cadena de conexión y use una API REST en versión preliminar.
  • En el caso de los grafos de Gremlin, agregue "ApiKind=Gremlin" al cadena de conexión y use una API REST en versión preliminar.
  • Para ambos tipos, solo se admite el enfoque legacy, es decir, IdentityAuthType=AccountKey o omitirlo por completo es la única cadena de conexión válida.

Este es un ejemplo para conectarse a colecciones de MongoDB mediante la identidad asignada por el sistema a través de la API REST.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "name": "my-cosmosdb-ds",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=MongoDb"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null
}

Este es un ejemplo para conectarse a grafos de Gremlin mediante la identidad asignada por el usuario.

POST https://[service name].search.windows.net/datasources?api-version=2026-08-01-preview
{
    "name": "[my-cosmosdb-ds]",
    "type": "cosmosdb",
    "credentials": {
        "connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=Gremlin"
    },
    "container": { "name": "[my-cosmos-collection]"},
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    }
}

Ejecución del indexador para comprobar los permisos

La información de conexión y los permisos en el servicio remoto se validan en tiempo de ejecución durante la ejecución del indexador. Si el indexador funciona correctamente, la sintaxis de conexión y las asignaciones de roles son válidas. Para obtener más información, consulte Ejecutar o restablecer indexadores, habilidades o documentos.

Solución de problemas de conexiones

  • Para Azure Cosmos DB para NoSQL, compruebe si la cuenta tiene su acceso restringido para seleccionar redes. Para descartar cualquier problema de firewall, pruebe la conexión sin restricciones. Consulte el acceso de Indexer al contenido protegido por la seguridad de red de Azure para obtener más información.

  • Para Azure Cosmos DB para NoSQL, si se produce un error en el indexador debido a problemas de autenticación, asegúrese de que las asignaciones de roles se han realizado both en el plano de control y el plano de datos de la cuenta de Cosmos DB.

  • Para Gremlin o MongoDB, si ha rotado recientemente las claves de cuenta de Azure Cosmos DB, debe esperar hasta 15 minutos para que la cadena de conexión de identidad administrada funcione.

Consulte también

  • Last updated on