快速入門:使用 .NET SDK 與 Azure Cosmos DB 建置資料表 API 應用程式Quickstart: Build a Table API app with .NET SDK and Azure Cosmos DB

本快速入門示範如何使用 .NET 與 Azure Cosmos DB 資料表 API,透過從 GitHub 複製範例來建置應用程式。This quickstart shows how to use .NET and the Azure Cosmos DB Table API to build an app by cloning an example from GitHub. 本快速入門也會示範如何建立 Azure Cosmos DB 帳戶,以及如何使用資料總管在以 Web 為基礎的 Azure 入口網站中建立資料表和實體。This quickstart also shows you how to create an Azure Cosmos DB account and how to use Data Explorer to create tables and entities in the web-based Azure portal.

必要條件Prerequisites

如果尚未安裝 Visual Studio 2019,您可以下載並使用免費的 Visual Studio 2019 Community 版本If you don’t already have Visual Studio 2019 installed, you can download and use the free Visual Studio 2019 Community Edition. 務必在 Visual Studio 設定期間啟用 Azure 開發Make sure that you enable Azure development during the Visual Studio setup.

如果您沒有 Azure 訂用帳戶,請在開始前建立免費帳戶If you don't have an Azure subscription, create a free account before you begin.

建立資料庫帳戶Create a database account

  1. 在新的瀏覽器視窗中,登入 Azure 入口網站In a new browser window, sign in to the Azure portal.

  2. 在左側導覽窗格中,選取 [建立資源] 。In the left navigation pane, select Create a resource. 選取 [資料庫] ,然後選取 [Azure Cosmos DB] 。Select Databases and then select Azure Cosmos DB.

    Azure 入口網站的螢幕擷取畫面,其中反白顯示 [其他服務] 和 Azure Cosmos DB

  3. 在 [建立 Azure Cosmos DB 帳戶] 頁面上,輸入新 Azure Cosmos DB 帳戶的設定:On the Create Azure Cosmos DB Account page, enter the settings for the new Azure Cosmos DB account:

    設定Setting Value 說明Description
    訂用帳戶Subscription 您的訂用帳戶Your subscription 選取要用於此 Azure Cosmos DB 帳戶的 Azure 訂用帳戶。Select the Azure subscription that you want to use for this Azure Cosmos DB account.
    資源群組Resource Group 新建Create new

    然後輸入識別碼中所提供的同一個唯一名稱Then enter the same unique name as provided in ID
    選取 [建立新的] 。Select Create new. 然後為您的帳戶輸入新的資源群組名稱。Then enter a new resource group name for your account. 為求簡化,請使用和識別碼相同的名稱。For simplicity, use the same name as your ID.
    帳戶名稱Account Name 輸入唯一名稱Enter a unique name 輸入唯一名稱來識別您的 Azure Cosmos DB 帳戶。Enter a unique name to identify your Azure Cosmos DB account.

    識別碼只能使用小寫字母、數字及連字號 (-) 字元。The ID can use only lowercase letters, numbers, and the hyphen (-) character. 其長度必須介於 3 到 31 個字元之間。It must be between 3 and 31 characters long.
    APIAPI Azure 資料表Azure Table API 會決定要建立的帳戶類型。The API determines the type of account to create. Azure Cosmos DB 提供五個 API:Core(SQL) (適用於文件資料庫)、Gremlin (適用於圖形資料庫)、MongoDB (適用於文件資料庫)、「Azure 資料表」及 Cassandra。Azure Cosmos DB provides five APIs: Core(SQL) for document databases, Gremlin for graph databases, MongoDB for document databases, Azure Table, and Cassandra. 目前,您必須為每個 API 建立個別個帳戶。Currently, you must create a separate account for each API.

    選取 [Azure 資料表] ,因為在本快速入門中,您會建立可搭配資料表 API 使用的資料表。Select Azure Table because in this quickstart you're creating a table that works with the Table API.

    深入了解資料表 APILearn more about the Table API.
    位置Location 選取最接近使用者的區域Select the region closest to your users 選取用來裝載 Azure Cosmos DB 帳戶的地理位置。Select a geographic location to host your Azure Cosmos DB account. 使用最接近使用者的位置,讓他們能以最快速度存取資料。Use the location that's closest to your users to give them the fastest access to data.

    您可以保留 [異地備援] 和 [多重區域寫入] 選項的預設值 ([停用] ) 以避免產生額外的 RU 費用。You can leave the Geo-Redundancy and Multi-region Writes options at their default values (Disable) to avoid additional RU charges. 您可以略過 [網路] 和 [標記] 區段。You can skip the Network and Tags sections.

  4. 請選取 [檢閱 + 建立] 。Select Review+Create. 驗證完成之後,請選取 [建立] 來建立帳戶。After the validation is complete, select Create to create the account.

    Azure Cosmos DB 的新帳戶頁面

  5. 建立帳戶需要幾分鐘的時間。It takes a few minutes to create the account. 您將會看到一個訊息,指出 [您的部署正在進行] 。You'll see a message that states Your deployment is underway. 等待部署完成,然後選取 [前往資源] 。Wait for the deployment to finish and then select Go to resource.

    Azure 入口網站的 [通知] 窗格

