Membuat dokumen

6 menit

Untuk membuat item baru, kita harus terlebih dahulu membuat variabel baru dalam kode C# dari Jenis produk .

Product saddle = new()
{
    id = "027D0B9A-F9D9-4C96-8213-C8546C4AAE71",
    categoryId = "26C74104-40BC-4541-8EF5-9892F7F03D72",
    name = "LL Road Seat/Saddle",
    price = 27.12d,
    tags = new string[] 
    {
        "brown",
        "weathered"
    }
};

Mari kita menyimpulkan sudah ada variabel jenis Microsoft.Azure.Cosmos. Kontainer bernama kontainer.

Kita dapat secara asinkron memanggil metode CreateItemAsync<> yang meneruskan jenis Produk dan variabel item baru ke dalam konstruktor.

await container.CreateItemAsync<Product>(saddle);

Pemanggilan metode ini membuat item baru, tetapi tidak memiliki metadata tentang hasil operasi. Atau, Anda dapat menyimpan hasil operasi dalam variabel jenis ItemResponse<>.

ItemResponse<Product> response = await container.CreateItemAsync<Product>(saddle);

HttpStatusCode status = response.StatusCode;
double requestUnits = response.RequestCharge;

Product item = response.Resource;

Jika Anda menggunakan blok try-catch, Anda dapat menangani jenis CosmosException , yang menyertakan properti StatusCode untuk nilai kode status HTTP. Ada beberapa kode status HTTP umum yang harus Anda pertimbangkan dalam kode aplikasi Anda:

Kode	Judul	Alasan
400	Permintaan Buruk	Ada yang salah dengan item di isi permintaan
403	Terlarang	Kontainer kemungkinan penuh
409	Konflik	Item dalam kontainer kemungkinan sudah memiliki id yang cocok
413	RequestEntityTooLarge	Item melebihi ukuran entitas maks
429	Terlalu Banyak Permintaan	Permintaan saat ini melebihi RU/dtk maksimum yang disediakan untuk kontainer

Dalam contoh berikut, kami menangani skenario konflik di mana item sudah ada di kontainer dan kembali ke blok penanganan pengecualian umum untuk skenario lain:

try
{
    await container.CreateItemAsync<Product>(saddle);
}
catch(CosmosException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // Add logic to handle conflicting ids
}
catch(CosmosException ex) 
{
    // Add general exception handling logic
}

Untuk membuat item baru dalam kontainer Azure Cosmos DB, Anda harus terlebih dahulu membuat instans model item Anda. Dalam Python, proses ini dapat dicapai dengan menentukan instans kelas Produk .

saddle = Product(
        internal_id="2a7816bf-9a3c-4f33-b7d7-84efb3923538",
        name="Road Warrior Saddle",
        category_id="26C74104-40BC-4541-8EF5-9892F7F03D72",
        price=65.15,
        tags=["black", "cushioned", "leather"]
    ).to_dict()

Ingat bahwa kelas Produk memiliki to_dict metode yang mengonversi instans menjadi kamus. Kelas ini juga memetakan properti internal_id menjadi properti id, yang diperlukan oleh Azure Cosmos DB.

Mari kita asumsikan sudah ada variabel dari jenis azure.cosmos.Container yang bernama kontainer.

Anda dapat menggunakan metode create_item untuk membuat item baru dalam kontainer.

container.create_item(body=saddle)

Pemanggilan metode ini membuat item baru, tetapi tidak menyediakan metadata tentang hasil operasi. Atau, Anda dapat menangkap respons operasi dalam variabel. Metode ini get_response_headers() mengambil metadata tentang operasi, seperti biaya permintaan dan nilai ETag dari item yang dibuat, yang memungkinkan skenario konkurensi optimis.

response = container.create_item(body=saddle)
# Get response headers
headers = response.get_response_headers()

# Retrieve the created item
item = response

# Extract metadata from headers
request_charge = headers.get('x-ms-request-charge')
etag = headers.get('etag')

# Output the metadata
print(f"Request Charge: {request_charge}")
print(f"etag: {etag}")

print(f"Item created: {item}")

x-ms-request-charge: Unit permintaan (RU) yang digunakan oleh operasi.
etag: Nilai unik yang mewakili versi item.

Menangani Pengecualian

Python SDK menimbulkan pengecualian untuk berbagai skenario. Anda dapat menangani pengecualian ini menggunakan try-except blok. Pengecualian CosmosHttpResponseError menyertakan informasi yang berguna seperti kode status HTTP. Beberapa kode status HTTP umum yang mungkin Anda temui meliputi:

