Condividi tramite

Connettersi ad Azure Cosmos DB usando un'identità gestita (Ricerca di intelligenza artificiale di Azure)

  • Articolo

Questo articolo illustra come configurare una connessione dell'indicizzatore a un database di Azure Cosmos DB usando un'identità gestita anziché fornire le credenziali nel stringa di connessione".

È possibile usare un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente. Le identità gestite sono account di accesso di Microsoft Entra e richiedono assegnazioni di ruolo di Azure per accedere ai dati in Azure Cosmos DB.

Prerequisiti

Limiti

Il supporto dell'indicizzatore per Azure Cosmos DB per le raccolte Gremlin e MongoDB è attualmente in anteprima. A questo punto, una limitazione dell'anteprima richiede che Ricerca intelligenza artificiale di Azure si connetta usando le chiavi. È comunque possibile configurare un'identità gestita e un'assegnazione di ruolo, ma Ricerca di intelligenza artificiale di Azure userà solo l'assegnazione di ruolo per ottenere le chiavi per la connessione. Questa limitazione significa che non è possibile configurare un approccio basato su ruoli se gli indicizzatori si connettono a Gremlin o MongoDB.

Creare un'assegnazione di ruolo in Azure Cosmos DB

  1. Accedere a portale di Azure e trovare l'account Cosmos DB per NoSQL.

  2. Seleziona Controllo di accesso (IAM).

  3. Selezionare Aggiungi e quindi selezionare Assegnazione di ruolo.

  4. Nell'elenco dei ruoli della funzione di processo selezionare Lettore account Cosmos DB.

  5. Selezionare Avanti.

  6. Selezionare Identità gestita e quindi Membri.

  7. Filtrare in base alle identità gestite assegnate dal sistema o alle identità gestite assegnate dall'utente. Verrà visualizzata l'identità gestita creata in precedenza per il servizio di ricerca. Se non è disponibile, vedere Configurare la ricerca per l'uso di un'identità gestita. Se è già stato configurato, ma non è disponibile, assegnare alcuni minuti.

  8. Selezionare l'identità e salvare l'assegnazione di ruolo.

Per altre informazioni, vedere Configurare il controllo degli accessi in base al ruolo con l'ID Microsoft Entra per l'account Azure Cosmos DB.

Specificare un'identità gestita in un stringa di connessione

Dopo aver assegnato un ruolo, è possibile configurare una connessione ad Azure Cosmos DB per NoSQL che opera con tale ruolo.

Gli indicizzatori usano un oggetto origine dati per le connessioni a un'origine dati esterna. Questa sezione illustra come specificare un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente in un'origine dati stringa di connessione. Altre stringa di connessione esempi sono disponibili nell'articolo Identità gestita.

Suggerimento

È possibile creare una connessione all'origine dati a CosmosDB nella portale di Azure, specificando un'identità gestita assegnata dal sistema o dall'utente e quindi visualizzare la definizione JSON per vedere come viene formulata la stringa di connessione.

Identità gestita assegnata dal sistema

L'API REST, portale di Azure e .NET SDK supportano l'uso di un'identità gestita assegnata dal sistema.

Quando ci si connette con un'identità gestita assegnata dal sistema, l'unica modifica alla definizione dell'origine dati è il formato della proprietà "credentials". Specificare un nome di database e un Id risorsa senza chiave o password dell'account. ResourceId deve includere l'ID sottoscrizione di Azure Cosmos DB, il gruppo di risorse e il nome dell'account Azure Cosmos DB.

  • Per le raccolte SQL, il stringa di connessione non richiede "ApiKind".
  • Per le raccolte SQL, aggiungere "IdentityAuthType=AccessToken" se l'accesso basato sui ruoli viene applicato come unico metodo di autenticazione. Non è applicabile per le raccolte MongoDB e Gremlin.
  • Per le raccolte MongoDB, aggiungere "ApiKind=MongoDb" al stringa di connessione e usare un'API REST di anteprima.
  • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" al stringa di connessione e usare un'API REST di anteprima.

Ecco un esempio di come creare un'origine dati per indicizzare i dati da un account Cosmos DB usando l'API REST Crea origine dati e un'identità gestita stringa di connessione. Il formato dell'identità gestita stringa di connessione è lo stesso per l'API REST, .NET SDK e l'portale di Azure.

POST https://[service name].search.windows.net/datasources?api-version=2023-11-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à gestita assegnata dall'utente

Quando ci si connette con un'identità gestita assegnata dall'utente, vengono apportate due modifiche alla definizione dell'origine dati:

  • In primo luogo, il formato della proprietà "credentials" è il nome del database e un ResourceId senza chiave o password dell'account. ResourceId deve includere l'ID sottoscrizione di Azure Cosmos DB, il gruppo di risorse e il nome dell'account Azure Cosmos DB.

    • Per le raccolte SQL, il stringa di connessione non richiede "ApiKind".
    • Per le raccolte SQL, aggiungere "IdentityAuthType=AccessToken" se l'accesso basato sui ruoli viene applicato come unico metodo di autenticazione. Non è applicabile per le raccolte MongoDB e Gremlin.
    • Per le raccolte MongoDB, aggiungere "ApiKind=MongoDb" alla stringa di connessione
    • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" alla stringa di connessione.

  • In secondo luogo, si aggiunge una proprietà "identity" che contiene la raccolta di identità gestite assegnate dall'utente. Quando si crea l'origine dati, è necessario specificare un'unica identità gestita assegnata dall'utente. Impostarlo sul tipo "userAssignedIdentities".

Ecco un esempio di come creare un oggetto origine dati dell'indicizzatore usando l'API REST.

POST https://[service name].search.windows.net/datasources?api-version=2023-11-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
}

Le informazioni di connessione e le autorizzazioni per il servizio remoto vengono convalidate in fase di esecuzione durante l'esecuzione dell'indicizzatore. Se l'indicizzatore ha esito positivo, la sintassi di connessione e le assegnazioni di ruolo sono valide. Per altre informazioni, vedere Eseguire o reimpostare indicizzatori, competenze o documenti.

Risoluzione dei problemi

Per Azure Cosmos DB per NoSQL, verificare se l'account ha accesso limitato alle reti selezionate. È possibile escludere eventuali problemi del firewall provando la connessione senza restrizioni.

Per Gremlin o MongoDB, se di recente sono state ruotate le chiavi dell'account Azure Cosmos DB, è necessario attendere fino a 15 minuti per il funzionamento dell'identità gestita stringa di connessione.

Vedi anche