Criar um item no Azure Cosmos DB para NoSQL usando .NET

Artigo
08/15/2024

APLICA-SE A: NoSQL

Os itens no Azure Cosmos DB representam uma entidade específica armazenada em um contêiner. Na API para NoSQL, um item consiste em dados formatados em JSON com um identificador exclusivo.

Criar um identificador exclusivo para um item

O identificador exclusivo é uma cadeia de caracteres distinta que identifica um item dentro de um contêiner. A id propriedade é a única propriedade necessária ao criar um novo documento JSON. Por exemplo, este documento JSON é um item válido no Azure Cosmos DB:

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

No escopo de um contêiner, dois itens não podem compartilhar o mesmo identificador exclusivo.

Importante

A id propriedade diferencia maiúsculas de minúsculas. As propriedades denominadas ID, Id, iDe _id serão tratadas como uma propriedade JSON arbitrária.

Uma vez criado, o URI de um item está neste formato:

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

Ao fazer referência ao item usando um URI, use o identificador de recurso gerado pelo sistema em vez do id campo. Para obter mais informações sobre propriedades de item geradas pelo sistema no Azure Cosmos DB para NoSQL, consulte Propriedades de um item

Criar um item

Nota

Os exemplos neste artigo pressupõem que você já definiu um tipo C# para representar seus dados chamado Product:

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

Os exemplos também pressupõem que você já criou um novo objeto do tipo Product chamado newItem:

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

Para criar um item, chame um dos seguintes métodos:

CreateItemAsync<>
ReplaceItemAsync<>
UpsertItemAsync<>

Criar um item de forma assíncrona

O exemplo a seguir cria um novo item de forma assíncrona:

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

O Container.CreateItemAsync<> método lançará uma exceção se houver um conflito com o identificador exclusivo de um item existente. Para saber mais sobre possíveis exceções, consulte CreateItemAsync<> exceções.

Substituir um item de forma assíncrona

O exemplo a seguir substitui um item existente de forma assíncrona:

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

O Container.ReplaceItemAsync<> método requer a cadeia de caracteres fornecida para que o id parâmetro corresponda ao identificador exclusivo do item parâmetro.

Criar ou substituir um item de forma assíncrona

O exemplo a seguir criará um novo item ou substituirá um item existente se um item já existir com o mesmo identificador exclusivo:

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

O Container.UpsertItemAsync<> método usará o identificador exclusivo do item parâmetro para determinar se há um conflito com um item existente e para substituir o item adequadamente.

Próximos passos

Agora que você criou vários itens, use o próximo guia para ler um item.

Ler um item

Partilhar via