新增資料表Add a table

您現在可以在 Azure 入口網站中使用 [資料總管] 工具,建立資料庫和資料表。You can now use the Data Explorer tool in the Azure portal to create a database and table.

  1. 選取 [資料總管] > [新增資料表] 。Select Data Explorer > New Table.

    [新增資料表] 區域會顯示在最右邊,您可能需要向右捲動才會看到。The Add Table area is displayed on the far right, you may need to scroll right to see it.

    Azure 入口網站中的資料總管

  2. 在 [新增資料表] 頁面中,輸入新資料表的設定。In the Add Table page, enter the settings for the new table.

    設定Setting 建議的值Suggested value 說明Description
    資料表識別碼Table Id sample-tablesample-table 新資料表的識別碼。The ID for your new table. 資料表名稱與資料庫識別碼具有相同的字元需求。Table names have the same character requirements as database ids. 資料庫名稱的長度必須介於 1 到 255 個字元,且不能包含 / \ # ? 或尾端空格。Database names must be between 1 and 255 characters, and cannot contain / \ # ? or a trailing space.
    ThroughputThroughput 400 RU400 RUs 將輸送量變更為每秒 400 個要求單位 (RU/秒)。Change the throughput to 400 request units per second (RU/s). 如果您想要降低延遲,稍後可以相應增加輸送量。If you want to reduce latency, you can scale up the throughput later.
  3. 選取 [確定] 。Select OK.

  4. [資料總管] 會顯示新的資料庫和資料表。Data Explorer displays the new database and table.

    Azure 入口網站 [資料總管],顯示新的資料庫和集合

新增範例資料Add sample data

您現在可以使用資料總管將資料新增至您的新資料表。You can now add data to your new table using Data Explorer.

  1. 在資料總管中,展開 sample-table,選取 [實體] ,然後選取 [新增實體] 。In Data Explorer, expand sample-table, select Entities, and then select Add Entity.

    在 Azure 入口網站的 [資料總管] 中建立新實體

  2. 現在,將資料新增至 PartitionKey 值方塊和 RowKey 值方塊,然後選取 [新增實體] 。Now add data to the PartitionKey value box and RowKey value box, and select Add Entity.

    為新的實體設定磁碟分割索引鍵和資料列索引鍵

    您現在可以在資料表中新增更多實體、編輯實體,或在資料總管中查詢資料。You can now add more entities to your table, edit your entities, or query your data in Data Explorer. 資料總管也可供您縮放輸送量,以及對資料表新增預存程序、使用者定義函式和觸發程序。Data Explorer is also where you can scale your throughput and add stored procedures, user-defined functions, and triggers to your table.

複製範例應用程式Clone the sample application

現在,我們將從 GitHub 複製「資料表」應用程式、設定連接字串,然後加以執行。Now let's clone a Table app from GitHub, set the connection string, and run it. 您會看到,以程式設計方式來處理資料有多麼的容易。You'll see how easy it is to work with data programmatically.

  1. 開啟命令提示字元,建立名為 git-samples 的新資料夾,然後關閉命令提示字元。Open a command prompt, create a new folder named git-samples, then close the command prompt.

    md "C:\git-samples"
    
  2. 開啟 git 終端機視窗 (例如 git bash),並使用 cd 命令變更至要安裝範例應用程式的新資料夾。Open a git terminal window, such as git bash, and use the cd command to change to the new folder to install the sample app.

    cd "C:\git-samples"
    
  3. 執行下列命令來複製範例存放庫。Run the following command to clone the sample repository. 此命令會在您的電腦上建立範例應用程式副本。This command creates a copy of the sample app on your computer.

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

