Condividi tramite

Leggere un elemento in Azure Cosmos DB for Table tramite .NET

  • Articolo

SI APPLICA A: Tabella

Gli elementi in Azure Cosmos DB rappresentano un'entità specifica archiviata all'interno di una tabella. Nell'API per Table un elemento è costituito da un set di coppie chiave-valore identificate in modo univoco dalla combinazione delle chiavi di riga e di partizione.

Creare un identificatore univoco per un elemento

L'identificatore univoco, noto a livello di codice come ****, è una stringa distinta che identifica un elemento all'interno di una tabella. Ogni elemento include anche un valore di chiave di partizione utilizzato per determinare la partizione logica per l'elemento. Entrambe le chiavi sono necessarie quando si crea un nuovo elemento all'interno di una tabella.

Nell'ambito di una tabella, due elementi non possono condividere la stessa chiave di riga e la stessa chiave di partizione.

Creare un elemento

La classe TableEntity è un'implementazione generica di un dizionario progettato in modo univoco per semplificare la creazione di un nuovo elemento da un dizionario arbitrario di coppie chiave-valore.

Usare una delle seguenti strategie per modellare gli elementi che si desidera creare in una tabella:

Utilizzare una classe integrata

Il (string rowKey, string partitionKey)costruttore della classe TableEntity rappresenta un modo rapido per creare un elemento con solo le proprietà necessarie. È quindi possibile usare il metodo Add per aggiungere ulteriori coppie chiave-valore all'elemento.

Ad esempio, è possibile creare una nuova istanza della classe TableEntity specificando innanzitutto le chiavi di riga e di partizione nel costruttore e quindi aggiungendo nuove coppie chiave-valore al dizionario:

// Create new item using composite key constructor
TableEntity item1 = new(
    rowKey: "68719518388",
    partitionKey: "gear-surf-surfboards"
);

// Add properties to item
item1.Add("Name", "Sunnox Surfboard");
item1.Add("Quantity", 8);
item1.Add("Sale", true);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item1);

Il (IDictionary<string, object>)costruttore della classe TableEntity converte un dizionario esistente in un elemento pronto per essere aggiunto a una tabella.

Ad esempio, è possibile passare un dizionario a una nuova istanza della classe TableEntity:

// Create dictionary
Dictionary<string, object> properties = new()
{
    { "RowKey", "68719518388" },
    { "PartitionKey", "gear-surf-surfboards" },
    { "Name", "Sunnox Surfboard" },
    { "Quantity", 8 },
    { "Sale", true }
};

// Create new item using dictionary constructor
TableEntity item2 = new(
    values: properties
);

// Add new item to server-side table
await tableClient.AddEntityAsync<TableEntity>(item2);

Il metodo TableClient.AddEntityAsync<> accetta un parametro di tipo TableEntity e quindi crea un elemento lato server nella tabella.

Implementare l'interfaccia

Nota

Gli esempi forniti in questa sezione presuppongono che sia già stato definito un tipo C# per rappresentare i dati denominati Prodotto:

// C# record type for items in the table
public record Product : ITableEntity
{
    public string RowKey { get; set; } = default!;

    public string PartitionKey { get; set; } = default!;

    public string Name { get; init; } = default!;

    public int Quantity { get; init; }

    public bool Sale { get; init; }

    public ETag ETag { get; set; } = default!;

    public DateTimeOffset? Timestamp { get; set; } = default!;
}

Il metodo TableClient.AddEntityAsync<> accetta un parametro di qualsiasi tipo che implementa l'interfacciaITableEntity. L'interfaccia include già le proprietà RowKey e PartitionKey necessarie.

Ad esempio, è possibile creare un nuovo oggetto che implementi almeno tutte le proprietà necessarie nell'interfaccia ITableEntity :

// Create new item
Product item = new()
{
    RowKey = "68719518388",
    PartitionKey = "gear-surf-surfboards",
    Name = "Sunnox Surfboard",
    Quantity = 8,
    Sale = true
};

È quindi possibile passare questo oggetto al metodo AddEntityAsync<> creando un elemento sul lato server:

// Add new item to server-side table
await tableClient.AddEntityAsync<Product>(item);

Passaggi successivi

Dopo aver creato vari elementi, utilizzare la guida successiva per seguire leggere un elemento.

Leggere un elemento