Compartilhar via


Integrar o Azure Cosmos DB for Table com o conector de serviço

Esta página mostra os métodos de autenticação e clientes com suporte, além de exibir um código de exemplo que você pode usar para conectar o Azure Cosmos DB for Table a outros serviços de nuvem utilizando o Conector de Serviço. Você ainda pode se conectar ao Azure Cosmos DB for Table em outras linguagens de programação sem usar o conector de serviço. Esta página também mostra nomes e valores de variáveis de ambiente padrão que você obtém ao criar a conexão de serviço.

Serviço de computação com suporte

O Conector de Serviço pode ser usado para conectar os seguintes serviços de computação ao Azure Cosmos DB for Table:

  • Serviço de Aplicativo do Azure
  • Aplicativos de Contêiner do Azure
  • Azure Functions
  • AKS (Serviço de Kubernetes do Azure)
  • Azure Spring Apps

Tipos de autenticação e tipos de cliente com suporte

A tabela abaixo mostra quais combinações de tipos de cliente e métodos de autenticação são suportadas para conectar seu serviço de computação ao Azure Cosmos DB for Table usando o Conector de Serviço. “Sim” indica que a combinação tem suporte e “Não” indica que ela não tem.

Tipo de cliente Identidade gerenciada atribuída pelo sistema Identidade gerenciada atribuída pelo usuário Cadeia de conexão/segredo Entidade de serviço
.NET Sim Sim Sim Sim
Java Sim Sim Sim Sim
Node.js Sim Sim Sim Sim
Python Sim Sim Sim Yes
Go Sim Sim Sim Yes
Nenhum Sim Sim Sim Yes

Essa tabela indica que todas as combinações de tipos de clientes e métodos de autenticação na tabela têm suporte. Todos os tipos de cliente podem usar qualquer um dos métodos de autenticação para se conectar ao Azure Cosmos DB for Table usando o Conector de Serviço.

Nomes de variáveis de ambiente padrão ou propriedades de aplicativo e código de exemplo

Use os detalhes de conexão abaixo para conectar seus serviços de computação ao Azure Cosmos DB for Table. Para cada exemplo abaixo, substitua os textos de espaço reservado <account-name>, <table-name>, <account-key>, <resource-group-name>, <subscription-ID>, <client-ID>, <client-secret>, <tenant-id> por suas próprias informações. Para saber mais sobre as convenções de nomenclatura, confira o artigo Detalhes internos no conector de serviço.

Identidade gerenciada atribuída pelo sistema

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTCONNECTIONSTRINGURL A URL para obter a cadeia de conexão 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 O escopo de sua identidade gerenciada https://management.azure.com/.default
AZURE_COSMOS_RESOURCEENDPOINT O ponto de extremidade do seu recurso https://<table-name>.documents.azure.com:443/

Código de exemplo

Consulte as etapas e o código abaixo para conectar-se ao Azure Cosmos DB for Table usando uma identidade gerenciada atribuída pelo sistema.

  1. Instale as dependências.
    dotnet add package Azure.Data.Tables
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerenciada ou entidade de serviço usando a biblioteca de clientes Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTCONNECTIONSTRINGURL para obter a cadeia de conexão. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Conector de Serviço e conecte-se ao Azure Cosmos DB for Table. Ao usar o código abaixo, descompacte a parte do snippet de código para o tipo de autenticação que você deseja usar.
    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);
    

Identidade gerenciada atribuída pelo usuário

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTCONNECTIONSTRINGURL A URL para obter a cadeia de conexão 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 O escopo de sua identidade gerenciada https://management.azure.com/.default
AZURE_COSMOS_CLIENTID Sua ID do segredo do cliente <client-ID>
AZURE_COSMOS_RESOURCEENDPOINT O ponto de extremidade do seu recurso https://<table-name>.documents.azure.com:443/

Código de exemplo

Consulte as etapas e o código abaixo para conectar-se ao Azure Cosmos DB for Table usando uma identidade gerenciada atribuída pelo usuário.

  1. Instale as dependências.
    dotnet add package Azure.Data.Tables
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerenciada ou entidade de serviço usando a biblioteca de clientes Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTCONNECTIONSTRINGURL para obter a cadeia de conexão. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Conector de Serviço e conecte-se ao Azure Cosmos DB for Table. Ao usar o código abaixo, descompacte a parte do snippet de código para o tipo de autenticação que você deseja usar.
    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);
    

Cadeia de conexão

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_CONNECTIONSTRING Cadeia de conexão do Azure Cosmos DB for Table DefaultEndpointsProtocol=https;AccountName=<account-name>;AccountKey=<account-key>;TableEndpoint=https://<table-name>.table.cosmos.azure.com:443/;

Aviso

A Microsoft recomenda usar o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste procedimento exige um grau muito alto de confiança no aplicativo e traz riscos que não estão presentes em outros fluxos. Você só deve usar esse fluxo quando outros fluxos mais seguros, como identidades gerenciadas, não forem viáveis.

Código de exemplo

Consulte as etapas e o código abaixo para conectar-se ao Azure Cosmos DB for Table usando uma cadeia de conexão.

  1. Instale a dependência.

    dotnet add package Azure.Data.Tables
    
  2. Obtenha a cadeia de conexão por meio da variável de ambiente adicionada pelo Conector de Serviço.

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

Entidade de serviço

Nome da variável de ambiente padrão Descrição Valor de exemplo
AZURE_COSMOS_LISTCONNECTIONSTRINGURL A URL para obter a cadeia de conexão 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 O escopo de sua identidade gerenciada https://management.azure.com/.default
AZURE_COSMOS_CLIENTID Sua ID do segredo do cliente <client-ID>
AZURE_COSMOS_CLIENTSECRET Seu segredo do cliente <client-secret>
AZURE_COSMOS_TENANTID Sua ID de locatário <tenant-ID>
AZURE_COSMOS_RESOURCEENDPOINT O ponto de extremidade do seu recurso https://<table-name>.documents.azure.com:443/

Código de exemplo

Consulte as etapas e o código abaixo para conectar-se ao Azure Cosmos DB for Table usando uma entidade de serviço.

  1. Instale as dependências.
    dotnet add package Azure.Data.Tables
    dotnet add package Azure.Identity
    
  2. Obtenha um token de acesso para a identidade gerenciada ou entidade de serviço usando a biblioteca de clientes Azure.Identity. Use o token de acesso e AZURE_COSMOS_LISTCONNECTIONSTRINGURL para obter a cadeia de conexão. Obtenha as informações de conexão das variáveis de ambiente adicionadas pelo Conector de Serviço e conecte-se ao Azure Cosmos DB for Table. Ao usar o código abaixo, descompacte a parte do snippet de código para o tipo de autenticação que você deseja usar.
    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);
    

Próximas etapas

Siga os tutoriais listados abaixo para saber mais sobre o Conector de Serviço.