在 Visual Studio 中開啟範例應用程式Open the sample application in Visual Studio

  1. 在 Visual Studio 中,從 [檔案] 功能表上,選擇 [開啟] ,然後選擇 [專案/解決方案] 。In Visual Studio, from the File menu, choose Open, then choose Project/Solution.

    開啟解決方案

  2. 瀏覽至您複製範例應用程式的資料夾,然後開啟 TableStorage.sln 檔案。Navigate to the folder where you cloned the sample application and open the TableStorage.sln file.

更新您的連接字串Update your connection string

現在,返回 Azure 入口網站以取得連接字串資訊,並將它複製到應用程式中。Now go back to the Azure portal to get your connection string information and copy it into the app. 這可讓您的應用程式與託管資料庫進行通訊。This enables your app to communicate with your hosted database.

  1. Azure 入口網站中,按一下 [連接字串] 。In the Azure portal, click Connection String. 使用視窗右方的複製按鈕來複製主要連接字串Use the copy button on the right side of the window to copy the PRIMARY CONNECTION STRING.

    在 [連接字串] 窗格中檢視及複製主要連接字串

  2. 在 Visual Studio 中開啟 Settings.json 檔案。In Visual Studio, open the Settings.json file.

  3. 將來自入口網站的主要連接字串貼到 StorageConnectionString 值中。Paste the PRIMARY CONNECTION STRING from the portal into the StorageConnectionString value. 在引號內貼上字串。Paste the string inside the quotes.

    {
       "StorageConnectionString": "<Primary connection string from Azure portal>"
    }
    
  4. 按下 CTRL + S,以儲存 Settings.json 檔案。Press CTRL+S to save the Settings.json file.

您現已更新應用程式,使其具有與 Azure Cosmos DB 通訊所需的所有資訊。You've now updated your app with all the info it needs to communicate with Azure Cosmos DB.

建置並部署應用程式Build and deploy the app

  1. 在 Visual Studio 中,於 [方案總管] 中的 CosmosTableSamples 專案上按一下滑鼠右鍵,然後按一下 [管理 NuGet 套件] 。In Visual Studio, right-click on the CosmosTableSamples project in Solution Explorer and then click Manage NuGet Packages.

    Manage NuGet Packages

  2. 在 NuGet [瀏覽] 方塊中,輸入Microsoft.Azure.Cosmos.Table。In the NuGet Browse box, type Microsoft.Azure.Cosmos.Table. 這會尋找 Cosmos DB 資料表 API 用戶端程式庫。This will find the Cosmos DB Table API client library. 請注意,此文件庫目前僅適用於 .NET Framework 與 .NET Standard。Note that this library is currently available for .NET Framework and .NET Standard.

    [NuGet 瀏覽] 索引標籤

  3. 按一下 [安裝] 可安裝 Microsoft.Azure.Cosmos.Table 程式庫。Click Install to install the Microsoft.Azure.Cosmos.Table library. 這會安裝 Azure Cosmos DB 資料表 API 套件以及所有相依性。This installs the Azure Cosmos DB Table API package and all dependencies.

  4. 當您執行整個應用程式時,會將範例資料插入資料表實體,並於結束時刪除,因此如果您執行完整的範例,並不會看到插入任何資料。When you run the entire app, sample data is inserted into the table entity and deleted at the end so you won’t see any data inserted if you run the whole sample. 不過,您可以插入一些中斷點來檢視資料。However you can insert some breakpoints to view the data. 開啟 BasicSamples.cs 檔案,然後以滑鼠右鍵按一下第 52 行,選取 [中斷點] ,然後選取 [插入中斷點] 。Open BasicSamples.cs file and right-click on line 52, select Breakpoint, then select Insert Breakpoint. 在第 55 行上插入另一個中斷點。Insert another breakpoint on line 55.

    新增中斷點

  5. 按 F5 執行應用程式。Press F5 to run the application. 主控台視窗會顯示 Azure Cosmos DB 中新資料表資料庫的名稱 (在此情況下為 demoa13b1)。The console window displays the name of the new table database (in this case, demoa13b1) in Azure Cosmos DB.

    主控台輸出

    到達第一個中斷點時,請回到 Azure 入口網站中的 [資料總管]。When you hit the first breakpoint, go back to Data Explorer in the Azure portal. 按一下 [重新整理] 按鈕、展開示範 * 資料表,然後按一下 [實體] 。Click the Refresh button, expand the demo* table, and click Entities. 右側的 [實體] 索引標籤會顯示針對 Walter Harp 新增的新實體。The Entities tab on the right shows the new entity that was added for Walter Harp. 請注意,新實體的電話號碼為 425-555-0101。Note that the phone number for the new entity is 425-555-0101.

    新的實體

    如果您收到錯誤,指出執行專案時找不到 Settings.json 檔案,您可以將下列 XML 項目新增至專案設定來解決該問題。If you receive an error that says Settings.json file can’t be found when running the project, you can resolve it by adding the following XML entry to the project settings. 以滑鼠右鍵按一下 [CosmosTableSamples]、選取 [編輯 CosmosTableSamples.csproj],然後新增下列 itemGroup:Right click on CosmosTableSamples, select Edit CosmosTableSamples.csproj and add the following itemGroup:

      <ItemGroup>
        <None Update="Settings.json">
          <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
        </None>
      </ItemGroup>
    
  6. 關閉 [資料總管] 中的 [實體] 索引標籤。Close the Entities tab in Data Explorer.

  7. 按 F5 執行應用程式到下一個中斷點。Press F5 to run the app to the next breakpoint.

    到達中斷點時,請切換回 Azure 入口網站,再按一下 [實體] 可開啟 [實體] 索引標籤,並請注意,電話號碼已經更新為 425-555-0105。When you hit the breakpoint, switch back to the Azure portal, click Entities again to open the Entities tab, and note that the phone number has been updated to 425-555-0105.

  8. 按 F5 以執行應用程式。Press F5 to run the app.

    應用程式會新增實體,以在資料表 API 目前不支援的進階範例應用程式中使用。The app adds entities for use in an advanced sample app that the Table API currently does not support. 然後,應用程式會刪除範例應用程式所建立的資料表。The app then deletes the table created by the sample app.

  9. 在主控台視窗中,按下 Enter 可結束執行應用程式。In the console window, press Enter to end the execution of the app.

