Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Bekerja dengan model persistensi objek.NET dan DynamoDB
AWS SDK untuk .NET Ini menyediakan model persistensi objek yang memungkinkan Anda memetakan kelas sisi klien Anda ke tabel Amazon DynamoDB. Kemudian, setiap instans objek dipetakan ke item dalam tabel yang sesuai. Untuk menyimpan objek sisi klien ke tabel, model persistensi objek menyediakan kelas `DynamoDBContext`, yaitu titik masuk ke DynamoDB. Kelas ini menyediakan koneksi ke DynamoDB dan memungkinkan Anda mengakses tabel, melakukan berbagai operasi CRUD, dan menjalankan kueri.
Model persistensi objek menyediakan satu set atribut untuk memetakan kelas sisi klien ke tabel, dan properties/fields ke atribut tabel.
**catatan**
Model persistensi objek tidak menyediakan API untuk membuat, memperbarui, atau menghapus tabel. Model ini hanya menyediakan operasi data. Anda hanya dapat menggunakan API AWS SDK untuk .NET tingkat rendah untuk membuat, memperbarui, dan menghapus tabel.
Contoh berikut menunjukkan cara kerja model persistensi objek. Contoh ini dimulai dengan tabel `ProductCatalog`. Contoh ini memiliki `Id` sebagai kunci primernya.
```
ProductCatalog(Id, ...)
```
Katakanlah Anda memiliki kelas `Book` yang berisi properti `Title`, `ISBN`, dan `Authors`. Anda dapat memetakan kelas `Book` ke tabel `ProductCatalog` dengan menambahkan atribut yang didefinisikan oleh model persistensi objek, seperti yang ditunjukkan dalam kode contoh C\$1 berikut.
**Example**
```
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey]
public int Id { get; set; }
public string Title { get; set; }
public int ISBN { get; set; }
[DynamoDBProperty("Authors")]
public List BookAuthors { get; set; }
[DynamoDBIgnore]
public string CoverPage { get; set; }
}
```
Dalam contoh sebelumnya, atribut `DynamoDBTable` memetakan kelas `Book` ke tabel `ProductCatalog`.
Model persistensi objek mendukung pemetaan eksplisit dan default antara properti kelas dan atribut tabel.
+ **Pemetaan eksplisit—**Untuk memetakan properti ke kunci primer, Anda harus menggunakan atribut model persistensi objek `DynamoDBHashKey` dan `DynamoDBRangeKey`. Selain itu, untuk atribut kunci nonprimer, jika nama properti di kelas Anda dan atribut tabel terkait yang ingin Anda petakan tidak sama, Anda harus mendefinisikan pemetaan dengan menambahkan atribut `DynamoDBProperty` secara eksplisit.
Dalam contoh sebelumnya, properti `Id` dipetakan ke kunci primer dengan nama yang sama, dan properti `BookAuthors` dipetakan ke atribut `Authors` dalam tabel `ProductCatalog`.
+ **Pemetaan default—**Secara default, model persistensi objek memetakan properti kelas ke atribut dengan nama yang sama dalam tabel.
Dalam contoh sebelumnya, properti `Title` dan `ISBN` dipetakan ke atribut dengan nama yang sama dalam tabel `ProductCatalog`.
Anda tidak perlu memetakan setiap properti kelas tunggal. Anda mengidentifikasi properti ini dengan menambahkan atribut `DynamoDBIgnore`. Ketika Anda menyimpan instans `Book` ke tabel, `DynamoDBContext` tidak menyertakan properti `CoverPage`. Instans tersebut juga tidak mengembalikan properti ini saat Anda mengambil instans buku.
Anda dapat memetakan properti jenis .NET primitif seperti int dan string. Anda juga dapat memetakan setiap jenis data arbitrer selama Anda memberikan konverter yang sesuai untuk memetakan data arbitrer ke salah satu jenis DynamoDB. Untuk mempelajari cara memetakan jenis arbitrer, lihat [Memetakan data arbitrer dengan DynamoDB menggunakan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.ArbitraryDataMapping.md).
Model persistensi objek mendukung penguncian optimis. Selama operasi pembaruan, model ini memastikan bahwa Anda memiliki salinan terbaru dari item yang akan Anda perbarui. Untuk informasi selengkapnya, lihat [Penguncian optimis menggunakan DynamoDB dan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.VersionSupport.md).
Untuk informasi selengkapnya, lihat topik di bawah.
**Topics**
+ [Jenis data yang didukung](#DotNetDynamoDBContext.SupportedTypes)
+ [Atribut DynamoDB dari model persistensi objek.NET](DeclarativeTagsList.md)
+ [DBContext Kelas Dynamo dari model persistensi objek.NET](DotNetDynamoDBContext.md)
+ [Penguncian optimis menggunakan DynamoDB dan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.VersionSupport.md)
+ [Memetakan data arbitrer dengan DynamoDB menggunakan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.ArbitraryDataMapping.md)
## Jenis data yang didukung
Model persistensi objek mendukung sekumpulan jenis data .NET primitif, koleksi, dan jenis data arbitrer. Model ini mendukung jenis data primitif berikut.
+ `bool`
+ `byte`
+ `char`
+ `DateTime`
+ `decimal`
+ `double`
+ `float`
+ `Int16`
+ `Int32`
+ `Int64`
+ `SByte`
+ `string`
+ `UInt16`
+ `UInt32`
+ `UInt64`
Model persistensi objek juga mendukung jenis koleksi.NET. `DynamoDBContext`mampu mengkonversi jenis koleksi beton dan sederhana Plain Old CLR Objects (POCOs).
Tabel berikut merangkum pemetaan jenis .NET sebelumnya untuk jenis DynamoDB.
****
| Jenis .NET primitif | Jenis DynamoDB |
| --- | --- |
| Semua jenis angka | `N` (jenis angka) |
| Semua jenis string | `S` (jenis string) |
| MemoryStream, byte [] | `B` (jenis biner) |
| bool | N (jenis angka). 0 mewakili false dan 1 mewakili true. |
| Jenis koleksi | Jenis BS (kumpulan biner), jenis SS (kumpulan string), dan jenis NS (kumpulan angka). |
| DateTime | S (jenis string). Nilai DateTime disimpan sebagai string berformat ISO-8601. |
Model persistensi objek juga mendukung jenis data arbitrer. Namun, Anda harus menyediakan kode konverter untuk memetakan jenis kompleks ke jenis DynamoDB.
**catatan**
Nilai biner kosong didukung.
Pembacaan nilai string kosong didukung. Nilai atribut string kosong didukung dalam nilai atribut string dari jenis Set saat menulis ke DynamoDB. Nilai atribut string kosong dari jenis string dan nilai string kosong dalam jenis Daftar atau Peta dihilangkan dari permintaan tulis
# Atribut DynamoDB dari model persistensi objek.NET
Bagian ini menjelaskan atribut yang ditawarkan model persistensi objek agar Anda dapat memetakan kelas dan properti ke tabel dan atribut DynamoDB.
**catatan**
Dalam atribut berikut, hanya `DynamoDBTable` dan `DynamoDBHashKey` yang diperlukan.
## Dinamo DBGlobal SecondaryIndexHashKey
Memetakan properti kelas ke kunci partisi untuk indeks sekunder global. Gunakan atribut ini jika Anda perlu `Query` indeks sekunder global.
## Dinamo DBGlobal SecondaryIndexRangeKey
Memetakan properti kelas ke kunci urutan indeks sekunder global. Gunakan atribut ini jika Anda perlu `Query` indeks sekunder global dan ingin menyempurnakan hasil menggunakan kunci urutan indeks.
## Kunci Dynamo DBHash
Memetakan properti kelas ke kunci partisi untuk kunci primer tabel. Atribut kunci primer tidak boleh berupa jenis koleksi.
Contoh kode C\$1 berikut memetakan kelas `Book` ke tabel `ProductCatalog`, dan properti `Id` ke kunci partisi kunci kunci primer tabel.
```
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey]
public int Id { get; set; }
// Additional properties go here.
}
```
## Dinamo DBIgnore
Menunjukkan bahwa properti terkait harus diabaikan. Jika tidak ingin menyimpan properti kelas, Anda dapat menambahkan atribut ini untuk meminta agar `DynamoDBContext` tidak menyertakan properti ini saat menyimpan objek ke tabel.
## Dinamo DBLocal SecondaryIndexRangeKey
Memetakan properti kelas ke kunci urutan indeks sekunder lokal. Gunakan atribut ini jika Anda perlu `Query` indeks sekunder lokal dan ingin menyempurnakan hasil menggunakan kunci urutan indeks.
## Dinamo DBProperty
Memetakan properti kelas ke atribut tabel. Jika properti kelas dipetakan ke atribut tabel dengan nama yang sama, Anda tidak perlu menentukan atribut ini. Namun, jika nama tidak sama, Anda dapat menggunakan tanda ini untuk memberikan pemetaan. Dalam pernyataan C\$1 berikut, `DynamoDBProperty` memetakan properti `BookAuthors` ke atribut `Authors` dalam tabel.
```
[DynamoDBProperty("Authors")]
public List BookAuthors { get; set; }
```
`DynamoDBContext` menggunakan informasi pemetaan ini untuk membuat atribut `Authors` saat menyimpan data objek ke tabel yang sesuai.
## Dinamo DBRenamable
Menentukan nama alternatif untuk properti kelas. Langkah ini berguna jika Anda menulis konverter khusus untuk memetakan data arbitrer ke tabel DynamoDB yang nama properti kelasnya berbeda dengan atribut tabel.
## Kunci Dynamo DBRange
Memetakan properti kelas ke kunci urutan untuk kunci primer tabel. Jika tabel memiliki kunci primer komposit (kunci partisi dan kunci urutan), Anda harus menentukan atribut `DynamoDBHashKey` dan `DynamoDBRangeKey` dalam pemetaan kelas Anda.
Misalnya, tabel sampel `Reply` memiliki kunci primer yang dibuat dari kunci partisi `Id` dan kunci urutan `Replenishment`. Contoh kode C\$1 berikut memetakan kelas `Reply` ke tabel `Reply`. Definisi kelas juga menunjukkan bahwa dua propertinya dipetakan ke kunci primer.
```
[DynamoDBTable("Reply")]
public class Reply
{
[DynamoDBHashKey]
public int ThreadId { get; set; }
[DynamoDBRangeKey]
public string Replenishment { get; set; }
// Additional properties go here.
}
```
## Dinamo DBTable
Mengidentifikasi tabel target di DynamoDB tempat kelas dipetakan. Misalnya, contoh kode C\$1 berikut memetakan kelas `Developer` ke tabel `People` di DynamoDB.
```
[DynamoDBTable("People")]
public class Developer { ...}
```
Atribut ini dapat diwariskan atau diganti.
+ Atribut `DynamoDBTable` dapat diwariskan. Dalam contoh sebelumnya, jika Anda menambahkan kelas baru, yaitu `Lead`, yang diwariskan dari kelas `Developer`, kelas tersebut juga dipetakan ke tabel `People`. Objek `Developer` dan `Lead` disimpan dalam tabel `People`.
+ Atribut `DynamoDBTable` juga dapat diganti. Dalam contoh kode C\$1 berikut, kelas `Manager` diwariskan dari kelas `Developer`. Namun, penambahan eksplisit atribut `DynamoDBTable` memetakan kelas ke tabel lainnya (`Managers`).
```
[DynamoDBTable("Managers")]
public class Manager : Developer { ...}
```
Anda dapat menambahkan parameter opsional, yaitu `LowerCamelCaseProperties`, untuk meminta DynamoDB menulis huruf pertama dari nama properti dalam huruf kecil ketika menyimpan objek ke tabel, seperti yang ditunjukkan dalam contoh C\$1 berikut.
```
[DynamoDBTable("People", LowerCamelCaseProperties=true)]
public class Developer
{
string DeveloperName;
...
}
```
Ketika menyimpan instans kelas `Developer`, `DynamoDBContext` menyimpan properti `DeveloperName` sebagai `developerName`.
## Dinamo DBVersion
Mengidentifikasi properti kelas untuk menyimpan nomor versi item. Untuk informasi selengkapnya tentang penentuan versi, lihat [Penguncian optimis menggunakan DynamoDB dan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.VersionSupport.md).
# DBContext Kelas Dynamo dari model persistensi objek.NET
Kelas `DynamoDBContext` adalah titik masuk ke basis data Amazon DynamoDB. Kelas ini menyediakan koneksi ke DynamoDB dan memungkinkan Anda mengakses data dalam berbagai tabel, melakukan berbagai operasi CRUD, dan menjalankan kueri. Kelas `DynamoDBContext` menyediakan metode berikut.
**Topics**
+ [Buat MultiTable BatchGet](#w2aac17b9c21c23c39b7)
+ [Buat MultiTable BatchWrite](#w2aac17b9c21c23c39b9)
+ [CreateBatchGet](#w2aac17b9c21c23c39c11)
+ [CreateBatchWrite](#w2aac17b9c21c23c39c13)
+ [Delete](#w2aac17b9c21c23c39c15)
+ [Dispose](#w2aac17b9c21c23c39c17)
+ [ExecuteBatchGet](#w2aac17b9c21c23c39c19)
+ [ExecuteBatchWrite](#w2aac17b9c21c23c39c21)
+ [FromDocument](#w2aac17b9c21c23c39c23)
+ [FromQuery](#w2aac17b9c21c23c39c25)
+ [FromScan](#w2aac17b9c21c23c39c27)
+ [GetTargetTable](#w2aac17b9c21c23c39c29)
+ [Muat](#w2aac17b9c21c23c39c31)
+ [Kueri](#w2aac17b9c21c23c39c33)
+ [Save](#w2aac17b9c21c23c39c35)
+ [Pindai](#w2aac17b9c21c23c39c37)
+ [ToDocument](#w2aac17b9c21c23c39c39)
+ [Menentukan parameter opsional untuk Dynamo DBContext](#OptionalConfigParams)
## Buat MultiTable BatchGet
Membuat objek `MultiTableBatchGet`, yang terdiri dari beberapa objek `BatchGet` individual. Setiap objek `BatchGet` dapat digunakan untuk mengambil item dari tabel DynamoDB tunggal.
Untuk mengambil item dari tabel, gunakan metode `ExecuteBatchGet`, dengan meneruskan objek `MultiTableBatchGet` sebagai parameter.
## Buat MultiTable BatchWrite
Membuat objek `MultiTableBatchWrite`, yang terdiri dari beberapa objek `BatchWrite` individual. Setiap objek `BatchWrite` dapat digunakan untuk menulis atau menghapus item dalam tabel DynamoDB tunggal.
Untuk menulis ke tabel, gunakan metode `ExecuteBatchWrite`, dengan meneruskan objek `MultiTableBatchWrite` sebagai parameter.
## CreateBatchGet
Membuat objek `BatchGet` yang dapat Anda gunakan untuk mengambil beberapa item dari tabel.
## CreateBatchWrite
Membuat objek `BatchWrite` yang dapat Anda gunakan untuk menempatkan beberapa item ke dalam tabel, atau untuk menghapus beberapa item dari tabel.
## Delete
Menghapus item dari tabel. Metode ini memerlukan kunci primer dari item yang ingin Anda hapus. Anda dapat memberikan nilai kunci primer maupun objek sisi klien yang berisi nilai kunci primer sebagai parameter untuk metode ini.
+ Jika Anda menentukan objek sisi klien sebagai parameter dan Anda telah mengaktifkan penguncian optimis, penghapusan hanya akan berhasil jika versi sisi klien dan sisi server objek cocok.
+ Jika Anda hanya menetapkan nilai kunci primer sebagai parameter, penghapusan akan berhasil terlepas dari apakah Anda telah mengaktifkan penguncian optimis atau tidak.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `DeleteAsync`.
## Dispose
Membuang semua sumber daya yang dikelola dan tidak dikelola.
## ExecuteBatchGet
Membaca data dari satu atau beberapa tabel, yang memproses semua objek `BatchGet` dalam `MultiTableBatchGet`.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `ExecuteBatchGetAsync`.
## ExecuteBatchWrite
Menulis atau menghapus data dalam satu atau beberapa tabel, yang memproses semua objek `BatchWrite` dalam `MultiTableBatchWrite`.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `ExecuteBatchWriteAsync`.
## FromDocument
Mengingat instans `Document`, metode `FromDocument` akan mengembalikan instans dari kelas sisi klien.
Langkah ini membantu jika Anda ingin menggunakan kelas model dokumen bersama dengan model persistensi objek untuk melakukan operasi data. Untuk informasi selengkapnya tentang kelas model dokumen yang disediakan oleh AWS SDK untuk .NET, lihat[Bekerja dengan model dokumen.NET di DynamoDB](DotNetSDKMidLevel.md).
Misalkan Anda memiliki objek `Document` bernama `doc`, yang berisi representasi item `Forum`. (Untuk mengetahui cara membuat objek ini, lihat deskripsi untuk metode `ToDocument` nanti dalam topik ini.) Anda dapat menggunakan `FromDocument` untuk mengambil item `Forum` dari `Document`, seperti yang ditunjukkan dalam contoh kode C\$1 berikut.
**Example**
```
forum101 = context.FromDocument(101);
```
**catatan**
Jika objek `Document` mengimplementasikan antarmuka `IEnumerable`, Anda dapat menggunakan metode `FromDocuments` sebagai gantinya. Metode ini memungkinkan Anda melakukan iterasi pada semua instans kelas dalam `Document`.
## FromQuery
Menjalankan operasi `Query`, dengan parameter kueri yang didefinisikan dalam objek `QueryOperationConfig`.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `FromQueryAsync`.
## FromScan
Menjalankan operasi `Scan`, dengan parameter pemindaian yang didefinisikan dalam objek `ScanOperationConfig`.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `FromScanAsync`.
## GetTargetTable
Mengambil tabel target untuk jenis yang ditentukan. Langkah ini berguna jika Anda menulis konverter khusus untuk memetakan data arbitrer ke tabel DynamoDB, dan Anda perlu menentukan tabel yang terkait dengan jenis data khusus.
## Muat
Mengambil item dari tabel. Metode ini hanya memerlukan kunci primer dari item yang ingin Anda ambil.
Secara default, DynamoDB akan mengembalikan item dengan nilai yang akhirnya konsisten. Untuk informasi tentang model konsistensi akhir, lihat [DynamoDB membaca konsistensi](HowItWorks.ReadConsistency.md).
`Load`atau `LoadAsync` metode memanggil [GetItem](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_GetItem.html)operasi, yang mengharuskan Anda untuk menentukan kunci utama untuk tabel. Karena `GetItem` mengabaikan `IndexName` parameter, Anda tidak dapat memuat item menggunakan partisi indeks atau kunci sortir. Oleh karena itu, Anda harus menggunakan kunci utama tabel untuk memuat item.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `LoadAsync`. Untuk melihat contoh penggunaan `LoadAsync` metode untuk melakukan operasi CRUD tingkat tinggi pada tabel DynamoDB, lihat contoh berikut.
```
///
/// Shows how to perform high-level CRUD operations on an Amazon DynamoDB
/// table.
///
public class HighLevelItemCrud
{
public static async Task Main()
{
var client = new AmazonDynamoDBClient();
DynamoDBContext context = new DynamoDBContext(client);
await PerformCRUDOperations(context);
}
public static async Task PerformCRUDOperations(IDynamoDBContext context)
{
int bookId = 1001; // Some unique value.
Book myBook = new Book
{
Id = bookId,
Title = "object persistence-AWS SDK for.NET SDK-Book 1001",
Isbn = "111-1111111001",
BookAuthors = new List { "Author 1", "Author 2" },
};
// Save the book to the ProductCatalog table.
await context.SaveAsync(myBook);
// Retrieve the book from the ProductCatalog table.
Book bookRetrieved = await context.LoadAsync(bookId);
// Update some properties.
bookRetrieved.Isbn = "222-2222221001";
// Update existing authors list with the following values.
bookRetrieved.BookAuthors = new List { " Author 1", "Author x" };
await context.SaveAsync(bookRetrieved);
// Retrieve the updated book. This time, add the optional
// ConsistentRead parameter using DynamoDBContextConfig object.
await context.LoadAsync(bookId, new DynamoDBContextConfig
{
ConsistentRead = true,
});
// Delete the book.
await context.DeleteAsync(bookId);
// Try to retrieve deleted book. It should return null.
Book deletedBook = await context.LoadAsync(bookId, new DynamoDBContextConfig
{
ConsistentRead = true,
});
if (deletedBook == null)
{
Console.WriteLine("Book is deleted");
}
}
}
```
## Kueri
Mengkueri tabel berdasarkan parameter kueri yang Anda berikan.
Anda dapat mengkueri tabel hanya jika memiliki kunci primer komposit (kunci partisi dan kunci urutan). Saat mengkueri, Anda harus menentukan kunci partisi dan syarat yang berlaku untuk kunci urutan.
Katakanlah Anda memiliki kelas `Reply` sisi klien yang dipetakan ke tabel `Reply` di DynamoDB. Contoh kode C\$1 berikut mengkueri tabel `Reply` untuk menemukan balasan utas dalam forum yang diposting dalam 15 hari terakhir. Tabel `Reply` memiliki kunci primer yang berisi kunci partisi `Id` dan kunci urutan `ReplyDateTime`.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
string replyId = "DynamoDB#DynamoDB Thread 1"; //Partition key
DateTime twoWeeksAgoDate = DateTime.UtcNow.Subtract(new TimeSpan(14, 0, 0, 0)); // Date to compare.
IEnumerable latestReplies = context.Query(replyId, QueryOperator.GreaterThan, twoWeeksAgoDate);
```
Tabel ini mengembalikan koleksi objek `Reply`.
Metode `Query` mengembalikan koleksi `IEnumerable` “lazy-loaded”. Metode ini awalnya hanya mengembalikan satu halaman hasil, lalu membuat panggilan layanan untuk halaman berikutnya jika diperlukan. Untuk mendapatkan semua item yang cocok, Anda perlu melakukan iterasi hanya pada `IEnumerable`.
Jika tabel Anda memiliki kunci primer sederhana (kunci partisi), Anda tidak dapat menggunakan metode `Query`. Sebaliknya, Anda dapat menggunakan metode `Load` dan menyediakan kunci partisi untuk mengambil item.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `QueryAsync`.
## Save
Menyimpan objek tertentu ke tabel. Jika kunci primer yang ditentukan dalam objek input tidak ada dalam tabel, metode akan menambahkan item baru ke tabel. Jika kunci primer ada, metode akan memperbarui item yang ada.
Jika Anda mengonfigurasi penguncian optimis, pembaruan hanya akan berhasil jika versi klien dan sisi server item cocok. Untuk informasi selengkapnya, lihat [Penguncian optimis menggunakan DynamoDB dan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.VersionSupport.md).
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `SaveAsync`.
## Pindai
Melakukan pemindaian pada seluruh tabel.
Anda dapat memfilter hasil pemindaian dengan menentukan syarat pemindaian. Syarat ini dapat dievaluasi pada setiap atribut dalam tabel. Katakanlah Anda memiliki kelas sisi klien `Book` yang dipetakan ke tabel `ProductCatalog` di DynamoDB. Contoh C\$1 berikut memindai tabel dan hanya mengembalikan item buku dengan harga kurang dari 0.
**Example**
```
IEnumerable itemsWithWrongPrice = context.Scan(
new ScanCondition("Price", ScanOperator.LessThan, price),
new ScanCondition("ProductCategory", ScanOperator.Equal, "Book")
);
```
Metode `Scan` mengembalikan koleksi `IEnumerable` “lazy-loaded”. Metode ini awalnya hanya mengembalikan satu halaman hasil, lalu membuat panggilan layanan untuk halaman berikutnya jika diperlukan. Untuk mendapatkan semua item yang cocok, Anda hanya perlu melakukan iterasi pada `IEnumerable`.
Untuk alasan performa, Anda harus mencari tabel dan menghindari pemindaian tabel.
**catatan**
Untuk melakukan operasi ini di latar belakang, gunakan metode `ScanAsync`.
## ToDocument
Mengembalikan instans untuk kelas model dokumen `Document` dari instans kelas Anda.
Langkah ini membantu jika Anda ingin menggunakan kelas model dokumen bersama dengan model persistensi objek untuk melakukan operasi data. Untuk informasi selengkapnya tentang kelas model dokumen yang disediakan oleh AWS SDK untuk .NET, lihat[Bekerja dengan model dokumen.NET di DynamoDB](DotNetSDKMidLevel.md).
Misalkan Anda memiliki kelas sisi klien yang dipetakan ke tabel `Forum` sampel. Anda kemudian dapat menggunakan `DynamoDBContext` untuk mendapatkan item sebagai objek `Document` dari tabel `Forum`, seperti yang ditunjukkan dalam contoh kode C\$1 berikut.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
Forum forum101 = context.Load(101); // Retrieve a forum by primary key.
Document doc = context.ToDocument(forum101);
```
## Menentukan parameter opsional untuk Dynamo DBContext
Saat menggunakan model persistensi objek, Anda dapat menentukan parameter opsional berikut untuk `DynamoDBContext`.
+ **`ConsistentRead`—**Saat mengambil data menggunakan operasi `Load`, `Query`, atau `Scan`, Anda dapat menambahkan parameter opsional ini guna meminta nilai data terbaru.
+ **`IgnoreNullValues`—**Parameter ini memberi tahu `DynamoDBContext` untuk mengabaikan nilai null pada atribut selama operasi `Save`. Jika parameter ini adalah false (atau jika tidak diatur), nilai null ditafsirkan sebagai direktif untuk menghapus atribut tertentu.
+ **`SkipVersionCheck`—** Parameter ini memberi tahu `DynamoDBContext` untuk tidak membandingkan versi saat menyimpan atau menghapus item. Untuk informasi selengkapnya tentang penentuan versi, lihat [Penguncian optimis menggunakan DynamoDB dan model persistensi objek AWS SDK untuk .NET](DynamoDBContext.VersionSupport.md).
+ **`TableNamePrefix`—** Memberikan prefiks pada semua nama tabel dengan string tertentu. Jika parameter ini adalah null (atau jika tidak diatur), tidak ada prefiks yang digunakan.
+ `DynamoDBEntryConversion`- Menentukan skema konversi yang digunakan oleh klien. Anda dapat mengatur parameter ini ke versi V1 atau V2. V1 adalah versi default.
Berdasarkan versi yang Anda tetapkan, perilaku parameter ini berubah. Contoh:
+ Di V1, tipe `bool` data dikonversi ke tipe `N` angka, di mana 0 mewakili false dan 1 mewakili true. Dalam V2, `bool` dikonversi ke`BOOL`.
+ Di V2, daftar dan array tidak dikelompokkan bersama. HashSets Daftar dan array numerik, tipe berbasis string, dan tipe berbasis biner dikonversi ke tipe `L` (Daftar), yang dapat dikirim kosong untuk memperbarui daftar. Ini tidak seperti V1, di mana daftar kosong tidak dikirim melalui kabel.
Di V1, jenis koleksi, seperti Daftar, HashSet, dan array diperlakukan sama. Daftar, HashSet, dan array numerik dikonversi ke tipe `NS` (jumlah set).
Contoh berikut menetapkan versi skema konversi ke V2, yang mengubah perilaku konversi antara tipe.NET dan tipe data DynamoDB.
```
var config = new DynamoDBContextConfig
{
Conversion = DynamoDBEntryConversion.V2
};
var contextV2 = new DynamoDBContext(client, config);
```
Contoh C \$1 berikut membuat yang baru `DynamoDBContext` dengan menentukan dua parameter opsional sebelumnya, dan. `ConsistentRead` `SkipVersionCheck`
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context =
new DynamoDBContext(client, new DynamoDBContextConfig { ConsistentRead = true, SkipVersionCheck = true});
```
`DynamoDBContext` menyertakan parameter opsional ini dengan setiap permintaan yang Anda kirimkan menggunakan konteks ini.
Alih-alih mengatur parameter ini di tingkat `DynamoDBContext`, Anda dapat menentukannya untuk setiap operasi yang Anda jalankan menggunakan `DynamoDBContext`, seperti yang ditunjukkan dalam contoh kode C\$1 berikut. Contoh ini memuat item buku tertentu. `Load`Metode `DynamoDBContext` menentukan `ConsistentRead` dan parameter `SkipVersionCheck` opsional.
**Example**
```
AmazonDynamoDBClient client = new AmazonDynamoDBClient();
...
DynamoDBContext context = new DynamoDBContext(client);
Book bookItem = context.Load(productId,new DynamoDBContextConfig{ ConsistentRead = true, SkipVersionCheck = true });
```
Dalam kasus ini, `DynamoDBContext` menyertakan parameter tersebut hanya ketika mengirimkan permintaan `Get`.
# Penguncian optimis menggunakan DynamoDB dan model persistensi objek AWS SDK untuk .NET
Dukungan penguncian optimis dalam model persistensi objek memastikan bahwa versi item untuk aplikasi Anda sama dengan versi item di sisi server sebelum memperbarui atau menghapus item. Misalkan Anda mengambil item untuk pembaruan. Namun, sebelum Anda mengirimkan pembaruan Anda kembali, beberapa aplikasi lain memperbarui item yang sama. Sekarang aplikasi Anda memiliki salinan item yang sudah usang. Tanpa penguncian optimis, setiap pembaruan yang Anda lakukan akan menimpa pembaruan yang dibuat oleh aplikasi lain.
Fitur penguncian optimis model persistensi objek menyediakan tanda `DynamoDBVersion` yang dapat Anda gunakan untuk mengaktifkan penguncian optimis. Untuk menggunakan fitur ini, Anda menambahkan properti ke kelas Anda untuk menyimpan nomor versi. Anda menambahkan atribut `DynamoDBVersion` untuk properti. Ketika Anda pertama kali menyimpan objek, `DynamoDBContext` menetapkan nomor versi dan menambah nilai ini setiap kali Anda memperbarui item.
Permintaan perbarui atau hapus Anda akan berhasil hanya jika versi objek sisi kliennya cocok dengan nomor versi item yang sesuai di sisi server. Jika aplikasi Anda memiliki salinan yang sudah usang, aplikasi tersebut harus mendapatkan versi terbaru dari server sebelum dapat memperbarui atau menghapus item.
Contoh kode C\$1 berikut mendefinisikan kelas `Book` dengan atribut persistensi objek yang memetakannya ke tabel `ProductCatalog`. Properti `VersionNumber` di kelas yang dilengkapi dengan atribut `DynamoDBVersion` menyimpan nilai nomor versi.
**Example**
```
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey] //Partition key
public int Id { get; set; }
[DynamoDBProperty]
public string Title { get; set; }
[DynamoDBProperty]
public string ISBN { get; set; }
[DynamoDBProperty("Authors")]
public List BookAuthors { get; set; }
[DynamoDBVersion]
public int? VersionNumber { get; set; }
}
```
**catatan**
Anda dapat menerapkan atribut `DynamoDBVersion` hanya untuk jenis primitif numerik yang dapat di-null-kan (seperti `int?`).
Penguncian optimis memiliki dampak berikut terhadap operasi `DynamoDBContext`:
+ Untuk item baru, `DynamoDBContext` menetapkan nomor versi awal 0. Jika Anda mengambil item yang ada, memperbarui satu atau beberapa properti, dan mencoba untuk menyimpan perubahan, operasi simpan hanya akan berhasil jika nomor versi di sisi klien dan sisi server cocok. `DynamoDBContext` menambahkan nomor versi. Anda tidak perlu mengatur nomor versi.
+ Metode `Delete` menyediakan beban berlebih yang dapat mengambil nilai kunci primer atau objek sebagai parameter, seperti yang ditunjukkan dalam contoh kode C\$1 berikut.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
...
// Load a book.
Book book = context.Load(111);
// Do other operations.
// Delete 1 - Pass in the book object.
context.Delete(book);
// Delete 2 - Pass in the Id (primary key)
context.Delete(222);
```
Jika Anda menyediakan objek sebagai parameter, penghapusan berhasil hanya jika versi objek cocok dengan versi item sisi server yang sesuai. Namun, jika Anda memberikan nilai kunci primer sebagai parameter, `DynamoDBContext` tidak mengenali nomor versi apa pun, dan menghapus item tanpa melakukan pemeriksaan versi.
Perhatikan bahwa implementasi internal penguncian optimis dalam kode model persistensi objek menggunakan tindakan API pembaruan bersyarat dan penghapusan bersyarat di DynamoDB.
## Menonaktifkan penguncian optimis
Untuk menonaktifkan penguncian optimis, gunakan properti konfigurasi `SkipVersionCheck`. Anda dapat mengatur properti ini saat membuat `DynamoDBContext`. Dalam kasus ini, penguncian optimis dinonaktifkan untuk permintaan apa pun yang Anda buat menggunakan konteks. Untuk informasi selengkapnya, lihat [Menentukan parameter opsional untuk Dynamo DBContext](DotNetDynamoDBContext.md#OptionalConfigParams).
Alih-alih menetapkan properti pada tingkat konteks, Anda dapat menonaktifkan penguncian optimis untuk operasi tertentu, seperti yang ditunjukkan dalam contoh kode C\$1 berikut. Contoh ini menggunakan konteks untuk menghapus item buku. Metode `Delete` menetapkan properti `SkipVersionCheck` opsional ke true, menonaktifkan pemeriksaan penentuan versi.
**Example**
```
DynamoDBContext context = new DynamoDBContext(client);
// Load a book.
Book book = context.Load(111);
...
// Delete the book.
context.Delete(book, new DynamoDBContextConfig { SkipVersionCheck = true });
```
# Memetakan data arbitrer dengan DynamoDB menggunakan model persistensi objek AWS SDK untuk .NET
Selain jenis .NET yang didukung (lihat [Jenis data yang didukung](DotNetSDKHighLevel.md#DotNetDynamoDBContext.SupportedTypes)), Anda dapat menggunakan jenis di aplikasi Anda yang tidak memiliki pemetaan langsung ke jenis Amazon DynamoDB. Model persistensi objek mendukung jenis penyimpanan data arbitrer selama Anda memberikan konverter untuk mengonversi data dari jenis arbitrer untuk jenis DynamoDB dan sebaliknya. Kode konverter mengubah data saat menyimpan dan memuat objek.
Anda dapat membuat jenis apa pun di sisi klien. Namun, data yang disimpan di tabel adalah salah satu jenis DynamoDB, dan selama kueri dan pemindaian, perbandingan data apa pun yang dibuat didasarkan pada data yang disimpan di DynamoDB.
Contoh kode C\$1 berikut mendefinisikan kelas `Book` dengan properti `Id`, `Title`, `ISBN`, dan `Dimension`. Properti `Dimension` adalah bagian dari `DimensionType` yang mendeskripsikan properti `Height`, `Width`, dan `Thickness`. Contoh kode ini menyediakan metode konverter `ToEntry` dan `FromEntry` untuk mengonversi data antara jenis string `DimensionType` dan DynamoDB. Misalnya, saat menyimpan instans `Book`, konverter membuat sebuah string `Dimension` buku seperti “8.5x11x.05". Saat Anda mengambil buku, konverter akan mengonversi string tersebut menjadi instans `DimensionType`.
Contoh ini memetakan jenis `Book` ke tabel `ProductCatalog`. Ini menyimpan instans `Book` sampel, mengambilnya, memperbarui dimensinya, dan menyimpan `Book` yang terbaru lagi.
Untuk step-by-step instruksi untuk menguji contoh berikut, lihat[Contoh kode .NET](CodeSamples.DotNet.md).
**Example**
```
using System;
using System.Collections.Generic;
using Amazon.DynamoDBv2;
using Amazon.DynamoDBv2.DataModel;
using Amazon.DynamoDBv2.DocumentModel;
using Amazon.Runtime;
using Amazon.SecurityToken;
namespace com.amazonaws.codesamples
{
class HighLevelMappingArbitraryData
{
private static AmazonDynamoDBClient client = new AmazonDynamoDBClient();
static void Main(string[] args)
{
try
{
DynamoDBContext context = new DynamoDBContext(client);
// 1. Create a book.
DimensionType myBookDimensions = new DimensionType()
{
Length = 8M,
Height = 11M,
Thickness = 0.5M
};
Book myBook = new Book
{
Id = 501,
Title = "AWS SDK for .NET Object Persistence Model Handling Arbitrary Data",
ISBN = "999-9999999999",
BookAuthors = new List { "Author 1", "Author 2" },
Dimensions = myBookDimensions
};
context.Save(myBook);
// 2. Retrieve the book.
Book bookRetrieved = context.Load(501);
// 3. Update property (book dimensions).
bookRetrieved.Dimensions.Height += 1;
bookRetrieved.Dimensions.Length += 1;
bookRetrieved.Dimensions.Thickness += 0.2M;
// Update the book.
context.Save(bookRetrieved);
Console.WriteLine("To continue, press Enter");
Console.ReadLine();
}
catch (AmazonDynamoDBException e) { Console.WriteLine(e.Message); }
catch (AmazonServiceException e) { Console.WriteLine(e.Message); }
catch (Exception e) { Console.WriteLine(e.Message); }
}
}
[DynamoDBTable("ProductCatalog")]
public class Book
{
[DynamoDBHashKey] //Partition key
public int Id
{
get; set;
}
[DynamoDBProperty]
public string Title
{
get; set;
}
[DynamoDBProperty]
public string ISBN
{
get; set;
}
// Multi-valued (set type) attribute.
[DynamoDBProperty("Authors")]
public List BookAuthors
{
get; set;
}
// Arbitrary type, with a converter to map it to DynamoDB type.
[DynamoDBProperty(typeof(DimensionTypeConverter))]
public DimensionType Dimensions
{
get; set;
}
}
public class DimensionType
{
public decimal Length
{
get; set;
}
public decimal Height
{
get; set;
}
public decimal Thickness
{
get; set;
}
}
// Converts the complex type DimensionType to string and vice-versa.
public class DimensionTypeConverter : IPropertyConverter
{
public DynamoDBEntry ToEntry(object value)
{
DimensionType bookDimensions = value as DimensionType;
if (bookDimensions == null) throw new ArgumentOutOfRangeException();
string data = string.Format("{1}{0}{2}{0}{3}", " x ",
bookDimensions.Length, bookDimensions.Height, bookDimensions.Thickness);
DynamoDBEntry entry = new Primitive
{
Value = data
};
return entry;
}
public object FromEntry(DynamoDBEntry entry)
{
Primitive primitive = entry as Primitive;
if (primitive == null || !(primitive.Value is String) || string.IsNullOrEmpty((string)primitive.Value))
throw new ArgumentOutOfRangeException();
string[] data = ((string)(primitive.Value)).Split(new string[] { " x " }, StringSplitOptions.None);
if (data.Length != 3) throw new ArgumentOutOfRangeException();
DimensionType complexData = new DimensionType
{
Length = Convert.ToDecimal(data[0]),
Height = Convert.ToDecimal(data[1]),
Thickness = Convert.ToDecimal(data[2])
};
return complexData;
}
}
}
```