Autenticarsi a Cosmos DB su Microsoft Fabric dai servizi host di Azure

Cosmos DB in Microsoft Fabric si basa esclusivamente sull'autenticazione di Microsoft Entra ID e sui ruoli predefiniti del piano dati per gestire l'autenticazione e l'autorizzazione. In questa guida, utilizzerai l'ID Microsoft Entra e l'account con cui sei connesso per collegarti a un artefatto di Cosmos DB in Microsoft Fabric.

Importante

I passaggi sono simili al processo usato per l'autenticazione se si utilizza un'entità del servizio, un gruppo o un altro tipo di identità di Microsoft Entra ID. Per concedere a un'entità servizio la possibilità di connettersi a Microsoft Fabric e al database Cosmos DB, abilitare l'impostazione "Le entità servizio possono usare l'impostazione API fabric nel tenant di Fabric. Per altre informazioni, vedere Impostazioni del tenant di Microsoft Fabric. Questa impostazione è abilitata per impostazione predefinita per i nuovi clienti.

Prerequisiti

• Una capacità di Fabric esistente

  • Se non si ha capacità di Fabric, attivare una versione di prova di Fabric.

• Un database Cosmos DB esistente in Fabric

  • Se non ne è già disponibile uno, creare un nuovo database Cosmos DB in Fabric.

• Un'identità con l'autorizzazione Lettura per il database in Fabric

  • Per altre informazioni sulle autorizzazioni di Fabric, vedere Controlli di accesso.

• Interfaccia CLI di Azure

  • Se non l'hai già, installa Azure CLI.

• Python 3.12 o versione successiva

• Node.js 22 o versione successiva

• .NET SDK 9.0 o versione successiva

Recuperare l'endpoint di Cosmos DB

Ottenere prima di tutto l'endpoint per il database Cosmos DB in Fabric. Questo endpoint è necessario per connettersi usando Azure SDK.

