Criar um item no Azure Cosmos DB for NoSQL usando o .NET

Artigo
08/15/2024

APLICA-SE A: NoSQL

Os itens do Azure Cosmos DB representam uma entidade específica armazenada dentro de um contêiner. Na API do 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 propriedade id é a única obrigatória ao criar um 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 propriedade id diferencia maiúsculas de minúsculas. Propriedades denominadas ID, Id, iD e _id serão tratadas como uma propriedade JSON arbitrária.

Depois de criado, o URI de um item estará nesse 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 campo id. Para obter mais informações sobre propriedades de item geradas pelo sistema no Azure Cosmos DB for NoSQL, confira Propriedades de um item

Criar um item

Observação

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

// 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á tenha criado um objeto do tipo Produto denominado 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 modo assíncrono

O seguinte exemplo cria um item de modo assíncrono:

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

O método Container.CreateItemAsync<> gera uma exceção se ocorre algum conflito com o identificador exclusivo de um item existente. Para saber mais sobre possíveis exceções, confira CreateItemAsync<> exceções.

Substituir um item de modo assíncrono

O seguinte exemplo substitui um item existente de modo assíncrono:

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

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

Criar ou substituir um item de modo assíncrono

O seguinte exemplo cria um item ou substitui um item existente, se houver um item com o mesmo identificador exclusivo:

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

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

Próximas etapas

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

Ler um item

Compartilhar via