Tworzenie dokumentów

6 min

Aby utworzyć nowy element, musimy najpierw utworzyć nową zmienną w kodzie języka C# typu Product .

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"
    }
};

Wywnioskujmy, że istnieje już zmienna typu Microsoft.Azure.Cosmos. Kontener o nazwie kontener.

Możemy asynchronicznie wywołać metodę CreateItemAsync<> przekazującą typ produktu i nową zmienną elementu do konstruktora.

await container.CreateItemAsync<Product>(saddle);

To wywołanie metody tworzy nowy element, ale nie ma żadnych metadanych dotyczących wyniku operacji. Alternatywnie można przechowywać wynik operacji w zmiennej typu ItemResponse<>.

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

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

Product item = response.Resource;

Jeśli używasz bloku try-catch, możesz obsłużyć typ CosmosException , który zawiera właściwość StatusCode dla wartości kodu stanu HTTP. Istnieje kilka typowych kodów stanu HTTP, które należy wziąć pod uwagę w kodzie aplikacji:

Code	Tytuł	Przyczyna
400	Nieprawidłowe żądanie	Wystąpił problem z elementem w treści żądania
403	Dostęp zabroniony	Kontener był prawdopodobnie pełny
409	Konflikt	Element w kontenerze prawdopodobnie miał już pasujący identyfikator
413	ŻądanieZbytDuże	Element przekracza maksymalny rozmiar jednostki
429	Zbyt wiele żądań	Bieżące żądanie przekracza maksymalną liczbę jednostek RU/s aprowizowanych dla kontenera

W poniższym przykładzie obsługujemy scenariusz powodujący konflikt, w którym element już istnieje w kontenerze i wracamy do ogólnego bloku obsługi wyjątków dla innych scenariuszy:

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
}

Aby utworzyć nowy element w kontenerze usługi Azure Cosmos DB, należy najpierw utworzyć wystąpienie modelu elementów. W języku Python ten proces można osiągnąć, definiując wystąpienie klasy Product .

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()

Pamiętaj, że klasa Product ma metodę to_dict , która konwertuje wystąpienie na słownik. Ta klasa mapuje także właściwość internal_id na właściwość id, której wymaga usługa Azure Cosmos DB.

Załóżmy, że istnieje już zmienna typu azure.cosmos.Container o nazwie container.

Możesz użyć metody create_item , aby utworzyć nowy element w kontenerze.

container.create_item(body=saddle)

To wywołanie metody tworzy nowy element, ale nie dostarcza metadanych dotyczących wyniku operacji. Alternatywnie możesz przechwycić odpowiedź operacji w zmiennej. Metoda get_response_headers() pobiera metadane dotyczące operacji, takie jak opłata za żądanie i wartość ETag utworzonego elementu, co umożliwia optymistyczne scenariusze współbieżności.

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: Jednostki żądań (RU) używane przez operację.
etag: unikatowa wartość reprezentująca wersję elementu.

Obsługa wyjątków

Zestaw SDK języka Python zgłasza wyjątki dla różnych scenariuszy. Te wyjątki można obsługiwać przy użyciu try-except bloku. Wyjątek CosmosHttpResponseError zawiera przydatne informacje, takie jak kod stanu HTTP. Niektóre typowe kody stanu HTTP, które mogą wystąpić, obejmują:

Code	Tytuł	Przyczyna
400	Nieprawidłowe żądanie	Wystąpił problem z elementem w treści żądania
403	Dostęp zabroniony	Kontener był prawdopodobnie pełny
409	Konflikt	Element w kontenerze prawdopodobnie miał już pasujący identyfikator
413	ŻądanieZbytDuże	Element przekracza maksymalny rozmiar jednostki
429	Zbyt wiele żądań	Bieżące żądanie przekracza maksymalną liczbę jednostek RU/s aprowizowanych dla kontenera

Oto przykład obsługi tych wyjątków:

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}")

Aby utworzyć nowy element, należy najpierw zdefiniować obiekt reprezentujący dane.

Definiowanie elementu

Zdefiniuj element w języku JavaScript jako obiekt ze wszystkimi niezbędnymi właściwościami. Na przykład poniżej przedstawiono sposób definiowania elementu produktu:

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
);

Ten obiekt ma następujące właściwości:

internalId: unikatowy identyfikator elementu.
categoryId: właściwość, która odpowiada ścieżce klucza partycji kontenera.
Inne właściwości, takie jak name, pricei tags, opisują element.

Pamiętaj, że klasa Product ma metodę toJSON() , która konwertuje obiekt na ciąg JSON. Ta klasa mapuje także właściwość internalId na właściwość id, której wymaga usługa Azure Cosmos DB.

Tworzenie elementu

Załóżmy, że istnieje już zmienna typu Container o nazwie container. Aby utworzyć element, możesz użyć metody items.create .

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

Ta metoda wysyła żądanie utworzenia elementu w kontenerze usługi Azure Cosmos DB.

Pobieranie metadanych

Odpowiedź metody items.create zawiera nagłówki, które dostarczają przydatnych metadanych dotyczących operacji, takich jak opłata za żądanie oraz wartość ETag, które umożliwiają optymistyczne scenariusze współbieżności.

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: Jednostki żądań (RU) używane przez operację.
etag: unikatowa wartość reprezentująca wersję elementu.

Obsługa błędów

Podczas tworzenia elementu mogą wystąpić błędy, takie jak konflikty lub nieprawidłowe żądania. Użyj bloku try-catch aby zająć się tymi błędami. Niektóre typowe kody stanu HTTP, które mogą wystąpić, obejmują:

Code	Tytuł	Przyczyna
400	Nieprawidłowe żądanie	Wystąpił problem z elementem w treści żądania
403	Dostęp zabroniony	Kontener był prawdopodobnie pełny
409	Konflikt	Element w kontenerze prawdopodobnie miał już pasujący identyfikator
413	ŻądanieZbytDuże	Element przekracza maksymalny rozmiar jednostki
429	Zbyt wiele żądań	Bieżące żądanie przekracza maksymalną liczbę jednostek RU/s aprowizowanych dla kontenera

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}`);
    }
}

Ta implementacja gwarantuje, że można tworzyć elementy, pobierać metadane do diagnostyki i bezpiecznie obsługiwać błędy.

Opinia

Czy ta strona była pomocna?