快速入門：使用 .NET Core 和 Azure Cosmos DB 建置 Cassandra 應用程式

文章
08/15/2024

適用於： Cassandra

本快速入門示範如何使用 .NET Core 與 Azure Cosmos DB API for Cassandra，以藉由從 GitHub 複製範例來建置設定檔應用程式。此快速入門也會示範如何使用 Web 型 Azure 入口網站來建立 Azure Cosmos DB 帳戶。

Azure Cosmos DB 為 Microsoft 的全域散發多重模型資料庫服務。您可以快速建立及查詢文件、資料表、索引鍵/值及圖形資料庫，所有這些都受惠於位於 Azure Cosmos DB 核心的全域散發和水平調整功能。

必要條件

如果您沒有 Azure 訂用帳戶，請在開始之前先建立 Azure 免費帳戶。或者，您可以免費試用 Azure Cosmos DB，無須 Azure 訂用帳戶，也無須任何費用和約定付款。

此外，您需要：

使用 Azure 開發工作負載的最新 Visual Studio。您可以開始使用 免費的 Visual Studio Community IDE。在 Visual Studio 設定期間啟用 Azure 開發工作負載。
安裝 Git 來複製範例。

建立資料庫帳戶

從 Azure 入口網站功能表或 [首頁] 頁面，選取 [建立資源]。
在 [新增] 頁面上，搜尋並選取 [Azure Cosmos DB]。
在 [Azure Cosmos DB] 頁面上，選取 [建立]。
在 [API] 頁面上的 [Cassandra] 區段下面，選取 [建立]。

API 會決定要建立的帳戶類型。 Azure Cosmos DB 提供五個 API：NoSQL (適用於文件資料庫)、Gremlin (適用於圖形資料庫)、MongoDB (適用於文件資料庫)、Azure 資料表與 Cassandra。您必須為每個 API 建立個別帳戶。

選取 [Cassandra]，因為在此快速入門中，您會建立可搭配 API for Cassandra 使用的資料表。

深入了解適用於 Cassandra 的 API。

在 [建立 Azure Cosmos DB 帳戶] 頁面中，輸入新 Azure Cosmos DB 帳戶的基本設定。

設定	值	Description
訂用帳戶	您的訂用帳戶	選取您要用於此 Azure Cosmos DB 帳戶的 Azure 訂用帳戶。
資源群組	新建然後，輸入與帳戶名稱相同的名稱	選取 [新建] 然後為您的帳戶輸入新的資源群組名稱。為求簡化，請使用與 Azure Cosmos DB 帳戶名稱相同的名稱。
客戶名稱	輸入唯一名稱	輸入唯一名稱來識別您的 Azure Cosmos DB 帳戶。您的帳戶 URI 將是 cassandra.cosmos.azure.com，並附加至您的唯一帳戶名稱。帳戶名稱只能使用小寫字母、數字和連字號 (-)，且長度必須介於 3 到 31 個字元之間。
Location	最接近使用者的區域	選取用來裝載 Azure Cosmos DB 帳戶的地理位置。使用最接近使用者的位置，讓他們能以最快速度存取資料。
容量模式	佈建輸送量或無伺服器	選取 [佈建的輸送量]，以佈建的輸送量模式建立帳戶。選取 [無伺服器]，以無伺服器模式建立帳戶。
申請 Azure Cosmos DB 免費階層折扣	適用或不適用	使用 Azure Cosmos DB 免費層，您將可在帳戶中免費取得前 1000 RU/秒和 25 GB 的儲存體。深入了解免費層。
限制帳戶總輸送量	選取此選項會限制帳戶的輸送量	如果您想要將帳戶的總輸送量限制為特定值，這會很有用。

注意

每個 Azure 訂用帳戶最多可以有一個免費層的 Azure Cosmos DB 帳戶，而且必須在建立帳戶時選擇加入。如果您看不到套用免費層折扣的選項，這表示訂用帳戶中的另一個帳戶已透過免費層啟用。

適用於 Apache Cassandra 的 Azure Cosmos DB 新帳戶頁面

在 [全域散發] 索引標籤中，設定下列詳細資料。您可以保留預設值，以供本快速入門的目的之用：

設定	值	Description
異地備援	停用	藉由將您的區域與配對區域進行配對，在您的帳戶上啟用或停用全域散發。您可以在稍後將更多區域新增至您的帳戶。
多重區域寫入	停用	多重區域寫入功能可讓您利用在全球為資料庫及容器佈建的輸送量。
可用性區域	停用	可用性區域是 Azure 區域內的隔離位置。每個區域都是由一或多個資料中心所組成，配備了獨立的電力、冷卻系統及網路系統。

注意

如果您選取 [無伺服器] 作為容量模式，則無法使用下列選項：

套用免費層折扣
異地備援
多重區域寫入

(選擇性) 您可以在下列索引標籤中設定其他詳細資料：
- 網路 - 設定從虛擬網路存取。
- 備份原則 - 設定定期或連續備份原則。
- 加密 - 使用服務管理的金鑰或客戶自控金鑰。
- 標籤 - 標籤為成對的名稱和值，可讓您將相同的標籤套用至多個資源與資源群組，以便為資源分類及檢視合併的帳單。
選取 [檢閱 + 建立]。
檢閱帳戶設定，然後選取 [建立]。建立帳戶需要幾分鐘的時間。請等候入口網站頁面顯示 [您的部署已完成]。
選取 [前往資源] 前往 Azure Cosmos DB 帳戶頁面。

