快速入门:使用 .NET SDK 和 Azure Cosmos DB 生成表 API 应用

适用于: 表 API

本快速入门介绍如何使用 .NET 和 Azure Cosmos DB 表 API,通过克隆 GitHub 中的示例来生成应用。 此外,本快速入门还介绍了如何创建 Azure Cosmos DB 帐户,以及如何在基于 Web 的 Azure 门户中使用数据资源管理器创建表和实体。

先决条件

如果尚未安装 Visual Studio 2019,可以下载并使用 免费Visual Studio 2019 Community Edition。 在安装 Visual Studio 的过程中,请确保启用“Azure 开发”。

如果没有 Azure 试用版订阅,请在开始前创建一个试用版订阅

创建数据库帐户

  1. 在新浏览器窗口中,登录到 Azure 门户

  2. 在左侧菜单中,选择“创建资源”。

    在 Azure 门户中创建资源

  3. 在“新建”页上,选择“数据库” > “Azure Cosmos DB”。

    Azure 门户“数据库”窗格

  4. 在“创建 Azure Cosmos DB 帐户”页中,输入新 Azure Cosmos DB 帐户的设置。

    设置 说明
    订阅 你的订阅 选择要用于此 Azure Cosmos DB 帐户的 Azure 订阅。
    资源组 选择“新建”,然后选择“帐户名称” 选择“新建”。 然后输入帐户的新资源组名称。 为简单起见,请使用与 Azure Cosmos DB 帐户名称相同的名称。
    帐户名 唯一的名称 输入标识此 Azure Cosmos DB 帐户的唯一名称。

    帐户名称只能使用小写字母、数字及连字符 (-),必须为 3 到 31 个字符长。
    API API 确定要创建的帐户的类型。 Azure Cosmos DB 提供五种 API:Core(SQL)(适用于文档数据库)、Gremlin(适用于图数据库)、MongoDB(适用于文档数据库)、Azure 表和 Cassandra。 必须为每种 API 创建单独的帐户。

    选择“Azure 表”,因为在本快速入门中,将创建一个使用表 API 的表。

    详细了解表 API
    位置 离用户最近的区域 选择用于托管 Azure Cosmos DB 帐户的地理位置。 使用离用户最近的位置,使他们能够以最快的速度访问数据。
    容量模式 预配吞吐量或无服务器 选择“预配吞吐量”以在预配吞吐量模式下创建帐户。 选择“无服务器”以在无服务器模式下创建帐户。

    可以将“异地冗余”和“多区域写入”选项保留为“禁用”,避免产生额外的费用,并跳过“网络”和“标记”部分 。

  5. 选择“查看 + 创建”。 完成验证后,选择“创建”以创建帐户。

    Azure Cosmos DB 的“新建帐户”页面

  6. 创建帐户需要几分钟时间。 你将看到一条说明“部署正在进行”的消息。 等待部署完成,然后选择“转到资源”。

    Azure 门户“通知”窗格

添加表

现在可以在 Azure 门户中使用数据资源管理器工具来创建数据库和表。

  1. 依次选择“数据资源管理器” > “新建表” 。

    此时,最右侧将显示“添加表” 区域,可能需要向右滚动才能看到。

    Azure 门户中的数据资源管理器

  2. 在“添加表” 页上,输入新表的设置。

    设置 建议的值 说明
    表 ID sample-table 新表的 ID。 表名称与数据库 ID 的字符要求相同。 数据库名称的长度必须为 1 到 255 个字符,不能包含 / \ # ? 或尾随空格。
    吞吐量 400 RU 将吞吐量更改为每秒 400 个请求单位 (RU/s)。 如果想要减少延迟,以后可以增加吞吐量。
  3. 选择“确定” 。

  4. 数据资源管理器将显示新的数据库和表。

    显示新的数据库和集合的 Azure 门户数据资源管理器

添加示例数据

现在可以使用数据资源管理器将数据添加到新表。

  1. 在数据资源管理器中,展开 sample-table,选择“实体”,然后选择“添加实体”。

    在 Azure 门户的数据资源管理器中创建新实体

  2. 现在请将数据添加到 PartitionKey 值框和 RowKey 值框,然后选择“添加实体”。

    为新实体设置分区键和行键

    现在可以在数据资源管理器中将更多实体添加到表、编辑实体或查询数据。 使用数据资源管理器还可以缩放吞吐量,并将存储过程、用户定义的函数和触发器添加到表中。

克隆示例应用程序