Kode	Judul	Alasan
400	Permintaan Buruk	Ada yang salah dengan item di isi permintaan
403	Terlarang	Kontainer kemungkinan penuh
409	Konflik	Item dalam kontainer kemungkinan sudah memiliki id yang cocok
413	RequestEntityTooLarge	Item melebihi ukuran entitas maks
429	Terlalu Banyak Permintaan	Permintaan saat ini melebihi RU/dtk maksimum yang disediakan untuk kontainer

Berikut adalah contoh penanganan pengecualian ini:

from azure.cosmos.exceptions import CosmosHttpResponseError

try:
    container.create_item(body=saddle)
except CosmosHttpResponseError as ex:
    if ex.status_code == 409:  # Conflict
        print("Conflict: Item with the same id already exists.")
    elif ex.status_code == 429:  # Too Many Requests
        print("Too many requests: Reduce request rate or increase RU/s provisioned.")
    elif ex.status_code == 400:  # Bad Request
        print("Bad request: Check the structure of the item being sent.")
    else:
        print(f"HTTP error occurred: Status code {ex.status_code}, message: {ex.message}")
except Exception as ex:
    print(f"An unexpected error occurred: {ex}")

Untuk membuat item baru, Pertama-tama Anda perlu menentukan objek yang mewakili data Anda.

Tentukan Item

Tentukan item di JavaScript sebagai objek dengan semua properti yang diperlukan. Misalnya, berikut cara menentukan item produk:

const saddle = new Product(
    "027D0B9A-F9D9-4C96-8213-C8546C4AAE72", // internalId
    "LL Road Seat/Saddle", // name
    "26C74104-40BC-4541-8EF5-9892F7F03D72", // categoryId
    27.12, // price
    ["brown", "weathered"] // tags
);

Objek ini memiliki properti berikut:

internalId: Pengidentifikasi unik untuk item.
categoryId: Properti yang cocok dengan jalur kunci partisi kontainer.
Properti lain, seperti name, price, dan tags, yang menggambarkan barang.

Ingat bahwa kelas Produk memiliki toJSON() metode yang mengonversi objek menjadi string JSON. Kelas ini juga memetakan properti internalId menjadi properti id, yang diperlukan oleh Azure Cosmos DB.

Membuat Item

Asumsikan sudah ada variabel jenis Container yang bernama kontainer. Anda dapat menggunakan metode items.create untuk membuat item.

const { resource: item } = await container.items.create(saddle);

Metode ini mengirimkan permintaan untuk membuat item di kontainer Azure Cosmos DB.

Mengambil Metadata

Respons dari metode ini items.create mencakup header yang menyediakan metadata yang berguna tentang operasi, seperti biaya permintaan dan nilai ETag, yang memungkinkan skenario konkurensi optimis.

const { resource: item, headers } = await container.items.create(saddle);

const requestCharge = headers["x-ms-request-charge"];
const etag = headers.etag;

console.log(`Request Charge: ${requestCharge}`);
console.log(`etag: ${etag}`);
console.log("Item created:", item);

x-ms-request-charge: Unit permintaan (RU) yang digunakan oleh operasi.
etag: Nilai unik yang mewakili versi item.

Menangani Kesalahan

Saat Anda membuat item, kesalahan mungkin terjadi, seperti konflik atau permintaan yang tidak valid. Gunakan blok try-catch untuk menangani kesalahan ini. Beberapa kode status HTTP umum yang mungkin Anda temui meliputi:

Kode	Judul	Alasan
400	Permintaan Buruk	Ada yang salah dengan item di isi permintaan
403	Terlarang	Kontainer kemungkinan penuh
409	Konflik	Item dalam kontainer kemungkinan sudah memiliki id yang cocok
413	RequestEntityTooLarge	Item melebihi ukuran entitas maks
429	Terlalu Banyak Permintaan	Permintaan saat ini melebihi RU/dtk maksimum yang disediakan untuk kontainer

try {
    const { resource: item, headers } = await container.items.create(saddle);
    console.log("Item created:", item);
} catch (error) {
    if (error.code === 409) {
        console.log(`Conflict: Item with the same id (${saddle.id}) already exists.`);
    } else if (error.code === 429) {
        console.log("Too many requests: Reduce request rate or increase RU/s provisioned.");
    } else if (error.code === 400) {
        console.log("Bad request: Check the structure of the item being sent.");
    } else {
        console.log(`An unexpected error occurred: ${error.message}`);
    }
}

Implementasi ini memastikan bahwa Anda dapat membuat item, mengambil metadata untuk diagnostik, dan menangani kesalahan dengan anggun.

Saran dan Komentar

Apakah halaman ini membantu?