1. Aprire il portale Fabric (https://app.fabric.microsoft.com).

2. Navigare al database Cosmos DB esistente.

3. Selezionare l'opzione Impostazioni nella barra dei menu per il database.

   

4. Nella finestra di dialogo impostazioni passare alla sezione Connessione . Copia quindi il valore del campo Endpoint per il database NoSQL di Cosmos DB. Questo valore viene usato nei passaggi successivi.

   

Eseguire l'autenticazione nell'interfaccia della riga di comando di Azure

Eseguire ora l'autenticazione all'interfaccia della riga di comando di Azure. Azure SDK può usare diversi meccanismi di autenticazione per verificare l'identità, ma l'interfaccia della riga di comando di Azure è l'opzione più universale e senza attrito in diversi linguaggi di sviluppo.

1. Nell'ambiente di sviluppo locale aprire un terminale.

2. Eseguire l'autenticazione nell'interfaccia della riga di comando di Azure usando az login.

   az login
   

3. Seguire i passaggi interattivi per eseguire l'autenticazione a più fattori (MFA) e selezionare la sottoscrizione.

4. Verificare che l'account sia stato connesso correttamente interrogando la propria identità.

   az ad signed-in-user show
   

5. Osservate l'output del comando precedente. Il id campo contiene l'ID principale (oggetto) dell'identità attualmente autenticata.

   {
     "@odata.context": "<https://graph.microsoft.com/v1.0/$metadata#users/$entity>",
     "businessPhones": [],
     "displayName": "Kai Carter",
     "givenName": "Kai",
     "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
     "jobTitle": "Senior Sales Representative",
     "mail": "<kai@adventure-works.com>",
     "mobilePhone": null,
     "officeLocation": "Redmond",
     "preferredLanguage": null,
     "surname": "Carter",
     "userPrincipalName": "<kai@adventure-works.com>"
   }
   

   Annotazioni

   Nei termini Microsoft Entra ID, questa identità viene definita identità umana. Si tratta di un tipo di identità che può connettersi ai database tra molti tipi diversi, tra cui, ad esempio:

   • Identità gestite (assegnata dal sistema o dall'utente)
   • Identità dei carichi di lavoro
   • Identità dell'applicazione
   • Identità dei dispositivi

   Sebbene questi passaggi si concentrino sull'uso dell'identità umana per connettersi al database in Fabric, i passaggi sono simili se ci si connette usando un tipo di identità diverso. Per altre informazioni sulle identità, vedere Nozioni fondamentali sull'identità.

Connettersi con Azure SDK

Usare infine Azure SDK per connettersi al database Cosmos DB in Fabric usando l'endpoint e l'identità. Azure SDK viene fornito con una libreria di identità unificata che gestisce automaticamente l'autenticazione per conto dell'utente. Questo passaggio usa il DefaultAzureCredential() tipo , che trova automaticamente il tipo di identità corretto in base all'ambiente in uso.

Annotazioni

Gli oggetti credenziali di Azure non sono supportati nei notebook di Microsoft Fabric. Non è possibile usare DefaultAzureCredential per eseguire l'autenticazione a Cosmos DB in Fabric. È necessario creare un oggetto credenziale personalizzato nei notebook per l'autenticazione. Per altre informazioni, vedere Eseguire l'autenticazione a Cosmos DB in Microsoft Fabric da notebook di Fabric.

from azure.cosmos.aio import CosmosClient
from azure.identity import DefaultAzureCredential

endpoint = "<cosmos-db-fabric-endpoint>"

credential = DefaultAzureCredential()

async with CosmosClient(endpoint, credential=credential) as client:
    container = client.get_database_client("<database-name>").get_container_client("<container-name>")

    nosql = "SELECT TOP 10 VALUE item.id FROM items AS item"

    results = container.query_items(
        query=nosql
    )

    items = []
    async for item in results:
        items.append(item)

    for item in items:
        print(item)

Annotazioni

Questo esempio usa i azure-identity pacchetti e azure-cosmos da PyPI. Si noti l'uso di azure.cosmos.aio per il supporto asincrono.

import { Container, CosmosClient, CosmosClientOptions } from '@azure/cosmos'
import { TokenCredential, DefaultAzureCredential } from '@azure/identity'

const endpoint: string = '<cosmos-db-fabric-endpoint>';

const credential: TokenCredential = new DefaultAzureCredential();

const options: CosmosClientOptions = {
    endpoint: endpoint,
    aadCredentials: credential
};

const client: CosmosClient = new CosmosClient(options);

const container: Container = client.database('<database-name>').container('<container-name>');

const nosql = 'SELECT TOP 10 VALUE item.id FROM items AS item';

const querySpec = {
    query: nosql
};

const response = await container.items.query(querySpec).fetchAll();
for (const item of response.resources) {
    console.log(item);
}

Annotazioni

Questo esempio usa i @azure/identity pacchetti e @azure/cosmos di npm.

using Azure.Identity;
using Microsoft.Azure.Cosmos;

string endpoint = "<cosmos-db-fabric-endpoint>";
DefaultAzureCredential credential = new();
using CosmosClient client = new(endpoint, credential);

Container container = client
    .GetDatabase("<database-name>")
    .GetContainer("<container-name>");

string sql = "SELECT TOP 10 VALUE item.id FROM items AS item";

QueryDefinition query = new(sql);

FeedIterator<string> iterator = container.GetItemQueryIterator<string>(query);

while (iterator.HasMoreResults)
{
    FeedResponse<string> response = await iterator.ReadNextAsync();
    foreach (var item in response)
    {
        Console.WriteLine(item);
    }
}

Annotazioni

Questo esempio usa i Azure.Identity pacchetti e Microsoft.Azure.Cosmos di NuGet.

Contenuti correlati

• Informazioni su Cosmos DB in Microsoft Fabric
• Gestire l'autorizzazione in Cosmos DB in Microsoft Fabric