现在让我们从 GitHub 克隆表应用,设置连接字符串,然后运行该应用。 会看到以编程方式处理数据是多么容易。

  1. 打开命令提示符,新建一个名为“git-samples”的文件夹,然后关闭命令提示符。

    md "C:\git-samples"
    
  2. 打开诸如 git bash 之类的 git 终端窗口,并使用 cd 命令更改为要安装示例应用的新文件夹。

    cd "C:\git-samples"
    
  3. 运行下列命令以克隆示例存储库。 此命令在计算机上创建示例应用程序的副本。

    git clone https://github.com/Azure-Samples/azure-cosmos-table-dotnet-core-getting-started.git
    

提示

有关类似代码的更详细演练,请参阅 Cosmos DB 表 API 示例一文。

在 Visual Studio 中打开示例应用程序

  1. 在 Visual Studio 的“文件”菜单中选择“打开”,然后选择“项目/解决方案”。

    打开解决方案

  2. 导航到示例应用程序所克隆到的文件夹,然后打开 TableStorage.sln 文件。

查看代码

此步骤是可选的。 如果有意了解如何使用代码创建数据库资源,可以查看以下代码片段。 否则,可以直接跳转到本文档的更新连接字符串部分。

  • 下面的代码演示如何在 Azure 存储中创建表:

    public static async Task<CloudTable> CreateTableAsync(string tableName)
    {
      string storageConnectionString = AppSettings.LoadAppSettings().StorageConnectionString;
    
      // Retrieve storage account information from connection string.
      CloudStorageAccount storageAccount = CreateStorageAccountFromConnectionString(storageConnectionString);
    
      // Create a table client for interacting with the table service
      CloudTableClient tableClient = storageAccount.CreateCloudTableClient(new TableClientConfiguration());
    
      Console.WriteLine("Create a Table for the demo");
    
      // Create a table client for interacting with the table service 
      CloudTable table = tableClient.GetTableReference(tableName);
      if (await table.CreateIfNotExistsAsync())
      {
          Console.WriteLine("Created Table named: {0}", tableName);
      }
      else
      {
          Console.WriteLine("Table {0} already exists", tableName);
      }
    
      Console.WriteLine();
      return table;
    }
    
    
  • 以下代码演示了如何在表中插入数据:

    public static async Task<CustomerEntity> InsertOrMergeEntityAsync(CloudTable table, CustomerEntity entity)
    {
      if (entity == null)
      {
          throw new ArgumentNullException("entity");
      }
    
      try
      {
          // Create the InsertOrReplace table operation
          TableOperation insertOrMergeOperation = TableOperation.InsertOrMerge(entity);
    
          // Execute the operation.
          TableResult result = await table.ExecuteAsync(insertOrMergeOperation);
          CustomerEntity insertedCustomer = result.Result as CustomerEntity;
    
          if (result.RequestCharge.HasValue)
          {
              Console.WriteLine("Request Charge of InsertOrMerge Operation: " + result.RequestCharge);
          }
    
          return insertedCustomer;
      }
      catch (StorageException e)
      {
          Console.WriteLine(e.Message);
          Console.ReadLine();
          throw;
      }
    }
    
    
  • 以下代码演示了如何查询表中的数据:

    public static async Task<CustomerEntity> RetrieveEntityUsingPointQueryAsync(CloudTable table, string partitionKey, string rowKey)
    {
      try
      {
          TableOperation retrieveOperation = TableOperation.Retrieve<CustomerEntity>(partitionKey, rowKey);
          TableResult result = await table.ExecuteAsync(retrieveOperation);
          CustomerEntity customer = result.Result as CustomerEntity;
          if (customer != null)
          {
              Console.WriteLine("\t{0}\t{1}\t{2}\t{3}", customer.PartitionKey, customer.RowKey, customer.Email, customer.PhoneNumber);
          }
    
          if (result.RequestCharge.HasValue)
          {
              Console.WriteLine("Request Charge of Retrieve Operation: " + result.RequestCharge);
          }
    
          return customer;
      }
      catch (StorageException e)
      {
          Console.WriteLine(e.Message);
          Console.ReadLine();
          throw;
      }
    }
    
    
  • 以下代码演示了如何删除表中的数据:

    public static async Task DeleteEntityAsync(CloudTable table, CustomerEntity deleteEntity)
    {
      try
      {
          if (deleteEntity == null)
          {
              throw new ArgumentNullException("deleteEntity");
          }
    
          TableOperation deleteOperation = TableOperation.Delete(deleteEntity);
          TableResult result = await table.ExecuteAsync(deleteOperation);
    
          if (result.RequestCharge.HasValue)
          {
              Console.WriteLine("Request Charge of Delete Operation: " + result.RequestCharge);
          }
    
      }
      catch (StorageException e)
      {
          Console.WriteLine(e.Message);
          Console.ReadLine();
          throw;
      }
    }
    
    

