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

  • Artigo

APLICA-SE A: NoSQL

Os itens no Azure Cosmos DB representam uma entidade específica armazenada num contentor. 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 distinta que identifica um item num contentor. 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 âmbito de um contentor, dois itens não podem partilhar o mesmo identificador exclusivo.

Importante

A id propriedade é sensível a maiúsculas e minúsculas. As propriedades denominadas ID, Id, iDe _id serão tratadas como uma propriedade JSON arbitrária.

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

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

Ao referenciar o item com um URI, utilize o identificador de recursos gerado pelo sistema em vez do id campo. Para obter mais informações sobre as propriedades dos itens gerados pelo sistema no Azure Cosmos DB para NoSQL, veja as propriedades de um item

Criar um item

Nota

Os exemplos neste artigo partem do princípio de que já definiu um tipo C# para representar os seus dados denominados Produto:

// 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 partem do princípio de que já criou um novo objeto do tipo Produto com o nome 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:

Criar um item de forma assíncrona

O exemplo seguinte 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 existir um conflito com o identificador exclusivo de um item existente. Para saber mais sobre potenciais exceções, veja CreateItemAsync<> exceções.

Substituir um item de forma assíncrona

O exemplo seguinte 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 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 seguinte irá criar um novo item ou substituir um item existente se já existir um item com o mesmo identificador exclusivo:

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

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

Passos seguintes

Agora que criou vários itens, utilize o guia seguinte para ler um item.

Ler um item