Condividi tramite

Connettersi ad Azure Cosmos DB usando un'identità gestita (Azure AI Search)

  • 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 nella 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 Azure AI Search si connetta usando le chiavi. È comunque possibile configurare un'identità gestita e un'assegnazione di ruolo, ma Azure AI Search 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 al 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 selezionare 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 ne è già stato configurata una ma non è disponibile, attendere qualche minuto.

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

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

Specificare un'identità gestita in una 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 una stringa di connessione dell'origine dati. Altre esempi di stringhe di connessione sono disponibili nell'articolo sull'identità gestita.

Suggerimento

È possibile creare una connessione dell'origine dati a CosmosDB nel portale di Azure, specificando un'identità gestita assegnata dal sistema o un'identità gestita assegnata 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, il 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 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, la stringa di connessione non necessita di "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 e usare un'anteprima dell’API REST.
  • Per i grafici Gremlin, aggiungere "ApiKind=Gremlin" alla stringa di connessione e usare un'anteprima dell’API REST.

Ecco un esempio di come creare un'origine dati per indicizzare i dati da un account di Cosmos DB usando l'API REST Create Data Source e una stringa di connessione identity gestita. Il formato della stringa di connessione dell'identità gestita è lo stesso per l'API REST, .NET SDK e il portale di 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à 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à "credenziali" è il nome del database e un ResourceId che non ha una chiave o una 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, la stringa di connessione non necessita di "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, aggiungere una proprietà "identità" 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=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
}

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 della stringa di connessione dell'identità gestita.

Vedi anche