Configurer une connexion d’indexeur à Azure Cosmos DB à l’aide d’une identité managée

Article
04/24/2024

Cet article explique comment configurer une connexion d’indexeur à une base de données Azure Cosmos DB en utilisant une identité managée au lieu de fournir des informations d’identification dans la chaîne de connexion.

Vous pouvez utiliser une identité managée affectée par le système ou une identité managée affectée par l’utilisateur (préversion). Les identités managées sont des connexions Microsoft Entra et nécessitent des attributions de rôles Azure pour accéder aux données dans Azure Cosmos DB.

Prérequis

Créez une identité managée pour votre service de recherche.
Attribuez le rôle Lecteur de compte Cosmos DB à l’identité managée du service de recherche. Ce rôle permet de lire les données de compte Azure Cosmos DB. Pour plus d’informations sur les attributions de rôles dans Cosmos DB, consultez Configurer le contrôle d’accès en fonction du rôle aux données.
Attribution de rôle de plan de données : suivez Attribution de rôle de plan de données pour en savoir plus.
Exemple d’attribution de rôle de plan de données en lecture seule :

$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)

Attribution de rôle pour l’identité affectée par le système :

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

Pour Cosmos DB for NoSQL, vous pouvez éventuellement appliquer l’accès en fonction du rôle comme seule méthode d’authentification pour les connexions de données en définissant disableLocalAuth sur true pour votre compte Cosmos DB.
Pour les collections Gremlin et MongoDB : la prise en charge de l’indexeur est actuellement en préversion. Actuellement, il existe une limitation de préversion qui nécessite qu’Azure AI Recherche se connecte à l’aide de clés. Vous pouvez toujours configurer une identité managée et une attribution de rôle, mais Azure AI Recherche utilise uniquement l’attribution de rôle pour obtenir des clés pour la connexion. Cette limitation signifie que vous ne pouvez pas configurer une approche en fonction du rôle si vos indexeurs se connectent à Gremlin ou MongoDB à l’aide de la recherche avec des identités managées pour se connecter à Azure Cosmos DB.
Vous devez être familiarisé avec les concepts et la configuration de l’indexeur.

Créer la source de données

Créez la source de données et indiquez une identité managée affectée par le système ou une identité managée affectée par l’utilisateur (préversion) dans la chaîne de connexion.

Identité managée affectée par le système

L’API REST, le portail Azure et le kit SDK .NET prennent en charge l’utilisation d’une identité managée affectée par le système.

Quand vous vous connectez avec une identité managée affectée par le système, la seule modification apportée à la définition de la source de données est le format de la propriété « credentials ». Vous fournissez le nom de la base de données et un ResourceId qui n’a pas de clé ou de mot de passe de compte. Le ResourceId doit inclure l’ID d’abonnement d’Azure Cosmos DB, le groupe de ressources et le nom du compte Azure Cosmos DB.

Pour les collections SQL, la chaîne de connexion ne requiert pas « ApiKind ».
Pour les collections SQL, ajoutez « IdentityAuthType=AccessToken » si le contrôle d’accès en fonction du rôle est appliqué comme seule méthode d’authentification. Il n’est pas applicable aux collections MongoDB et Gremlin.
Pour les collections MongoDB, ajoutez « ApiKind=MongoDb » à la chaîne de connexion et utilisez une API REST en préversion.
Pour les graphiques Gremlin, ajoutez « ApiKind = Gremlin » à la chaîne de connexion et utilisez une API REST en préversion.

Voici un exemple de la façon de créer une source de données pour indexer des données à partir d’un compte de stockage en utilisant l’API REST et une chaîne de connexion d’identité managée. Le format de chaîne de connexion d’identité managée est le même pour l’API REST, le kit de développement logiciel (SDK) .NET et le portail Azure.

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

 
}

Identité managée affectée par l’utilisateur (préversion)

L’API REST 2021-04-30-preview prend en charge les connexions basées sur une identité managée affectée par l’utilisateur. Quand vous vous connectez avec une identité managée affectée par l’utilisateur, deux modifications sont apportées à la définition de la source de données :

Tout d’abord, le format de la propriété « credentials » est le nom de la base de données et un ResourceId qui n’a pas de clé ou de mot de passe de compte. Le ResourceId doit inclure l’ID d’abonnement d’Azure Cosmos DB, le groupe de ressources et le nom du compte Azure Cosmos DB.
- Pour les collections SQL, la chaîne de connexion ne requiert pas « ApiKind ».
- Pour les collections SQL, ajoutez « IdentityAuthType=AccessToken » si le contrôle d’accès en fonction du rôle est appliqué comme seule méthode d’authentification. Il n’est pas applicable aux collections MongoDB et Gremlin.
- Pour les collections MongoDB, ajoutez « ApiKind=MongoDb » à la chaîne de connexion
- Pour les graphiques Gremlin, ajoutez « ApiKind = Gremlin » à la chaîne de connexion.
Ensuite, vous ajoutez une propriété « identité » qui contient la collection d’identités managées affectées par l’utilisateur. Une seule identité managée affectée par l’utilisateur doit être fournie lors de la création de la source de données. Définissez-la sur le type « userAssignedIdentities ».

Voici un exemple de la façon de créer un objet de source de données d’indexeur en utilisant l’API REST Créer ou mettre à jour une source de données - Préversion :

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
}

Création de l'index

L’index spécifie les champs d’un document, les attributs et d’autres constructions qui façonnent l’expérience de recherche.

Voici un appel de l’API REST Créer un index avec un champ de recherche booktitle :

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 }
    ]
}

Créer l’indexeur

Un indexeur connecte une source de données à un index de recherche cible et fournit une planification afin d’automatiser l’actualisation des données. Une fois l’index et la source de données créés, vous êtes prêt à créer et exécuter l’indexeur. Si l’indexeur réussit, la syntaxe de connexion et les attributions de rôles sont valides.

Voici un appel de l’API REST Créer un indexeur avec une définition d’indexeur Azure Cosmos DB for NoSQL. L’indexeur s’exécute quand vous envoyez la demande.

    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"
    }

Dépannage

Si vous avez récemment alterné vos clés de compte Azure Cosmos DB, vous devez attendre jusqu’à 15 minutes pour que la chaîne de connexion de l’identité managée fonctionne.

Vérifiez si l’accès au compte Azure Cosmos DB est limité à certains réseaux. Vous pouvez éliminer les problèmes de pare-feu en essayant la connexion sans restrictions en place.

Partage via