Creare un elemento in Azure Cosmos DB for NoSQL con JavaScript

SI APPLICA A: NoSQL

Gli elementi in Azure Cosmos DB rappresentano un'entità specifica archiviata all'interno di un contenitore. Nell'API for NoSQL un elemento è costituito da dati in formato JSON con un identificatore univoco.

Elemento, definizione dell'elemento e risposta dell'elemento

In JavaScript SDK i tre oggetti correlati a un elemento hanno scopi diversi.

Nome	Operazioni
Articolo	Funzionalità, tra cui Read, Patch, Replace, Delete.
ItemDefinition	Oggetto dati personalizzato. Include automaticamente le proprietà id e ttl.
ItemResponse	Include statusCode, item e altre proprietà.

Usare le proprietà dell'oggetto ItemResponse per comprendere il risultato dell'operazione.

• statusCode: codice di stato HTTP. Una risposta con esito positivo rientra nell'intervallo 200-299.
• activityId: identificatore univoco dell'operazione, ad esempio create, read, replace o delete.
• etag: tag di entità associato ai dati. Usarlo per la concorrenza ottimistica, la memorizzazione nella cache e le richieste condizionali.
• item: oggetto Item usato per eseguire operazioni quali read, replace, delete.
• resource: dati personalizzati.

Creare un identificatore univoco per un elemento

L'identificatore univoco è una stringa distinta che identifica un elemento all'interno di un contenitore. La proprietà id è l'unica proprietà obbligatoria quando si crea un nuovo documento JSON. Questo documento JSON, ad esempio, è un elemento valido in Azure Cosmos DB:

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

Nell'ambito di un contenitore due elementi non possono condividere lo stesso identificatore univoco.

Importante

La proprietà id fa distinzione tra maiuscole e minuscole. Le proprietà denominate ID, Id, iD e _id verranno considerate come proprietà JSON arbitrarie.

Dopo la creazione il formato dell'URI per un elemento è il seguente:

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

Per fare riferimento all'elemento con un URI, usare l'identificatore di risorsa generato dal sistema invece del campo id. Per altre informazioni sulle proprietà degli elementi generati dal sistema in Azure Cosmos DB for NoSQL, vedere Proprietà di un elemento

Creare un elemento

Creare un elemento con l'oggetto items del contenitore con il metodo create.

const { statusCode, item, resource, activityId, etag} = await container.items.create({ 
        id: '2', 
        category: 'gear-surf-surfboards',
        name: 'Sunnox Surfboard',
        quantity: 8,
        sale: true 
    });

Accedere a un elemento

Accedere a un elemento tramite l'oggetto Item. È possibile accedervi dall'oggetto Container o modificarlo dagli oggetti Database o CosmosClient.

// Chained, then use a method of the Item object such as `read`
const { statusCode, item, resource, activityId, etag} = await client.database(databaseId).container(containerId).item(itemId).read();

Accesso in base all'oggetto:

• Items (plurale): creare, eseguire in batch, osservare il feed di modifiche, leggere tutto, eseguire l'upsert o eseguire query sugli elementi.
• Item (singolare): leggere, applicare patch, sostituire o eliminare un elemento.

Sostituire un elemento

Sostituire i dati associati all'oggetto Item con il metodo replace.

const { statusCode, item, resource, activityId, etag} = await item.replace({ 
        id: '2', 
        category: 'gear-surf-surfboards-retro',
        name: 'Sunnox Surfboard Retro',
        quantity: 5,
        sale: false 
    });

Leggere un elemento

Leggere i dati più aggiornati con il metodo read dell'oggetto Item.

const { statusCode, item, resource, activityId, etag} = await item.read();

Eliminare un elemento

Eliminare l'elemento con il metodo delete dell'oggetto Item.

const { statusCode, item, activityId, etag} = await item.delete();

Passaggi successivi

Dopo aver creato vari elementi, usare la guida successiva per eseguire query per ottenere l'elemento.

Leggere un elemento