Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
QLDBDriver Amazon untuk. NET— Referensi buku masak
penting
Pemberitahuan akhir dukungan: Pelanggan yang ada akan dapat menggunakan Amazon QLDB hingga akhir dukungan pada 07/31/2025. Untuk detail selengkapnya, lihat Memigrasi QLDB Buku Besar Amazon ke Amazon Aurora Postgre
Panduan referensi ini menunjukkan kasus penggunaan umum QLDB driver Amazon untuk. NET. Ini memberikan contoh kode C # yang menunjukkan cara menggunakan driver untuk menjalankan operasi create, read, update, dan delete (CRUD) dasar. Ini juga mencakup contoh kode untuk memproses data Amazon Ion. Selain itu, panduan ini menyoroti praktik terbaik untuk membuat transaksi idempoten dan menerapkan kendala keunikan.
catatan
Topik ini memberikan contoh kode pemrosesan data Amazon Ion menggunakan pemetaan objek Ion secara
Mengimpor driver
Contoh kode berikut mengimpor driver.
using Amazon.QLDB.Driver; using Amazon.QLDB.Driver.Generic; using Amazon.QLDB.Driver.Serialization;
using Amazon.QLDB.Driver; using Amazon.IonDotnet.Builders;
Membuat instantiasi pengemudi
Contoh kode berikut membuat instance driver yang menghubungkan ke nama buku besar tertentu menggunakan pengaturan default.
Operasi CRUD
QLDBmenjalankan operasi create, read, update, dan delete (CRUD) sebagai bagian dari transaksi.
Awas
Sebagai praktik terbaik, buat transaksi tulis Anda benar-benar idempoten.
Membuat transaksi idempoten
Kami menyarankan Anda membuat transaksi tulis idempoten untuk menghindari efek samping yang tidak terduga dalam kasus percobaan ulang. Transaksi adalah idempoten jika dapat berjalan beberapa kali dan menghasilkan hasil yang identik setiap kali.
Misalnya, pertimbangkan transaksi yang menyisipkan dokumen ke dalam tabel bernamaPerson
. Transaksi harus terlebih dahulu memeriksa apakah dokumen sudah ada dalam tabel atau tidak. Tanpa pemeriksaan ini, tabel mungkin berakhir dengan dokumen duplikat.
Misalkan QLDB berhasil melakukan transaksi di sisi server, tetapi klien kehabisan waktu sambil menunggu respons. Jika transaksi tidak idempoten, dokumen yang sama dapat dimasukkan lebih dari sekali dalam kasus percobaan ulang.
Menggunakan indeks untuk menghindari pemindaian tabel penuh
Kami juga menyarankan Anda menjalankan pernyataan dengan klausa WHERE
predikat menggunakan operator kesetaraan pada bidang yang diindeks atau ID dokumen; misalnya, atau. WHERE indexedField = 123
WHERE indexedField IN (456, 789)
Tanpa pencarian yang diindeks ini, QLDB perlu melakukan pemindaian tabel, yang dapat menyebabkan batas waktu transaksi atau konflik kontrol konkurensi () yang optimis. OCC
Untuk informasi selengkapnya tentang OCC, lihat Model QLDB konkurensi Amazon.
Transaksi yang dibuat secara implisit
Amazon. QLDB.Pengemudi. TransactionExecutor
membungkus transaksi yang dibuat secara implisit.
Anda dapat menjalankan pernyataan dalam fungsi lambda dengan menggunakan Execute
metode pelaksana transaksi. Pengemudi secara implisit melakukan transaksi saat fungsi lambda kembali.
Bagian berikut menunjukkan cara menjalankan CRUD operasi dasar, menentukan logika coba ulang kustom, dan menerapkan kendala keunikan.
Daftar Isi
Membuat tabel
Membuat indeks
Membaca dokumen
// Assumes that Person table has documents as follows: // { "GovId": "TOYENC486FH", "FirstName" : "Brent" } // Person class is defined as follows: // public class Person // { // public string GovId { get; set; } // public string FirstName { get; set; } // } IAsyncResult<Person> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'")); }); await foreach (Person person in result) { Console.WriteLine(person.GovId); // Prints TOYENC486FH. Console.WriteLine(person.FirstName); // Prints Brent. }
catatan
Saat Anda menjalankan kueri tanpa pencarian yang diindeks, itu akan memanggil pemindaian tabel lengkap. Dalam contoh ini, kami merekomendasikan memiliki indeks di GovId
lapangan untuk mengoptimalkan kinerja. Tanpa indeks aktifGovId
, kueri dapat memiliki lebih banyak latensi dan juga dapat menyebabkan pengecualian OCC konflik atau batas waktu transaksi.
Menggunakan parameter kueri
Contoh kode berikut menggunakan parameter query tipe C #.
IAsyncResult<Person> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE FirstName = ?", "Brent")); }); await foreach (Person person in result) { Console.WriteLine(person.GovId); // Prints TOYENC486FH. Console.WriteLine(person.FirstName); // Prints Brent. }
Contoh kode berikut menggunakan beberapa parameter query tipe C #.
IAsyncResult<Person> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE GovId = ? AND FirstName = ?", "TOYENC486FH", "Brent")); }); await foreach (Person person in result) { Console.WriteLine(person.GovId); // Prints TOYENC486FH. Console.WriteLine(person.FirstName); // Prints Brent. }
Contoh kode berikut menggunakan array parameter query tipe C #.
// Assumes that Person table has documents as follows: // { "GovId": "TOYENC486FH", "FirstName" : "Brent" } // { "GovId": "ROEE1C1AABH", "FirstName" : "Jim" } // { "GovId": "YH844DA7LDB", "FirstName" : "Mary" } string[] ids = { "TOYENC486FH", "ROEE1C1AABH", "YH844DA7LDB" }; IAsyncResult<Person> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE GovId IN (?,?,?)", ids)); }); await foreach (Person person in result) { Console.WriteLine(person.FirstName); // Prints Brent on first iteration. // Prints Jim on second iteration. // Prints Mary on third iteration. }
Contoh kode berikut menggunakan daftar C # sebagai nilai.
// Assumes that Person table has document as follows: // { "GovId": "TOYENC486FH", // "FirstName" : "Brent", // "Vehicles": [ // { "Make": "Volkswagen", // "Model": "Golf"}, // { "Make": "Honda", // "Model": "Civic"} // ] // } // Person class is defined as follows: // public class Person // { // public string GovId { get; set; } // public string FirstName { get; set; } // public List<Vehicle> Vehicles { get; set; } // } // Vehicle class is defined as follows: // public class Vehicle // { // public string Make { get; set; } // public string Model { get; set; } // } List<Vehicle> vehicles = new List<Vehicle> { new Vehicle { Make = "Volkswagen", Model = "Golf" }, new Vehicle { Make = "Honda", Model = "Civic" } }; IAsyncResult<Person> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE Vehicles = ?", vehicles)); }); await foreach (Person person in result) { Console.WriteLine("{"); Console.WriteLine($" GovId: {person.GovId},"); Console.WriteLine($" FirstName: {person.FirstName},"); Console.WriteLine(" Vehicles: ["); foreach (Vehicle vehicle in person.Vehicles) { Console.WriteLine(" {"); Console.WriteLine($" Make: {vehicle.Make},"); Console.WriteLine($" Model: {vehicle.Model},"); Console.WriteLine(" },"); } Console.WriteLine(" ]"); Console.WriteLine("}"); // Prints: // { // GovId: TOYENC486FH, // FirstName: Brent, // Vehicles: [ // { // Make: Volkswagen, // Model: Golf // }, // { // Make: Honda, // Model: Civic // }, // ] // } }
catatan
Saat Anda menjalankan kueri tanpa pencarian yang diindeks, itu akan memanggil pemindaian tabel lengkap. Dalam contoh ini, kami merekomendasikan memiliki indeks di GovId
lapangan untuk mengoptimalkan kinerja. Tanpa indeks aktifGovId
, kueri dapat memiliki lebih banyak latensi dan juga dapat menyebabkan pengecualian OCC konflik atau batas waktu transaksi.
Contoh kode berikut menggunakan parameter query tipe Ion.
Contoh kode berikut menggunakan beberapa parameter query.
Contoh kode berikut menggunakan daftar parameter query.
Contoh kode berikut menggunakan daftar Ion sebagai nilai. Untuk mempelajari lebih lanjut tentang menggunakan tipe Ion yang berbeda, lihatBekerja dengan tipe data Amazon Ion di Amazon QLDB.
Memasukkan dokumen
Contoh kode berikut menyisipkan tipe data Ion.
string govId = "TOYENC486FH"; Person person = new Person { GovId = "TOYENC486FH", FirstName = "Brent" }; await driver.Execute(async txn => { // Check if a document with GovId:TOYENC486FH exists // This is critical to make this transaction idempotent IAsyncResult<Person> result = await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE GovId = ?", govId)); // Check if there is a record in the cursor. int count = await result.CountAsync(); if (count > 0) { // Document already exists, no need to insert return; } // Insert the document. await txn.Execute(txn.Query<Document>("INSERT INTO Person ?", person)); });
Transaksi ini memasukkan dokumen ke dalam Person
tabel. Sebelum memasukkan, pertama-tama memeriksa apakah dokumen sudah ada di tabel. Pemeriksaan ini membuat transaksi idempoten di alam. Bahkan jika Anda menjalankan transaksi ini beberapa kali, itu tidak akan menyebabkan efek samping yang tidak diinginkan.
catatan
Dalam contoh ini, kami merekomendasikan memiliki indeks di GovId
lapangan untuk mengoptimalkan kinerja. Tanpa indeks aktifGovId
, pernyataan dapat memiliki lebih banyak latensi dan juga dapat menyebabkan pengecualian OCC konflik atau batas waktu transaksi.
Memasukkan beberapa dokumen dalam satu pernyataan
Untuk menyisipkan beberapa dokumen dengan menggunakan satu INSERT pernyataan, Anda dapat meneruskan List
parameter C# ke pernyataan sebagai berikut.
Person person1 = new Person { FirstName = "Brent", GovId = "TOYENC486FH" }; Person person2 = new Person { FirstName = "Jim", GovId = "ROEE1C1AABH" }; List<Person> people = new List<Person>(); people.Add(person1); people.Add(person2); IAsyncResult<Document> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Document>("INSERT INTO Person ?", people)); }); await foreach (Document row in result) { Console.WriteLine("{ documentId: " + row.DocumentId + " }"); // The statement returns the created documents' ID: // { documentId: 6BFt5eJQDFLBW2aR8LPw42 } // { documentId: K5Zrcb6N3gmIEHgGhwoyKF } }
Untuk menyisipkan beberapa dokumen dengan menggunakan INSERT pernyataan tunggal, Anda dapat meneruskan parameter tipe Daftar Ion ke pernyataan sebagai berikut.
Anda tidak melampirkan variabel placeholder (?
) dalam tanda kurung sudut ganda (<<...>>
) saat melewati daftar Ion. Dalam pernyataan PartiQL manual, tanda kurung sudut ganda menunjukkan koleksi tidak berurutan yang dikenal sebagai tas.
Memperbarui dokumen
string govId = "TOYENC486FH"; string firstName = "John"; IAsyncResult<Document> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Document>("UPDATE Person SET FirstName = ? WHERE GovId = ?", firstName , govId)); }); await foreach (Document row in result) { Console.WriteLine("{ documentId: " + row.DocumentId + " }"); // The statement returns the updated document ID: // { documentId: Djg30Zoltqy5M4BFsA2jSJ } }
catatan
Dalam contoh ini, kami merekomendasikan memiliki indeks di GovId
lapangan untuk mengoptimalkan kinerja. Tanpa indeks aktifGovId
, pernyataan dapat memiliki lebih banyak latensi dan juga dapat menyebabkan pengecualian OCC konflik atau batas waktu transaksi.
Menghapus dokumen
string govId = "TOYENC486FH"; IAsyncResult<Document> result = await driver.Execute(async txn => { return await txn.Execute(txn.Query<Document>("DELETE FROM Person WHERE GovId = ?", govId)); }); await foreach (Document row in result) { Console.WriteLine("{ documentId: " + row.DocumentId + " }"); // The statement returns the updated document ID: // { documentId: Djg30Zoltqy5M4BFsA2jSJ } }
catatan
Dalam contoh ini, kami merekomendasikan memiliki indeks di GovId
lapangan untuk mengoptimalkan kinerja. Tanpa indeks aktifGovId
, pernyataan dapat memiliki lebih banyak latensi dan juga dapat menyebabkan pengecualian OCC konflik atau batas waktu transaksi.
Menjalankan beberapa pernyataan dalam transaksi
// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd // set your UPDATE to filter on vin and insured, and check if you updated something or not. public static async Task<bool> InsureVehicle(IAsyncQldbDriver driver, string vin) { return await driver.Execute(async txn => { // Check if the vehicle is insured. Amazon.QLDB.Driver.Generic.IAsyncResult<Vehicle> result = await txn.Execute( txn.Query<Vehicle>("SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)); if (await result.CountAsync() > 0) { // If the vehicle is not insured, insure it. await txn.Execute( txn.Query<Document>("UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin)); return true; } return false; }); }
Logika coba lagi
Untuk informasi tentang logika coba ulang bawaan pengemudi, lihatMemahami kebijakan coba lagi dengan pengemudi di Amazon QLDB.
Menerapkan kendala keunikan
QLDBtidak mendukung indeks unik, tetapi Anda dapat menerapkan perilaku ini di aplikasi Anda.
Misalkan Anda ingin menerapkan kendala keunikan pada GovId
bidang dalam tabel. Person
Untuk melakukan ini, Anda dapat menulis transaksi yang melakukan hal berikut:
-
Tegaskan bahwa tabel tidak memiliki dokumen yang ada dengan yang ditentukan
GovId
. -
Masukkan dokumen jika pernyataan lolos.
Jika transaksi yang bersaing secara bersamaan melewati pernyataan, hanya satu transaksi yang akan berhasil dilakukan. Transaksi lainnya akan gagal dengan pengecualian OCC konflik.
Contoh kode berikut menunjukkan bagaimana menerapkan logika kendala keunikan ini.
string govId = "TOYENC486FH"; Person person = new Person { GovId = "TOYENC486FH", FirstName = "Brent" }; await driver.Execute(async txn => { // Check if a document with GovId:TOYENC486FH exists // This is critical to make this transaction idempotent IAsyncResult<Person> result = await txn.Execute(txn.Query<Person>("SELECT * FROM Person WHERE GovId = ?", govId)); // Check if there is a record in the cursor. int count = await result.CountAsync(); if (count > 0) { // Document already exists, no need to insert return; } // Insert the document. await txn.Execute(txn.Query<Document>("INSERT INTO Person ?", person)); });
catatan
Dalam contoh ini, kami merekomendasikan memiliki indeks di GovId
lapangan untuk mengoptimalkan kinerja. Tanpa indeks aktifGovId
, pernyataan dapat memiliki lebih banyak latensi dan juga dapat menyebabkan pengecualian OCC konflik atau batas waktu transaksi.
Bekerja dengan Amazon Ion
Ada beberapa cara untuk memproses data Amazon Ion diQLDB. Anda dapat menggunakan pustaka Ion
Bagian berikut memberikan contoh kode pemrosesan data Ion menggunakan kedua teknik.
Mengimpor modul Ion
using Amazon.IonObjectMapper;
using Amazon.IonDotnet.Builders;
Membuat tipe Ion
Contoh kode berikut menunjukkan cara membuat nilai Ion dari objek C# menggunakan pemetaan objek Ion.
// Assumes that Person class is defined as follows: // public class Person // { // public string FirstName { get; set; } // public int Age { get; set; } // } // Initialize the Ion Object Mapper IonSerializer ionSerializer = new IonSerializer(); // The C# object to be serialized Person person = new Person { FirstName = "John", Age = 13 }; // Serialize the C# object into stream using the Ion Object Mapper Stream stream = ionSerializer.Serialize(person); // Load will take in stream and return a datagram; a top level container of Ion values. IIonValue ionDatagram = IonLoader.Default.Load(stream); // To get the Ion value within the datagram, we call GetElementAt(0). IIonValue ionPerson = ionDatagram.GetElementAt(0); Console.WriteLine(ionPerson.GetField("firstName").StringValue); Console.WriteLine(ionPerson.GetField("age").IntValue);
Contoh kode berikut menunjukkan dua cara untuk membuat nilai Ion menggunakan perpustakaan Ion.
Menggunakan ValueFactory
using Amazon.IonDotnet.Tree; using Amazon.IonDotnet.Tree.Impl; IValueFactory valueFactory = new ValueFactory(); IIonValue ionPerson = valueFactory.NewEmptyStruct(); ionPerson.SetField("firstName", valueFactory.NewString("John")); ionPerson.SetField("age", valueFactory.NewInt(13)); Console.WriteLine(ionPerson.GetField("firstName").StringValue); Console.WriteLine(ionPerson.GetField("age").IntValue);
Menggunakan IonLoader
using Amazon.IonDotnet.Builders; using Amazon.IonDotnet.Tree; // Load will take in Ion text and return a datagram; a top level container of Ion values. IIonValue ionDatagram = IonLoader.Default.Load("{firstName: \"John\", age: 13}"); // To get the Ion value within the datagram, we call GetElementAt(0). IIonValue ionPerson = ionDatagram.GetElementAt(0); Console.WriteLine(ionPerson.GetField("firstName").StringValue); Console.WriteLine(ionPerson.GetField("age").IntValue);
Mendapatkan dump biner Ion
// Initialize the Ion Object Mapper with Ion binary serialization format IonSerializer ionSerializer = new IonSerializer(new IonSerializationOptions { Format = IonSerializationFormat.BINARY }); // The C# object to be serialized Person person = new Person { FirstName = "John", Age = 13 }; MemoryStream stream = (MemoryStream) ionSerializer.Serialize(person); Console.WriteLine(BitConverter.ToString(stream.ToArray()));
// ionObject is an Ion struct MemoryStream stream = new MemoryStream(); using (var writer = IonBinaryWriterBuilder.Build(stream)) { ionObject.WriteTo(writer); writer.Finish(); } Console.WriteLine(BitConverter.ToString(stream.ToArray()));
Mendapatkan dump teks Ion
// Initialize the Ion Object Mapper IonSerializer ionSerializer = new IonSerializer(new IonSerializationOptions { Format = IonSerializationFormat.TEXT }); // The C# object to be serialized Person person = new Person { FirstName = "John", Age = 13 }; MemoryStream stream = (MemoryStream) ionSerializer.Serialize(person); Console.WriteLine(System.Text.Encoding.UTF8.GetString(stream.ToArray()));
// ionObject is an Ion struct StringWriter sw = new StringWriter(); using (var writer = IonTextWriterBuilder.Build(sw)) { ionObject.WriteTo(writer); writer.Finish(); } Console.WriteLine(sw.ToString());
Untuk informasi selengkapnya tentang bekerja dengan Ion, lihat dokumentasi Amazon Ion