Integrieren von Azure Cosmos DB for Table mit Service Connector

In diesem Artikel werden unterstützte Authentifizierungsmethoden und -clients beschrieben und Beispielcode zum Herstellen einer Verbindung mit Azure Cosmos DB für Tabellen mit Clouddiensten mithilfe von Service Connector bereitgestellt. Sie können auch eine Verbindung mit anderen Programmiersprachen ohne Service Connector herstellen. Der Artikel enthält die Namen und Werte der Standardumgebungsvariablen, die Sie beim Erstellen einer Dienstverbindung erhalten.

Unterstützte Rechendienste

Mit Service Connector können Sie die folgenden Computedienste mit Azure Cosmos DB for Table verbinden:

  • Azure App Service
  • Azure-Funktionen
  • Azure Kubernetes Service (AKS)
  • Azure Spring Apps

Unterstützte Authentifizierungstypen und Clienttypen

Die folgende Tabelle zeigt, welche Kombinationen von Clienttypen und Authentifizierungsmethoden für die Verbindung Ihres Computediensts mit Azure Cosmos DB for Table mithilfe von Service Connector unterstützt werden. Ein „Ja“ gibt an, dass die Kombination unterstützt wird, während ein „Nein“ angibt, dass sie nicht unterstützt wird.

Clienttyp Systemseitig zugewiesene verwaltete Identität Benutzerseitig zugewiesene verwaltete Identität Geheimer Schlüssel / Verbindungszeichenfolge Service Principal
.NET Ja Ja Ja Ja
Java Ja Ja Ja Ja
Node.js Ja Ja Ja Ja
Python Ja Ja Ja Ja
Go Ja Ja Ja Ja
Keine Ja Ja Ja Ja

In der Tabelle wird angegeben, dass alle Kombinationen von Clienttypen und Authentifizierungsmethoden in der Tabelle unterstützt werden. Alle Clienttypen können jede der Authentifizierungsmethoden verwenden, um mithilfe von Service Connector eine Verbindung mit Azure Cosmos DB for Table herzustellen.

Note

Cosmos DB unterstützt die Authentifizierung nicht nativ über verwaltete Identität. Daher verwendet Service Connector die verwaltete Identität, um die Verbindungszeichenfolge abzurufen, und die Verbindung wird anschließend mithilfe dieses Verbindungszeichenfolge hergestellt.

Namen von Standard-Umgebungsvariablen oder Anwendungseigenschaften und Beispielcode

Entnehmen Sie den nachstehenden Verbindungsdetails, wie Sie Ihre Computedienste mit Azure Cosmos DB for Table verbinden. Ersetzen Sie Platzhaltertext wie <account-name>, <table-name> und <account-key> durch Ihre tatsächlichen Werte. Benennungskonventionen finden Sie unter Service Connector Internals.

Systemseitig zugewiesene verwaltete Identität

Standardname der Umgebungsvariablen Beschreibung Beispielswert
AZURE_COSMOS_LISTCONNECTIONSTRINGURL Die URL zum Abrufen der Verbindungszeichenfolge https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<table-name>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE Ihr verwalteter Identitätsumfang https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT Ihr Ressourcen-Endpunkt https://<table-name>.documents.azure.com:443/

Beispielcode

So stellen Sie eine Verbindung mit einer vom System zugewiesenen verwalteten Identität her:

  1. Installieren Sie Abhängigkeiten.
    dotnet add package Azure.Data.Tables
    dotnet add package Azure.Identity
    
  2. Rufen Sie mithilfe von Azure.Identity ein Zugriffstoken für die verwaltete Identität oder den Dienstprinzipal ab. Verwenden Sie das Zugriffstoken und AZURE_COSMOS_LISTCONNECTIONSTRINGURL, um die Verbindungszeichenfolge abzurufen und eine Verbindung mit Azure Cosmos DB for Table herzustellen. Entfernen Sie im folgenden Code die Kommentierung des Abschnitts für Ihren Authentifizierungstyp:
    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Threading.Tasks;
    using Azure.Data.Tables;
    using Azure.Identity;
    
    var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // var tokenProvider = new DefaultAzureCredential();
    
    // For user-assigned identity.
    // var tokenProvider = new DefaultAzureCredential(
    //     new DefaultAzureCredentialOptions
    //     {
    //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    //     }
    // );
    
    // For service principal.
    // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
    // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
    // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
    // Acquire the access token. 
    AccessToken accessToken = await tokenProvider.GetTokenAsync(
        new TokenRequestContext(scopes: new string[]{ scope }));
    
    // Get the connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.POSTAsync(listConnectionStringUrl);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonConvert.DeserializeObject<Dictionary<string, List<Dictionary<string, string>>>(responseBody);
    var connectionString = connectionStrings["connectionStrings"].Find(connStr => connStr["description"] == "Primary Table Connection String")["connectionString"];
    
    // Connect to Azure Cosmos DB for Table
    TableServiceClient tableServiceClient = new TableServiceClient(connectionString);
    

