hızlı başlangıç: Azure Cosmos DB SQL apı hesabı kaynaklarını yönetmek için .net V4 SDK 'sını (önizleme) kullanarak bir konsol uygulaması oluşturma
UYGULANDıĞı YER:
SQL API
.net için Azure Cosmos DB SQL apı istemci kitaplığı ile çalışmaya başlayın. .net V4 (Azure. Cosmos) paketini yüklemek ve bir uygulama oluşturmak için bu makaledeki adımları izleyin. daha sonra, Azure Cosmos DB depolanan verilerde temel oluşturma, okuma, güncelleştirme ve silme (crud) işlemleri için örnek kodu deneyin.
Önemli
Azure Cosmos DB için .net V4 SDK 'sı şu anda genel önizlemededir. Bu önizleme sürümü bir hizmet düzeyi sözleşmesi olmadan sağlanır ve bunu üretim iş yükleri için önermiyoruz. Bazı özellikler desteklenmiyor olabileceği gibi özellikleri sınırlandırılmış da olabilir.
Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.
Azure Cosmos DB, Microsoft 'un herhangi bir ölçekte açık apı 'leri olan hızlı nosql veritabanıdır. anahtar/değer, belge ve grafik veritabanlarını hızlıca oluşturmak ve sorgulamak için Azure Cosmos DB kullanabilirsiniz. .net için Azure Cosmos DB SQL apı istemci kitaplığını kullanın:
- Azure Cosmos veritabanı ve kapsayıcısı oluşturun.
- Kapsayıcıya örnek veriler ekleyin.
- Verileri sorgulayın.
- Veritabanını silin.
Kitaplık kaynak kodu | Paket (NuGet)
Önkoşullar
- Azure aboneliği. Ücretsiz bir tane oluşturun. ayrıca, Azure aboneliği olmadan Azure Cosmos DB deneyebilir , ücretsiz ve taahhütlere sahip olabilirsiniz.
- NET Core 3 SDK. Çalıştırıp ortamınızda hangi sürümün kullanılabilir olduğunu doğrulayabilirsiniz
dotnet --version.
Kurulum
bu bölümde, kaynakları yönetmek üzere .net için Azure Cosmos DB SQL apı istemci kitaplığı 'nı kullanan bir Azure Cosmos hesabı oluşturma ve bir proje ayarlama işlemi adım adım açıklanmaktadır.
Bu makalede açıklanan örnek kod, bu FamilyDatabase veritabanı içinde bir veritabanı ve aile üyeleri oluşturur. Her aile üyesi bir öğedir ve,,,,, ve gibi özelliklere sahiptir Id FamilyName FirstName LastName Parents Children Address . LastNameÖzelliği kapsayıcı için bölüm anahtarı olarak kullanılır.
Azure Cosmos hesabı oluşturma
azure Cosmos hesabı oluşturmak için ücretsiz deneme Azure Cosmos DB seçeneğini kullanırsanız, SQL apı türünde bir azure Cosmos hesabı oluşturmanız gerekir. sizin için bir Azure Cosmos test hesabı zaten oluşturulmuş. Hesabı açıkça oluşturmanız gerekmez; bu sayede bu bölümü atlayabilir ve sonraki bölüme geçebilirsiniz.
kendi azure aboneliğiniz varsa veya ücretsiz bir abonelik oluşturduysanız, açıkça bir azure Cosmos hesabı oluşturmanız gerekir. aşağıdaki kod, oturum tutarlılığı olan bir Azure Cosmos hesabı oluşturacaktır. Hesap ve ' de çoğaltılır South Central US North Central US .
Azure Cosmos hesabını oluşturmak için Azure Cloud Shell kullanabilirsiniz. Azure Cloud Shell, Azure kaynaklarını yönetmek için kullanabileceğiniz etkileşimli, kimliği doğrulanmış ve tarayıcı ile erişilebilen bir kabuktur. Çalışma biçiminize en uygun kabuk deneyimini seçme esnekliği sağlar: bash veya PowerShell.
Bu hızlı başlangıç için bash kullanın. Azure Cloud Shell Ayrıca bir depolama hesabı gerektirir. İstendiğinde bir tane oluşturabilirsiniz.
Aşağıdaki kodun yanındaki deneyin düğmesini seçin, Bash modu ' nu seçin, depolama hesabı oluştur' u seçin ve Cloud Shell için oturum açın.
Aşağıdaki kodu kopyalayıp Azure Cloud Shell ve çalıştırmak için yapıştırın. Azure Cosmos hesap adı genel olarak benzersiz olmalıdır; bu nedenle,
mysqlapicosmosdbkomutu çalıştırmadan önce değeri güncelleştirdiğinizden emin olun.# Set variables for the new SQL API account, database, and container resourceGroupName='myResourceGroup' location='southcentralus' # The Azure Cosmos account name must be globally unique, so be sure to update the `mysqlapicosmosdb` value before you run the command accountName='mysqlapicosmosdb' # Create a resource group az group create \ --name $resourceGroupName \ --location $location # Create a SQL API Cosmos DB account with session consistency and multi-region writes enabled az cosmosdb create \ --resource-group $resourceGroupName \ --name $accountName \ --kind GlobalDocumentDB \ --locations regionName="South Central US" failoverPriority=0 --locations regionName="North Central US" failoverPriority=1 \ --default-consistency-level "Session" \ --enable-multiple-write-locations true
Azure Cosmos hesabının oluşturulması biraz zaman alabilir. İşlem başarılı olduktan sonra, onay çıkışını görebilirsiniz. Azure portal oturum açın ve belirtilen ada sahip Azure Cosmos hesabının var olduğunu doğrulayın. Kaynak oluşturulduktan sonra Azure Cloud Shell penceresini kapatabilirsiniz.
.NET uygulaması oluşturma
Tercih ettiğiniz düzenleyicide veya IDE 'de bir .NET uygulaması oluşturun. Windows komut istemi veya yerel bilgisayarınızdan bir terminal penceresi açın. Komut istemi veya terminalden sonraki bölümlerde bulunan tüm komutları çalıştıracaksınız.
dotnet newAdında bir uygulama oluşturmak için aşağıdaki komutu çalıştırın todo . --langVersionParametresi, LangVersion oluşturulan proje dosyasındaki özelliği ayarlar.
dotnet new console --langVersion:8 -n todo
Dizininizi yeni oluşturulan uygulama klasörüyle değiştirmek ve uygulamayı derlemek için aşağıdaki komutları kullanın:
cd todo
dotnet build
Derlemeden beklenen çıktı şuna benzemelidir:
Restore completed in 100.37 ms for C:\Users\user1\Downloads\CosmosDB_Samples\todo\todo.csproj.
todo -> C:\Users\user1\Downloads\CosmosDB_Samples\todo\bin\Debug\netcoreapp3.0\todo.dll
Build succeeded.
0 Warning(s)
0 Error(s)
Time Elapsed 00:00:34.17
Azure Cosmos DB paketini yükler
hala uygulama dizininde olduğunuzda, komutunu kullanarak .net Core için Azure Cosmos DB istemci kitaplığı ' nı da yükleyebilirsiniz dotnet add package :
dotnet add package Azure.Cosmos --version 4.0.0-preview3
Azure Cosmos hesabı kimlik bilgilerinizi Azure portal kopyalayın
örnek uygulamanın Azure Cosmos hesabınızda kimlik doğrulaması yapması gerekir. kimlik doğrulaması yapmak için Azure Cosmos hesabı kimlik bilgilerini uygulamaya geçirin. aşağıdaki adımları izleyerek Azure Cosmos hesabı kimlik bilgilerinizi alın:
Azure Portal oturum açın.
Azure Cosmos hesabınıza gidin.
Anahtarlar bölmesini açın ve hesabınız için URI ve birincil anahtar değerlerini kopyalayın. Bir sonraki yordamda bir ortam değişkenine URI ve anahtar değerleri ekleyeceksiniz.
Nesne modelini öğrenme
uygulamayı oluşturmaya devam etmeden önce Azure Cosmos DB içindeki kaynak hiyerarşisine ve bu kaynakları oluşturmak ve bunlara erişmek için kullanılan nesne modeline göz atalım. Azure Cosmos DB, kaynakları aşağıdaki sırayla oluşturur:
- Azure Cosmos hesabı
- Veritabanları
- Kapsayıcılar
- Öğeler
varlıkların hiyerarşisi hakkında daha fazla bilgi edinmek için Azure Cosmos DB kaynak modeli makalesine bakın. Şu kaynaklarla etkileşim kurmak için aşağıdaki .NET sınıflarını kullanacaksınız:
CosmosClient. bu sınıf Azure Cosmos DB hizmeti için istemci tarafı mantıksal temsili sağlar. İstemci nesnesi, hizmete yönelik istekleri yapılandırmak ve yürütmek için kullanılır.CreateDatabaseIfNotExistsAsync. Bu Yöntem (yoksa) oluşturur veya (zaten varsa) zaman uyumsuz bir işlem olarak veritabanı kaynağını alır.CreateContainerIfNotExistsAsync. Bu Yöntem (yoksa) oluşturur veya bir kapsayıcıyı zaman uyumsuz bir işlem olarak (zaten varsa) alır. Kapsayıcının yeni oluşturulup oluşturulmayacağını (201) veya var olan bir kapsayıcının döndürülüp döndürülmediğini (200) öğrenmek için yanıttan durum kodunu kontrol edebilirsiniz.CreateItemAsync. Bu yöntem, kapsayıcı içinde bir öğe oluşturur.UpsertItemAsync. Bu yöntem, zaten yoksa kapsayıcı içinde bir öğe oluşturur veya zaten varsa öğeyi değiştirir.GetItemQueryIterator. bu yöntem, parametreli değerler içeren bir SQL ifadesini kullanarak bir Azure Cosmos veritabanındaki kapsayıcı altındaki öğeler için bir sorgu oluşturur.DeleteAsync. bu yöntem, Azure Cosmos hesabınızdan belirtilen veritabanını siler.
Kod örneklerini yapılandırma
bu makalede açıklanan örnek kod, Azure Cosmos DB bir aile veritabanı oluşturur. Aile veritabanı ad, adres, konum, üst öğeler, alt öğeler ve Evcil hayvan gibi aile ayrıntılarını içerir.
Azure Cosmos hesabınız için verileri doldurmadan önce, bir aile öğesinin özelliklerini tanımlayın. Örnek uygulamanızın kök düzeyinde adlı yeni bir sınıf oluşturun Family.cs ve buna aşağıdaki kodu ekleyin:
using System.Text.Json;
using System.Text.Json.Serialization;
namespace todo
{
public class Family
{
[JsonPropertyName("id")]
public string Id { get; set; }
public string LastName { get; set; }
public Parent[] Parents { get; set; }
public Child[] Children { get; set; }
public Address Address { get; set; }
public bool IsRegistered { get; set; }
public override string ToString()
{
return JsonSerializer.Serialize(this);
}
}
public class Parent
{
public string FamilyName { get; set; }
public string FirstName { get; set; }
}
public class Child
{
public string FamilyName { get; set; }
public string FirstName { get; set; }
public string Gender { get; set; }
public int Grade { get; set; }
public Pet[] Pets { get; set; }
}
public class Pet
{
public string GivenName { get; set; }
}
public class Address
{
public string State { get; set; }
public string County { get; set; }
public string City { get; set; }
}
}
Using yönergelerini ekleme ve istemci nesnesini tanımlama
Proje dizininden, düzenleyicinizdeki program. cs dosyasını açın ve using uygulamanızın en üstüne aşağıdaki yönergeleri ekleyin:
using System;
using System.Collections.Generic;
using System.Net;
using System.Threading.Tasks;
using Azure.Cosmos;
Sınıfınıza aşağıdaki genel değişkenleri ekleyin Program . Bu değişkenler, uç nokta ve yetkilendirme anahtarlarını, veritabanının adını ve oluşturacağınız kapsayıcıyı içerir. Uç nokta ve yetkilendirme anahtarı değerlerini ortamınıza göre değiştirdiğinizden emin olun.
private const string EndpointUrl = "https://<your-account>.documents.azure.com:443/";
private const string AuthorizationKey = "<your-account-key>";
private const string DatabaseId = "FamilyDatabase";
private const string ContainerId = "FamilyContainer";
Son olarak, Main yöntemini değiştirin:
static async Task Main(string[] args)
{
CosmosClient cosmosClient = new CosmosClient(EndpointUrl, AuthorizationKey);
await Program.CreateDatabaseAsync(cosmosClient);
await Program.CreateContainerAsync(cosmosClient);
await Program.AddItemsToContainerAsync(cosmosClient);
await Program.QueryItemsAsync(cosmosClient);
await Program.ReplaceFamilyItemAsync(cosmosClient);
await Program.DeleteFamilyItemAsync(cosmosClient);
await Program.DeleteDatabaseAndCleanupAsync(cosmosClient);
}
Veritabanı oluşturma
CreateDatabaseAsyncSınıfında yöntemini tanımlayın program.cs . Bu yöntem, FamilyDatabase zaten mevcut değilse veritabanını oluşturur.
/// <summary>
/// Create the database if it does not exist
/// </summary>
private static async Task CreateDatabaseAsync(CosmosClient cosmosClient)
{
// Create a new database
CosmosDatabase database = await cosmosClient.CreateDatabaseIfNotExistsAsync(Program.DatabaseId);
Console.WriteLine("Created Database: {0}\n", database.Id);
}
Kapsayıcı oluşturma
CreateContainerAsyncSınıfında yöntemini tanımlayın Program . Bu yöntem, FamilyContainer zaten mevcut değilse kapsayıcıyı oluşturur.
/// <summary>
/// Create the container if it does not exist.
/// Specify "/LastName" as the partition key since we're storing family information, to ensure good distribution of requests and storage.
/// </summary>
/// <returns></returns>
private static async Task CreateContainerAsync(CosmosClient cosmosClient)
{
// Create a new container
CosmosContainer container = await cosmosClient.GetDatabase(Program.DatabaseId).CreateContainerIfNotExistsAsync(Program.ContainerId, "/LastName");
Console.WriteLine("Created Container: {0}\n", container.Id);
}
Öğe oluşturma
Aşağıdaki kodla metodunu ekleyerek bir aile öğesi oluşturun AddItemsToContainerAsync . CreateItemAsync UpsertItemAsync Bir öğe oluşturmak için veya yöntemini kullanabilirsiniz.
/// <summary>
/// Add Family items to the container
/// </summary>
private static async Task AddItemsToContainerAsync(CosmosClient cosmosClient)
{
// Create a family object for the Andersen family
Family andersenFamily = new Family
{
Id = "Andersen.1",
LastName = "Andersen",
Parents = new Parent[]
{
new Parent { FirstName = "Thomas" },
new Parent { FirstName = "Mary Kay" }
},
Children = new Child[]
{
new Child
{
FirstName = "Henriette Thaulow",
Gender = "female",
Grade = 5,
Pets = new Pet[]
{
new Pet { GivenName = "Fluffy" }
}
}
},
Address = new Address { State = "WA", County = "King", City = "Seattle" },
IsRegistered = false
};
CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
try
{
// Read the item to see if it exists.
ItemResponse<Family> andersenFamilyResponse = await container.ReadItemAsync<Family>(andersenFamily.Id, new PartitionKey(andersenFamily.LastName));
Console.WriteLine("Item in database with id: {0} already exists\n", andersenFamilyResponse.Value.Id);
}
catch(CosmosException ex) when (ex.Status == (int)HttpStatusCode.NotFound)
{
// Create an item in the container representing the Andersen family. Note we provide the value of the partition key for this item, which is "Andersen"
ItemResponse<Family> andersenFamilyResponse = await container.CreateItemAsync<Family>(andersenFamily, new PartitionKey(andersenFamily.LastName));
// Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse.
Console.WriteLine("Created item in database with id: {0}\n", andersenFamilyResponse.Value.Id);
}
// Create a family object for the Wakefield family
Family wakefieldFamily = new Family
{
Id = "Wakefield.7",
LastName = "Wakefield",
Parents = new Parent[]
{
new Parent { FamilyName = "Wakefield", FirstName = "Robin" },
new Parent { FamilyName = "Miller", FirstName = "Ben" }
},
Children = new Child[]
{
new Child
{
FamilyName = "Merriam",
FirstName = "Jesse",
Gender = "female",
Grade = 8,
Pets = new Pet[]
{
new Pet { GivenName = "Goofy" },
new Pet { GivenName = "Shadow" }
}
},
new Child
{
FamilyName = "Miller",
FirstName = "Lisa",
Gender = "female",
Grade = 1
}
},
Address = new Address { State = "NY", County = "Manhattan", City = "NY" },
IsRegistered = true
};
// Create an item in the container representing the Wakefield family. Note we provide the value of the partition key for this item, which is "Wakefield"
ItemResponse<Family> wakefieldFamilyResponse = await container.UpsertItemAsync<Family>(wakefieldFamily, new PartitionKey(wakefieldFamily.LastName));
// Note that after creating the item, we can access the body of the item with the Resource property off the ItemResponse. We can also access the RequestCharge property to see the amount of RUs consumed on this request.
Console.WriteLine("Created item in database with id: {0}\n", wakefieldFamilyResponse.Value.Id);
}
Öğeleri sorgulama
Bir öğeyi ekledikten sonra, Andersen ailesinin ayrıntılarını almak için bir sorgu çalıştırabilirsiniz. aşağıdaki kod, SQL sorgusunu doğrudan kullanarak sorgunun nasıl yürütüleceğini gösterir. andersen aile ayrıntılarını almak için SQL sorgusu SELECT * FROM c WHERE c.LastName = 'Andersen' . QueryItemsAsyncSınıfında yöntemi tanımlayın Program ve aşağıdaki kodu buna ekleyin:
/// <summary>
/// Run a query (using Azure Cosmos DB SQL syntax) against the container
/// </summary>
private static async Task QueryItemsAsync(CosmosClient cosmosClient)
{
var sqlQueryText = "SELECT * FROM c WHERE c.LastName = 'Andersen'";
Console.WriteLine("Running query: {0}\n", sqlQueryText);
CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
QueryDefinition queryDefinition = new QueryDefinition(sqlQueryText);
List<Family> families = new List<Family>();
await foreach (Family family in container.GetItemQueryIterator<Family>(queryDefinition))
{
families.Add(family);
Console.WriteLine("\tRead {0}\n", family);
}
}
Bir öğeyi değiştirme
Bir aile öğesini okuyun ve ReplaceFamilyItemAsync yöntemi aşağıdaki kodla ekleyerek güncelleştirin:
/// <summary>
/// Replace an item in the container
/// </summary>
private static async Task ReplaceFamilyItemAsync(CosmosClient cosmosClient)
{
CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
ItemResponse<Family> wakefieldFamilyResponse = await container.ReadItemAsync<Family>("Wakefield.7", new PartitionKey("Wakefield"));
Family itemBody = wakefieldFamilyResponse;
// update registration status from false to true
itemBody.IsRegistered = true;
// update grade of child
itemBody.Children[0].Grade = 6;
// replace the item with the updated content
wakefieldFamilyResponse = await container.ReplaceItemAsync<Family>(itemBody, itemBody.Id, new PartitionKey(itemBody.LastName));
Console.WriteLine("Updated Family [{0},{1}].\n \tBody is now: {2}\n", itemBody.LastName, itemBody.Id, wakefieldFamilyResponse.Value);
}
Öğeyi silme
Aşağıdaki kodla yöntemini ekleyerek bir aile öğesini silin DeleteFamilyItemAsync :
/// <summary>
/// Delete an item in the container
/// </summary>
private static async Task DeleteFamilyItemAsync(CosmosClient cosmosClient)
{
CosmosContainer container = cosmosClient.GetContainer(Program.DatabaseId, Program.ContainerId);
string partitionKeyValue = "Wakefield";
string familyId = "Wakefield.7";
// Delete an item. Note we must provide the partition key value and id of the item to delete
ItemResponse<Family> wakefieldFamilyResponse = await container.DeleteItemAsync<Family>(familyId,new PartitionKey(partitionKeyValue));
Console.WriteLine("Deleted Family [{0},{1}]\n", partitionKeyValue, familyId);
}
Veritabanını silme
DeleteDatabaseAndCleanupAsyncAşağıdaki kodla yöntemini ekleyerek veritabanını silebilirsiniz:
/// <summary>
/// Delete the database and dispose of the Cosmos Client instance
/// </summary>
private static async Task DeleteDatabaseAndCleanupAsync(CosmosClient cosmosClient)
{
CosmosDatabase database = cosmosClient.GetDatabase(Program.DatabaseId);
DatabaseResponse databaseResourceResponse = await database.DeleteAsync();
Console.WriteLine("Deleted Database: {0}\n", Program.DatabaseId);
}
Tüm gerekli yöntemleri ekledikten sonra program. cs dosyasını kaydedin.
Kodu çalıştırma
Azure Cosmos DB kaynaklarını oluşturmak için uygulamayı çalıştırın:
dotnet run
Uygulamayı çalıştırdığınızda aşağıdaki çıktı oluşturulur:
Created Database: FamilyDatabase
Created Container: FamilyContainer
Created item in database with id: Andersen.1
Running query: SELECT * FROM c WHERE c.LastName = 'Andersen'
Read {"id":"Andersen.1","LastName":"Andersen","Parents":[{"FamilyName":null,"FirstName":"Thomas"},{"FamilyName":null "FirstName":"Mary Kay"}],"Children":[{"FamilyName":null,"FirstName":"Henriette Thaulow","Gender":"female","Grade":5,"Pets": [{"GivenName":"Fluffy"}]}],"Address":{"State":"WA","County":"King","City":"Seattle"},"IsRegistered":false}
Updated Family [Wakefield,Wakefield.7].
Body is now: {"id":"Wakefield.7","LastName":"Wakefield","Parents":[{"FamilyName":"Wakefield","FirstName":"Robin"} {"FamilyName":"Miller","FirstName":"Ben"}],"Children":[{"FamilyName":"Merriam","FirstName":"Jesse","Gender":"female","Grade":6 "Pets":[{"GivenName":"Goofy"},{"GivenName":"Shadow"}]},{"FamilyName":"Miller","FirstName":"Lisa","Gender":"female","Grade":1 "Pets":null}],"Address":{"State":"NY","County":"Manhattan","City":"NY"},"IsRegistered":true}
Deleted Family [Wakefield,Wakefield.7]
Deleted Database: FamilyDatabase
End of demo, press any key to exit.
Azure portal oturum açarak ve Azure Cosmos hesabınızda gerekli öğeleri görerek, verilerin oluşturulduğunu doğrulayabilirsiniz.
Kaynakları temizleme
artık azure Cosmos hesabına ve ilgili kaynak grubuna ihtiyacınız kalmadığında, bunları kaldırmak için azure clı veya Azure PowerShell kullanabilirsiniz. Aşağıdaki komut, Azure CLı kullanılarak kaynak grubunun nasıl silineceğini göstermektedir:
az group delete -g "myResourceGroup"
Sonraki adımlar
bu hızlı başlangıçta, bir Azure Cosmos hesabı oluşturmayı, veritabanı oluşturmayı ve bir .net Core uygulamasını kullanarak kapsayıcı oluşturmayı öğrendiniz. artık aşağıdaki makaledeki yönergeleri kullanarak Azure Cosmos hesabınıza daha fazla veri aktarabilirsiniz:
Azure Cosmos DB bir geçişe yönelik kapasite planlaması yapılmaya çalışılıyor musunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkında bilgi kullanabilirsiniz.
- Varsa, var olan veritabanı kümenizdeki sanal çekirdek ve sunucu sayısı varsa, sanal çekirdekler veya vCPU 'lar kullanarak istek birimlerini tahmin etme hakkında bilgi edinin
- geçerli veritabanı iş yükünüz için tipik istek hızlarını biliyorsanız, Azure Cosmos DB kapasite planlayıcısı kullanarak istek birimlerini tahmin etme hakkında bilgi edinin