Configuración de una conexión de indexador a Azure Cosmos DB mediante una identidad administrada

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 (versión preliminar). 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

• Crear una identidad administrada para su servicio de búsqueda.

• Asigne el rol Lector de cuentas de Cosmos DB a la identidad administrada del servicio de búsqueda. Este rol concede la capacidad de leer datos de cuentas de Azure Cosmos DB. Para obtener más información sobre las asignaciones de roles en Cosmos DB, consulte Configuración del control de acceso basado en rol para datos.

• Asignación de roles del plano de datos: consulte Asignación de roles del plano de datos para obtener más información.

• Ejemplo de asignación de roles del plano de datos de solo lectura:

$cosmosdb_acc_name = <cosmos db account name>
$resource_group = <resource group name>
$subsciption = <subscription id>
$system_assigned_principal = <principal id for system assigned identity>
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)

Asignación de roles para la identidad asignada por el sistema:

az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope

• En el caso de Cosmos DB para NoSQL, tiene la opción de aplicar un acceso basado en rol como único método de autenticación para las conexiones de datos estableciendo disableLocalAuth en true para la cuenta de Cosmos DB.

• Para las colecciones de Gremlin y MongoDB: la compatibilidad con los indexadores está actualmente en versión preliminar. En este momento, existe una limitación de versión preliminar que 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 implica que no puede configurar un enfoque basado en roles si los indizadores se conectan a Gremlin o MongoDB mediante Search con identidades administradas para conectarse a Azure Cosmos DB.

• Debe conocer los conceptos del indexador y la configuración.

Creación del origen de datos

Cree el origen de datos y proporcione una identidad administrada asignada por el sistema o por el usuario (versión preliminar) en 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". Deberá proporcionar el nombre de la base de datos y un valor de ResourceId que no tenga 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 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.

A continuación, se muestra un ejemplo de cómo crear un origen de datos para indexar datos desde una cuenta de almacenamiento mediante la API REST de creación de origen de datos 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=2020-06-30
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
    },
    "container": { "name": "[my-cosmos-collection]", "query": null },
    "dataChangeDetectionPolicy": null

 
}

Identidad administrada asignada por el usuario (versión preliminar)

La API REST 2021-04-30-preview admite conexiones basadas en una 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".

A continuación, se ofrece un ejemplo de cómo crear un objeto de origen de datos de indexador mediante la API REST de creación o actualización de origen de datos en versión preliminar:

POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
Content-Type: application/json
api-key: [Search service admin key]

{
    "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 | Gremlin | MongoDB];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
}

creación del índice

El índice especifica los campos de un documento, los atributos y otras construcciones que conforman la experiencia de búsqueda.

Esta es una llamada a la API REST de creación de índice con un campo booktitle que permite búsquedas:

POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
Content-Type: application/json
api-key: [admin key]

{
    "name" : "my-target-index",
    "fields": [
    { "name": "id", "type": "Edm.String", "key": true, "searchable": false },
    { "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
    ]
}

Creación del indexador

Un indexador conecta un origen de datos con un índice de búsqueda de destino y proporciona una programación para automatizar la actualización de datos. Una vez creados el índice y el origen de datos, estará preparado para crear y ejecutar el indexador. Si el indexador se realizó correctamente, la sintaxis de conexión y las asignaciones de roles son válidas.

Esta es una llamada a la API REST Crear indizador con una definición de indizador de Azure Cosmos DB for NoSQL. El indexador se ejecuta al enviar la solicitud.

    POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
    Content-Type: application/json
    api-key: [admin key]

    {
      "name" : "cosmos-db-indexer",
      "dataSourceName" : "cosmos-db-datasource",
      "targetIndexName" : "my-target-index"
    }

Solución de problemas

Si ha rotado recientemente las claves de la cuenta de Azure Cosmos DB, tendrá que esperar un máximo de 15 minutos para que la cadena de conexión de la identidad administrada funcione.

Compruebe si la cuenta de Azure Cosmos DB tiene acceso restringido a las redes seleccionadas. Para descartar cualquier problema relacionado con el firewall, pruebe la conexión sin restricciones.

Consulte también

• Indexación mediante Azure Cosmos DB for NoSQL
• Indexación mediante Azure Cosmos DB for MongoDB
• Indexación mediante Azure Cosmos DB for Apache Gremlin