Benutzerseitig zugewiesene verwaltete Identität

Standardname der Umgebungsvariablen Beschreibung Beispielswert
AZURE_COSMOS_LISTCONNECTIONSTRINGURL Die URL zum Abrufen der Verbindungszeichenfolge https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<table-name>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE Ihr verwalteter Identitätsumfang https://management.azure.com/.default
AZURE_COSMOS_CLIENTID Die ID Ihres geheimen Clientschlüssels <client-ID>
AZURE_COSMOS_RESOURCEENDPOINT Ihr Ressourcen-Endpunkt https://<table-name>.documents.azure.com:443/

Beispielcode

Um eine Verbindung mit einer vom Benutzer zugewiesenen verwalteten Identität herzustellen, verwendet der folgende Code die verwaltete Identität, um die Verbindungszeichenfolge abzurufen, und richtet dann die Verbindung ein:

  1. Installieren Sie Abhängigkeiten.
    dotnet add package Azure.Data.Tables
    dotnet add package Azure.Identity
    
  2. Rufen Sie mit Azure.Identity ein Zugriffstoken für die verwaltete Identität oder den Dienstprinzipal ab. Verwenden Sie das Zugriffstoken und AZURE_COSMOS_LISTCONNECTIONSTRINGURL, um die Verbindungszeichenfolge abzurufen und eine Verbindung mit Azure Cosmos DB für Table herzustellen. Entfernen Sie im folgenden Code die Kommentarzeichen im Abschnitt für Ihren Authentifizierungstyp:
    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Threading.Tasks;
    using Azure.Data.Tables;
    using Azure.Identity;
    
    var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // var tokenProvider = new DefaultAzureCredential();
    
    // For user-assigned identity.
    // var tokenProvider = new DefaultAzureCredential(
    //     new DefaultAzureCredentialOptions
    //     {
    //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    //     }
    // );
    
    // For service principal.
    // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
    // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
    // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
    // Acquire the access token. 
    AccessToken accessToken = await tokenProvider.GetTokenAsync(
        new TokenRequestContext(scopes: new string[]{ scope }));
    
    // Get the connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.POSTAsync(listConnectionStringUrl);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonConvert.DeserializeObject<Dictionary<string, List<Dictionary<string, string>>>(responseBody);
    var connectionString = connectionStrings["connectionStrings"].Find(connStr => connStr["description"] == "Primary Table Connection String")["connectionString"];
    
    // Connect to Azure Cosmos DB for Table
    TableServiceClient tableServiceClient = new TableServiceClient(connectionString);
    

Verbindungszeichenfolge

Standardname der Umgebungsvariablen Beschreibung Beispielswert
AZURE_COSMOS_CONNECTIONSTRING Azure Cosmos DB for Table-Verbindungszeichenfolge DefaultEndpointsProtocol=https;AccountName=<account-name>;AccountKey=<account-key>;TableEndpoint=https://<table-name>.table.cosmos.azure.com:443/;

Warnung

Microsoft empfiehlt, immer den sichersten Authentifizierungsflow zu verwenden. Der in diesem Verfahren beschriebene Authentifizierungsflow erfordert ein sehr hohes Maß an Vertrauen in die Anwendung und birgt Risiken, die bei anderen Flows nicht vorhanden sind. Sie sollten diesen Flow nur verwenden, wenn andere sicherere Flows (z. B. verwaltete Identitäten) nicht anwendbar sind.

Beispielcode

