Compartir vía

Conexión a Azure Cosmos DB mediante una identidad administrada (Azure AI Search)

  • Artículo

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 la cadena de conexión.

Puede usar una identidad administrada asignada por el sistema o 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.

Requisitos previos

Limitaciones

El soporte del indexador con Azure Cosmos DB para colecciones de Gremlin y MongoDB está actualmente en versión preliminar. En este momento, una limitación de versión preliminar requiere que Azure AI Search se conecte mediante claves. Puede seguir configurando una identidad administrada y una asignación de roles, pero Azure AI Search solo usará la asignación de roles para obtener claves para la conexión. Esta limitación significa que no se puede configurar un enfoque basado en roles si los indexadores se conectan a Gremlin o MongoDB.

Creación de una asignación de roles en Azure Cosmos DB

  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 función de trabajo, seleccione Lector de cuentas de Cosmos DB.

  5. Seleccione Siguiente.

  6. Seleccione Identidad administrada y, después, 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 una pero no está disponible, espere unos minutos.

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

Para más información, consulte Configuración del control de acceso basado en roles con Microsoft Entra ID para la cuenta de Azure Cosmos DB.

Especificación de una identidad administrada en una cadena de conexión

Una vez que tenga una asignación de roles, puede configurar una conexión a Azure Cosmos DB para NoSQL que funcione con ese 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 una cadena de conexión del origen de datos. Puede encontrar más ejemplos de cadenas de conexión en el artículo sobre la identidad administrada.

Sugerencia

Puede crear una conexión de origen de datos a CosmosDB en Azure Portal, especificar una identidad administrada asignada por el usuario o un sistema y, a continuación, ver la definición JSON para ver cómo se formula la cadena de conexión.

Identidad administrada asignada por el sistema

La API de REST, Azure Portal y el SDK de .NET permiten usar una identidad administrada asignada por el sistema.

Cuando se conecte con una identidad administrada asignada por el sistema, el único cambio en la definición del origen de datos será 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 cuenta de Azure Cosmos DB.

  • En las colecciones de SQL, la cadena de conexión no requiere un elemento "ApiKind".
  • En el caso de las colecciones SQL, agregue "IdentityAuthType=AccessToken" si se aplica el acceso basado en rol como único método de autenticación. No se puede aplicar a las colecciones de MongoDB ni de Gremlin.
  • Para las colecciones de MongoDB, agregue "ApiKind=MongoDb" a la cadena de conexión y use una API de REST en versión preliminar.
  • Para los gráficos de Gremlin, agregue "ApiKind=Gremlin" a la cadena de conexión y use una API de REST en versión preliminar.

Este es un ejemplo de cómo crear un origen de datos para indexar datos desde una cuenta de Cosmos DB mediante el Crear origen de datos API de REST y una cadena de conexión de identidad administrada. El formato de la cadena de conexión de identidad administrada es el mismo para la API REST, el SDK de .NET y Azure Portal.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Identidad administrada asignada por el usuario

Al conectarse con una identidad administrada asignada por el usuario, se producen dos cambios en la definición del origen de datos:

  • En primer lugar, el formato de la propiedad "credentials" es el nombre de la base de datos y un valor de ResourceId que no tiene clave ni contraseña de cuenta. ResourceId debe incluir el identificador de suscripción de Azure Cosmos DB, el grupo de recursos y el nombre de cuenta de Azure Cosmos DB.

    • En las colecciones de SQL, la cadena de conexión no requiere un elemento "ApiKind".
    • En el caso de las colecciones SQL, agregue "IdentityAuthType=AccessToken" si se aplica el acceso basado en rol como único método de autenticación. No se puede aplicar a las colecciones de MongoDB ni de Gremlin.
    • Para las colecciones de MongoDB, agregue "ApiKind=MongoDb" a la cadena de conexión.
    • Para los gráficos de Gremlin, agregue "ApiKind=Gremlin" a la cadena de conexión.

  • En segundo lugar, agrega una propiedad "identity" que contiene la colección de identidades administradas asignadas por el usuario. Solo se debe proporcionar una identidad administrada asignada por el usuario al crear el origen de datos. Establece el tipo en "userAssignedIdentities".

Este es un ejemplo de cómo crear un objeto de origen de datos de indexador mediante la API de REST.

POST https://[service name].search.windows.net/datasources?api-version=2024-07-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];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { 
        "name": "[my-cosmos-collection]", "query": null 
    },
    "identity" : { 
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/[subscription-id]/resourcegroups/[rg-name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[my-user-managed-identity-name]" 
    },
    "dataChangeDetectionPolicy": null
}

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 se realizó correctamente, la sintaxis de conexión y las asignaciones de roles son válidas. Para obtener más información, consulte Ejecutar o restablecer indizadores, aptitudes o documentos.

Solución de problemas

Para Azure Cosmos DB para NoSQL, compruebe si la cuenta tiene su acceso restringido para seleccionar redes. Para descartar cualquier problema relacionado con el firewall, pruebe la conexión sin restricciones.

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

Consulte también