Tworzenie elementu w usłudze Azure Cosmos DB dla NoSQL przy użyciu platformy .NET

Artykuł
05/23/2023

DOTYCZY: NoSQL

Elementy w usłudze Azure Cosmos DB reprezentują określoną jednostkę przechowywaną w kontenerze. W interfejsie API dla NoSQL element składa się z danych w formacie JSON z unikatowym identyfikatorem.

Tworzenie unikatowego identyfikatora elementu

Unikatowy identyfikator jest odrębnym ciągiem, który identyfikuje element w kontenerze. Właściwość id jest jedyną wymaganą właściwością podczas tworzenia nowego dokumentu JSON. Na przykład ten dokument JSON jest prawidłowym elementem w usłudze Azure Cosmos DB:

{
  "id": "unique-string-2309509"
}

W zakresie kontenera dwa elementy nie mogą współużytkować tego samego unikatowego identyfikatora.

Ważne

W id właściwości jest rozróżniana wielkość liter. Właściwości o nazwie ID, , IdiDi _id będą traktowane jako dowolna właściwość JSON.

Po utworzeniu identyfikator URI elementu ma następujący format:

https://<cosmos-account-name>.documents.azure.com/dbs/<database-name>/docs/<item-resource-identifier>

W przypadku odwoływania się do elementu przy użyciu identyfikatora URI użyj identyfikatora zasobu wygenerowanego przez system zamiast id pola. Aby uzyskać więcej informacji na temat właściwości elementów generowanych przez system w usłudze Azure Cosmos DB dla NoSQL, zobacz właściwości elementu

Tworzenie elementu

Uwaga

W przykładach w tym artykule przyjęto założenie, że zdefiniowano już typ języka C#, aby reprezentować dane o nazwie Product:

// C# record type for items in the container
public record Product(
    string id,
    string category,
    string name,
    int quantity,
    bool sale
);

W przykładach założono również, że utworzono już nowy obiekt typu Product o nazwie newItem:

// Create new item and add to container
Product item = new(
    id: "68719518388",
    category: "gear-surf-surfboards",
    name: "Sunnox Surfboard",
    quantity: 8,
    sale: true
);

Aby utworzyć element, wywołaj jedną z następujących metod:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Asynchronicznie tworzenie elementu

Poniższy przykład tworzy nowy element asynchronicznie:

Product createdItem = await container.CreateItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Metoda Container.CreateItemAsync<> zgłosi wyjątek, jeśli wystąpi konflikt z unikatowym identyfikatorem istniejącego elementu. Aby dowiedzieć się więcej o potencjalnych wyjątkach, zobacz CreateItemAsync<> wyjątki.

Asynchroniczne zastępowanie elementu

Poniższy przykład zastępuje istniejący element asynchronicznie:

Product replacedItem = await container.ReplaceItemAsync<Product>(
    item: item,
    id: "68719518388",
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Metoda Container.ReplaceItemAsync<> wymaga podanego ciągu parametru id , aby był zgodny z unikatowym identyfikatorem parametru item .

Tworzenie lub zastępowanie elementu asynchronicznie

Poniższy przykład spowoduje utworzenie nowego elementu lub zastąpienie istniejącego elementu, jeśli element już istnieje o tym samym unikatowym identyfikatorze:

Product upsertedItem = await container.UpsertItemAsync<Product>(
    item: item,
    partitionKey: new PartitionKey("gear-surf-surfboards")
);

Metoda Container.UpsertItemAsync<> użyje unikatowego identyfikatora parametru item , aby określić, czy występuje konflikt z istniejącym elementem i odpowiednio zastąpić element.

Następne kroki

Po utworzeniu różnych elementów użyj następnego przewodnika, aby odczytać element.

Odczytywanie elementu

Share via