在 Azure 入口網站中檢閱 SLAReview SLAs in the Azure portal

Azure 入口網站會監視您的 Cosmos DB 帳戶輸送量、儲存體、可用性、延遲和一致性。The Azure portal monitors your Cosmos DB account throughput, storage, availability, latency, and consistency. Azure Cosmos DB 服務等級協定 (SLA) 相關聯的計量圖表會顯示相較於實際效能的 SLA 值。Charts for metrics associated with an Azure Cosmos DB Service Level Agreement (SLA) show the SLA value compared to actual performance. 此計量套件可讓您以更透明的方式監視監視 SLA。This suite of metrics makes monitoring your SLAs transparent.

若要檢閱計量和 SLA:To review metrics and SLAs:

  1. 在您的 Cosmos DB 帳戶導覽功能表中,選取 [計量] 。Select Metrics in your Cosmos DB account's navigation menu.

  2. 選取一個索引標籤 (例如 [延遲] ),並在右側選取時間範圍。Select a tab such as Latency, and select a timeframe on the right. 比較圖表中的實際SLA 的資料行。Compare the Actual and SLA lines on the charts.

    Azure Cosmos DB 計量套件

  3. 檢閱其他索引標籤中的計量。Review the metrics on the other tabs.

清除資源Clean up resources

完成您的 Web 應用程式和 Azure Cosmos DB 帳戶之後,您可以將建立的 Azure 資源刪除,以免產生更多費用。When you're done with your web app and Azure Cosmos DB account, you can delete the Azure resources you created so you don't incur more charges. 若要刪除資源:To delete the resources:

  1. 在 Azure 入口網站中,選取最左邊的 [資源群組] 。In the Azure portal, select Resource groups on the far left. 若已摺疊左側功能表,請選取展開按鈕加以展開。If the left menu is collapsed, select Expand button to expand it.

  2. 選取您在本快速入門中建立的資源群組。Select the resource group you created for this quickstart.

    選取要刪除的資源群組

  3. 在新視窗中,選取 [刪除資源群組] 。In the new window, select Delete resource group.

    刪除資源群組

  4. 在下個視窗中輸入要刪除的資源群組名稱,然後選取 [刪除] 。In the next window, enter the name of the resource group to delete, and then select Delete.

後續步驟Next steps

在本快速入門中,您已了解如何建立 Azure Cosmos DB 帳戶、如何使用資料總管來建立資料表,以及如何執行應用程式。In this quickstart, you've learned how to create an Azure Cosmos DB account, create a table using the Data Explorer, and run an app. 現在,您可以使用資料表 API 來查詢您的資料。Now you can query your data using the Table API.