Partager via

Se connecter à Azure Cosmos DB à l’aide d’une identité managée (recherche Azure AI)

  • Article

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. 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

Limites

La prise en charge de l’indexeur d’Azure Cosmos DB pour Gremlin et les collections MongoDB est actuellement en préversion. Actuellement, une limite de préversion oblige la recherche Azure AI à se connecter à 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 limite signifie que vous ne pouvez pas configurer une approche en fonction du rôle si vos indexeurs se connectent à Gremlin ou MongoDB.

Créer une attribution de rôle dans Azure Cosmos DB

  1. Connectez-vous au portail Azure et recherchez votre compte Cosmos DB for NoSQL.

  2. Sélectionnez Contrôle d’accès (IAM) .

  3. Sélectionnez Ajouter, puis Attribution de rôle.

  4. Dans la liste des rôles de fonction de tâche, sélectionnez Lecteur de compte Cosmos DB.

  5. Cliquez sur Suivant.

  6. Sélectionnez Identité managée, puis Membres.

  7. Filtrez selon les identités managées affectées par le système ou les identités managées affectées par l’utilisateur. Vous devez voir l’identité managée que vous avez créée précédemment pour votre service de recherche. Si vous n’en avez pas, consultez Configurer la recherche pour utiliser une identité managée. Si vous en avez déjà configuré une mais qu’elle n’est pas disponible, patientez quelques minutes.

  8. Sélectionnez l’identité et enregistrez l’attribution de rôle.

Pour plus d’informations, consultez Configurer le contrôle d’accès en fonction du rôle avec Microsoft Entra ID pour votre compte Azure Cosmos DB.

Spécifier une identité managée dans une chaîne de connexion

Une fois que vous avez une attribution de rôle, vous pouvez configurer une connexion à Azure Cosmos DB for NoSQL qui fonctionne sous ce rôle.

Les indexeurs utilisent un objet source de données pour les connexions à une source de données externe. Cette section explique comment spécifier une identité managée affectée par le système ou une identité managée affectée par l’utilisateur dans une chaîne de connexion de source de données. Vous trouverez d’autres exemples de chaîne de connexion dans l’article sur l’identité managée.

Conseil

Vous pouvez créer une connexion de source de données à CosmosDB dans le portail Azure, en spécifiant une identité managée affectée par le système ou par l’utilisateur, puis afficher la définition JSON pour voir comment la chaîne de connexion est formulée.

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 ». Fournissez un nom de base de données et un ResourceId qui n’a pas de clé de compte ou de mot de passe. 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 création d’une source de données pour indexer des données à partir d’un compte Cosmos DB à l’aide de l’API REST Créer une source de données et d’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=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

 
}

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 ».

Exemple de création d’un objet source de données indexeur à l’aide de l’API 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
}

Les informations de connexion et les autorisations sur le service distant sont validées au moment de l’exécution de l’indexeur. Si l’indexeur réussit, la syntaxe de connexion et les attributions de rôles sont valides. Pour plus d'informations, consultez Exécuter ou réinitialiser des indexeurs, des compétences ou des documents.

Dépannage

Pour Azure Cosmos DB for NoSQL, vérifiez si l’accès du compte aux réseaux sélectionnés est restreint. Vous pouvez éliminer les problèmes de pare-feu en essayant la connexion sans restrictions en place.

Pour Gremlin ou MongoDB, 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.

Voir aussi