更新连接字符串

现在返回到 Azure 门户,获取连接字符串信息,并将其复制到应用。 这样,应用程序就可以与托管的数据库进行通信。

  1. Azure 门户中,单击“连接字符串”。 使用窗口右侧的复制按钮复制“主连接字符串”。

    在“连接字符串”窗格中查看并复制“主连接字符串”

  2. 在 Visual Studio 中打开 Settings.json 文件。

  3. 将门户中的“主连接字符串”粘贴到 StorageConnectionString 值中。 粘贴引号内的字符串。

    {
      "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. 按 CTRL+S 保存 Settings.json 文件。

现已使用与 Azure Cosmos DB 进行通信所需的所有信息更新应用。

生成并部署应用

  1. 在 Visual Studio 中,右键单击“解决方案资源管理器”中的“CosmosTableSamples”项目,然后单击“管理 NuGet 包”。

    管理 NuGet 包

  2. 在 NuGet 的“浏览”框中,键入 Microsoft.Azure.Cosmos.Table。 这样会查找 Cosmos DB 表 API 客户端库。 请注意,此库目前仅适用于 .NET Framework 和 .NET Standard。

    NuGet 的“浏览”选项卡

  3. 单击“安装”以安装 Microsoft.Azure.Cosmos.Table 库。 这会安装 Azure Cosmos DB 表 API 包和所有依赖项。

  4. 运行整个应用时,示例数据将插入到表实体中,运行结束时会删除这些数据,因此,如果运行整个示例,你将看不到插入的任何数据。 但是,可以插入一些断点来查看数据。 打开 BasicSamples.cs 文件并右键单击第 52 行,选择“断点”,然后选择“插入断点”。 在第 55 行中插入另一个断点。

    添加断点

  5. 按 F5 运行应用程序。 控制台窗口会显示 Azure Cosmos DB 中新的表数据库的名称(在本例中为 demoa13b1)。

    控制台输出

    点击第一个断点后,返回到 Azure 门户中的数据资源管理器。 单击“刷新”按钮,展开 demo* 表,然后单击“实体”。 右侧的“实体”选项卡将显示为 Walter Harp 添加的新实体。 请注意,新实体的电话号码为 425-555-0101。

    新建实体

    如果收到说明在运行项目时无法找到 Settings.json 文件的错误,可以通过将以下 XML 条目添加到项目设置来解决该问题。 右键单击 CosmosTableSamples,选择“编辑 CosmosTableSamples.csproj”并添加以下 itemGroup:

     <ItemGroup>
       <None Update="Settings.json">
         <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
       </None>
     </ItemGroup>
    
  6. 关闭数据资源管理器中的“实体”选项卡。

  7. 按 F5,运行应用到下一个断点。

    点击该断点后,切换回 Azure 门户,再次单击“实体”以打开“实体”选项卡,请注意该电话号码已更新为 425-555-0105。

  8. 按 F5 运行该应用。

    该应用添加的实体可在表 API 目前不支持的高级示例应用中使用。 该应用然后会删除示例应用创建的表。

  9. 在控制台窗口中,按 Enter 结束应用的执行。

在 Azure 门户中查看 SLA

Azure 门户监视 Cosmos DB 帐户吞吐量、存储、可用性、延迟和一致性。 与 Azure Cosmos DB 服务级别协议 (SLA) 关联的指标的图表显示与实际性能相比的 SLA 值。 此套指标使得监视 SLA 十分透明。

若要查看指标和 SLA,请执行以下操作:

  1. 在 Cosmos DB 帐户的导航菜单中选择“指标” 。

  2. 选择一个选项卡,如“延迟” ,然后选择右侧的时间范围。 比较图表上的“实际” 和“SLA” 线。

    Azure Cosmos DB 指标套件

  3. 查看其他选项卡上的指标。

清理资源

执行完应用和 Azure Cosmos DB 帐户的操作以后,可以删除所创建的 Azure 资源,以免产生更多费用。 若要删除资源,请执行以下操作:

  1. 在 Azure 门户的“搜索”栏中,搜索并选择“资源组” 。

  2. 从列表中选择为本快速入门创建的资源组。

    选择要删除的资源组

  3. 在资源组“概览”页上,选择“删除资源组” 。

    删除资源组

  4. 在下一窗口中输入要删除的资源组的名称,然后选择“删除” 。

后续步骤

在本快速入门教程中,已了解如何创建 Azure Cosmos DB 帐户、使用数据资源管理器创建表和运行应用。 现在可以使用表 API 进行数据查询了。