複製範例應用程式

現在讓我們切換為使用程式碼。我們將從 GitHub 複製適用於 Cassandra 應用程式的 API、設定連接字串，然後加以執行。您會看到，以程式設計方式來處理資料有多麼的容易。

開啟命令提示字元。建立名為 git-samples 的新資料夾。接著，關閉命令提示字元。
```
md "C:\git-samples"
```
開啟 git 終端機視窗 (例如 git bash)，並使用 cd 命令變更至要安裝範例應用程式的新資料夾。
```
cd "C:\git-samples"
```
執行下列命令來複製範例存放庫。此命令會在您的電腦上建立範例應用程式副本。
```
git clone https://github.com/Azure-Samples/azure-cosmos-db-cassandra-dotnet-core-getting-started.git
```
接下來，在 Visual Studio 中開啟 CassandraQuickStartSample 方案檔。

檢閱程式碼

此步驟是選擇性的。如果您有興趣了解程式碼如何建立資料庫資源，您可以檢閱下列程式碼片段。這些片段全都取自 Program.cs 檔案的 async Task ProcessAsync() 方法，該檔案安裝於 C:\git-samples\azure-cosmos-db-cassandra-dotnet-core-getting-started\CassandraQuickStart 資料夾。或者也可以直接跳至更新您的連接字串。

連線到 Cassandra 叢集端點以初始化工作階段。 Azure Cosmos DB 上適用於 Cassandra 的 API 僅支援 TLSv1.2。

var options = new Cassandra.SSLOptions(SslProtocols.Tls12, true, ValidateServerCertificate);
options.SetHostNameResolver((ipAddress) => CASSANDRACONTACTPOINT);
Cluster cluster = Cluster
    .Builder()
    .WithCredentials(USERNAME, PASSWORD)
    .WithPort(CASSANDRAPORT)
    .AddContactPoint(CASSANDRACONTACTPOINT)
    .WithSSL(options)
    .Build()
;
ISession session = await cluster.ConnectAsync();

如果已存在現有的 keyspace，則將其卸除。

await session.ExecuteAsync(new SimpleStatement("DROP KEYSPACE IF EXISTS uprofile"));

建立新的 keyspace。

await session.ExecuteAsync(new SimpleStatement("CREATE KEYSPACE uprofile WITH REPLICATION = { 'class' : 'NetworkTopologyStrategy', 'datacenter1' : 1 };"));

建立新表格。

await session.ExecuteAsync(new SimpleStatement("CREATE TABLE IF NOT EXISTS uprofile.user (user_id int PRIMARY KEY, user_name text, user_bcity text)"));

使用 IMapper 物件搭配連線到 uprofile keyspace 的新工作階段來插入使用者實體。
```
await mapper.InsertAsync<User>(new User(1, "LyubovK", "Dubai"));
```

取得所有使用者資訊的查詢。

foreach (User user in await mapper.FetchAsync<User>("Select * from user"))
{
    Console.WriteLine(user);
}

取得單一使用者資訊的查詢。

mapper.FirstOrDefault<User>("Select * from user where user_id = ?", 3);

更新您的連接字串

現在，返回 Azure 入口網站以取得連接字串資訊，並將它複製到應用程式中。連接字串資訊可讓您的應用程式與託管資料庫進行通訊。

在 Azure 入口網站中，選取 [連接字串]。
使用位於螢幕右側的按鈕來複製 [使用者名稱] 值。
在 Visual Studio 中，開啟 Program.cs 檔案。
從入口網站將 [使用者名稱] 值貼到 <PROVIDE> 的行 13。

Program.cs 的行 13 現應如下所示

private const string UserName = "cosmos-db-quickstart";

您也可以針對接觸點的值，在第 15 行的 <PROVIDE> 貼上相同的值：

private const string CassandraContactPoint = "cosmos-db-quickstarts.cassandra.cosmosdb.azure.com"; // DnsName
返回入口網站，並複製 [密碼] 值。從入口網站將 [密碼] 值貼到 <PROVIDE> 的行 14。

Program.cs 的行 14 現應如下所示

private const string Password = "2Ggkr662ifxz2Mg...==";
返回入口網站，並複製 [連絡點] 值。從入口網站將 [連絡點] 值貼到第 16 行上的 <PROVIDE>。

Program.cs 的第 16 行現應如下所示

private const string CASSANDRACONTACTPOINT = "quickstart-cassandra-api.cassandra.cosmos.azure.com";
儲存 Program.cs 檔案。

執行 .NET Core 應用程式

在 Visual Studio 中，選取工具>NuGet 套件管理員>套件管理器主控台。
在命令提示字元中，使用下列命令來安裝 .NET 驅動程式的 NuGet 套件。
```
Install-Package CassandraCSharpDriver
```
按 CTRL + F5 來執行應用程式。您的應用程式會顯示在主控台視窗中。

按 CTRL + C 來停止執行程式，並關閉主控台視窗。
在 Azure 入口網站中，開啟 [資料總管] 以查詢、修改及使用這個新資料。