So stellen Sie eine Verbindung mit einem Verbindungszeichenfolge her:

  1. Installieren Sie die Abhängigkeit.

    dotnet add package Azure.Data.Tables
    
  2. Rufen Sie die Verbindungszeichenfolge aus der Umgebungsvariablen ab, die von Service Connector hinzugefügt wurde.

    using Azure.Data.Tables;
    using System; 
    
    TableServiceClient tableServiceClient = new TableServiceClient(Environment.GetEnvironmentVariable("AZURE_COSMOS_CONNECTIONSTRING"));
    

Service Principal

Standardname der Umgebungsvariablen Beschreibung Beispielswert
AZURE_COSMOS_LISTCONNECTIONSTRINGURL Die URL zum Abrufen der Verbindungszeichenfolge https://management.azure.com/subscriptions/<subscription-ID>/resourceGroups/<resource-group-name>/providers/Microsoft.DocumentDB/databaseAccounts/<table-name>/listConnectionStrings?api-version=2021-04-15
AZURE_COSMOS_SCOPE Ihr verwalteter Identitätsumfang https://management.azure.com/.default
AZURE_COSMOS_CLIENTID Die ID Ihres geheimen Clientschlüssels <client-ID>
AZURE_COSMOS_CLIENTSECRET Ihr Clientgeheimnis <client-secret>
AZURE_COSMOS_TENANTID Ihre Mandanten-ID <tenant-ID>
AZURE_COSMOS_RESOURCEENDPOINT Ihr Ressourcen-Endpunkt https://<table-name>.documents.azure.com:443/

Beispielcode

So stellen Sie eine Verbindung mit einem Dienstprinzipal her:

  1. Installieren Sie Abhängigkeiten.
    dotnet add package Azure.Data.Tables
    dotnet add package Azure.Identity
    
  2. Rufen Sie mit Azure.Identity ein Zugriffstoken für die verwaltete Identität oder den Dienstprinzipal ab. Verwenden Sie das Zugriffstoken und AZURE_COSMOS_LISTCONNECTIONSTRINGURL, um die Verbindungszeichenfolge abzurufen und eine Verbindung mit Azure Cosmos DB für Table herzustellen. Entfernen Sie im folgenden Code die Auskommentierung des Abschnitts für Ihren Authentifizierungstyp:
    using System;
    using System.Security.Authentication;
    using System.Net.Security;
    using System.Net.Http;
    using System.Security.Authentication;
    using System.Threading.Tasks;
    using Azure.Data.Tables;
    using Azure.Identity;
    
    var endpoint = Environment.GetEnvironmentVariable("AZURE_COSMOS_RESOURCEENDPOINT");
    var listConnectionStringUrl = Environment.GetEnvironmentVariable("AZURE_COSMOS_LISTCONNECTIONSTRINGURL");
    var scope = Environment.GetEnvironmentVariable("AZURE_COSMOS_SCOPE");
    
    // Uncomment the following lines corresponding to the authentication type you want to use.
    // For system-assigned identity.
    // var tokenProvider = new DefaultAzureCredential();
    
    // For user-assigned identity.
    // var tokenProvider = new DefaultAzureCredential(
    //     new DefaultAzureCredentialOptions
    //     {
    //         ManagedIdentityClientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    //     }
    // );
    
    // For service principal.
    // var tenantId = Environment.GetEnvironmentVariable("AZURE_COSMOS_TENANTID");
    // var clientId = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTID");
    // var clientSecret = Environment.GetEnvironmentVariable("AZURE_COSMOS_CLIENTSECRET");
    // var tokenProvider = new ClientSecretCredential(tenantId, clientId, clientSecret);
    
    // Acquire the access token. 
    AccessToken accessToken = await tokenProvider.GetTokenAsync(
        new TokenRequestContext(scopes: new string[]{ scope }));
    
    // Get the connection string.
    var httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken.Token}");
    var response = await httpClient.POSTAsync(listConnectionStringUrl);
    var responseBody = await response.Content.ReadAsStringAsync();
    var connectionStrings = JsonConvert.DeserializeObject<Dictionary<string, List<Dictionary<string, string>>>(responseBody);
    var connectionString = connectionStrings["connectionStrings"].Find(connStr => connStr["description"] == "Primary Table Connection String")["connectionString"];
    
    // Connect to Azure Cosmos DB for Table
    TableServiceClient tableServiceClient = new TableServiceClient(connectionString);
    

Nächste Schritte

Befolgen Sie die unten aufgeführten Tutorials, um mehr über Service Connector zu erfahren.