Introduzione ad Azure Cosmos DB: API di DocumentDBIntroduction to Azure Cosmos DB: DocumentDB API

Azure Cosmos DB è il servizio di database multimodello distribuito a livello globale di Microsoft per applicazioni cruciali.Azure Cosmos DB is Microsoft's globally distributed, multi-model database service for mission-critical applications. Azure Cosmos DB offre distribuzione globale predefinita, scalabilità elastica in termini di archiviazione e velocità effettiva ovunque nel mondo, latenze pari a singole unità di millisecondi al 99° percentile, cinque livelli di coerenza ben definiti e disponibilità elevata garantita, il tutto supportato da contratti di servizio leader del settore.Azure Cosmos DB provides turn-key global distribution, elastic scaling of throughput and storage worldwide, single-digit millisecond latencies at the 99th percentile, five well-defined consistency levels, and guaranteed high availability, all backed by industry-leading SLAs. Azure Cosmos DB indicizza automaticamente i dati senza che sia necessario gestire manualmente indici e schemi.Azure Cosmos DB automatically indexes data without requiring you to deal with schema and index management. Si tratta di un database multimodello che supporta modelli di dati di documenti, coppie chiave-valore, grafi e colonne.It is multi-model and supports document, key-value, graph, and columnar data models.

API di Azure DocumentDB

Con l'API di DocumentDB, Azure Cosmos DB offre funzionalità di query SQL avanzate e già note con latenze sempre basse sui dati JSON senza schema.With the DocumentDB API, Azure Cosmos DB provides rich and familiar SQL query capabilities with consistent low latencies over schema-less JSON data. Questo articolo offre una panoramica dell'API di DocumentDB di Azure Cosmos DB e ne illustra l'uso per l'archiviazione di volumi elevati di documenti JSON, l'esecuzione di query con latenze di millisecondi e la semplice evoluzione dello schema.In this article, we provide an overview of the Azure Cosmos DB's DocumentDB API, and how you can use it to store massive volumes of JSON data, query them within order of milliseconds latency, and evolve the schema easily.

Capacità e funzionalità chiave offerte da Azure Cosmos DBWhat capabilities and key features does Azure Cosmos DB offer?

Di seguito sono riportati i vantaggi e le funzionalità chiave offerti da Azure Cosmos DB mediante l'API di DocumentDB:Azure Cosmos DB, via the DocumentDB API, offers the following key capabilities and benefits:

  • Velocità effettiva e archiviazione con scalabilità elastica: è possibile aumentare o ridurre le prestazioni del database JSON in base alle esigenze dell'applicazione.Elastically scalable throughput and storage: Easily scale up or scale down your JSON database to meet your application needs. I dati sono archiviati in unità SSD (Solid State Drive) per garantire livelli di latenza bassi e prevedibili.Your data is stored on solid state disks (SSD) for low predictable latencies. Azure Cosmos DB supporta contenitori di archiviazione dei dati JSON, chiamati raccolte, che possono raggiungere dimensioni di archiviazione e velocità effettiva con provisioning quasi illimitate.Azure Cosmos DB supports containers for storing JSON data called collections that can scale to virtually unlimited storage sizes and provisioned throughput. Azure Cosmos DB offre una semplice scalabilità elastica e prestazioni prevedibili in base alla crescita dell'applicazione.You can elastically scale Azure Cosmos DB with predictable performance seamlessly as your application grows.

  • Replica multiarea: Azure Cosmos DB replica in modo trasparente i dati in tutte le aree associate all'account Azure Cosmos DB, consentendo lo sviluppo di applicazioni che richiedono l'accesso globale ai dati, con il necessario compromesso tra coerenza, disponibilità e prestazioni, tutto con le garanzie corrispondenti.Multi-region replication: Azure Cosmos DB transparently replicates your data to all regions you've associated with your Azure Cosmos DB account, enabling you to develop applications that require global access to data while providing tradeoffs between consistency, availability and performance, all with corresponding guarantees. Azure Cosmos DB fornisce il failover trasparente a livello di area con le API multihosting e la possibilità di aumentare o ridurre la velocità effettiva e le risorse di archiviazione in tutto il mondo.Azure Cosmos DB provides transparent regional failover with multi-homing APIs, and the ability to elastically scale throughput and storage across the globe. Per altre informazioni, vedere Distribuire i dati a livello globale con Azure Cosmos DB.Learn more in Distribute data globally with Azure Cosmos DB.

  • Query ad hoc con sintassi SQL familiare: è possibile archiviare documenti JSON eterogenei ed eseguire query su di essi usando una sintassi SQL familiare.Ad hoc queries with familiar SQL syntax: Store heterogeneous JSON documents and query these documents through a familiar SQL syntax. Azure Cosmos DB da uso di una tecnologia di indicizzazione a simultaneità elevata, priva di blocchi, con registrazione strutturata per indicizzare automaticamente l'intero contenuto dei documenti.Azure Cosmos DB utilizes a highly concurrent, lock free, log structured indexing technology to automatically index all document content. Ciò permette l'esecuzione di query avanzate in tempo reale, senza dovere specificare hint di schema, indici secondari o visualizzazioni.This enables rich real-time queries without the need to specify schema hints, secondary indexes, or views. Per altre informazioni, vedere Query in Azure Cosmos DB.Learn more in Query Azure Cosmos DB.

  • Esecuzione di JavaScript nel database: è possibile esprimere la logica dell'applicazione sotto forma di stored procedure, trigger e funzioni definite dall'utente (UDF, User Defined Functions) tramite JavaScript standard.JavaScript execution within the database: Express application logic as stored procedures, triggers, and user defined functions (UDFs) using standard JavaScript. Ciò permette alla logica dell'applicazione di operare sui dati, senza preoccuparsi della mancata corrispondenza tra l'applicazione e lo schema di database.This allows your application logic to operate over data without worrying about the mismatch between the application and the database schema. L'API di DocumentDB offre l'esecuzione transazionale completa della logica dell'applicazione JavaScript direttamente nel motore di database.The DocumentDB API provides full transactional execution of JavaScript application logic directly inside the database engine. La profonda integrazione di JavaScript permette l'esecuzione di operazioni INSERT, REPLACE, DELETE e SELECT da un programma JavaScript come transazione isolata.The deep integration of JavaScript enables the execution of INSERT, REPLACE, DELETE, and SELECT operations from within a JavaScript program as an isolated transaction. Ulteriori informazioni sono disponibili in Programmazione sul lato server di DocumentDB.Learn more in DocumentDB server-side programming.

  • Livelli di coerenza perfezionabili: è possibile scegliere tra cinque livelli di coerenza ben definiti per ottenere un compromesso ottimale tra coerenza e prestazioni.Tunable consistency levels: Select from five well defined consistency levels to achieve optimal trade-off between consistency and performance. Per query e operazioni di lettura, Azure Cosmos DB offre cinque livelli di coerenza distinti, ovvero avanzata, con decadimento ristretto, sessione, prefisso coerente e futura.For queries and read operations, Azure Cosmos DB offers five distinct consistency levels: strong, bounded-staleness, session, consistent prefix, and eventual. Questi livelli di coerenza granulari e ben definiti permettono di ottenere compromessi efficaci tra coerenza, disponibilità e latenza.These granular, well-defined consistency levels allow you to make sound trade-offs between consistency, availability, and latency. Per altre informazioni, vedere Uso dei livelli di coerenza per ottimizzare la disponibilità e le prestazioni.Learn more in Using consistency levels to maximize availability and performance.

  • Completamente gestito: è possibile eliminare la necessità di gestire risorse di database e computer.Fully managed: Eliminate the need to manage database and machine resources. Questo servizio Microsoft Azure completamente gestito non richiede la gestione di macchine virtuali, la distribuzione e la configurazione di software, la gestione del ridimensionamento o complessi aggiornamenti di livello dati.As a fully-managed Microsoft Azure service, you do not need to manage virtual machines, deploy and configure software, manage scaling, or deal with complex data-tier upgrades. Il backup di ogni database è eseguito automaticamente e ogni database è protetto da errori nell'area geografica specifica.Every database is automatically backed up and protected against regional failures. La possibilità di aggiungere con facilità account e capacità di provisioning di Azure Cosmos DB in base alla necessità permette di concentrarsi sull'applicazione invece che sul funzionamento e sulla gestione del database.You can easily add an Azure Cosmos DB account and provision capacity as you need it, allowing you to focus on your application instead of operating and managing your database.

  • Progettazione aperta: è possibile iniziare subito a lavorare usando le competenze e gli strumenti esistenti.Open by design: Get started quickly by using existing skills and tools. La programmazione per l'API di DocumentDB è semplice, intuitiva e non richiede l'adozione di nuovi strumenti o l'adesione a estensioni personalizzate per JSON o JavaScript.Programming against the DocumentDB API is simple, approachable, and does not require you to adopt new tools or adhere to custom extensions to JSON or JavaScript. È possibile accedere a tutte le funzionalità del database, incluso CRUD, l'elaborazione di JavaScript e query in una semplice interfaccia HTTP RESTful.You can access all of the database functionality including CRUD, query, and JavaScript processing over a simple RESTful HTTP interface. L'API di DocumentDB accetta i formati, i linguaggi e gli standard esistenti, offrendo al tempo stesso capacità di database di livello elevato.The DocumentDB API embraces existing formats, languages, and standards while offering high value database capabilities on top of them.

  • Indicizzazione automatica: per impostazione predefinita, Azure Cosmos DB indicizza automaticamente tutti i documenti nel database e non prevede né richiede schemi o la creazione di indici secondari.Automatic indexing: By default, Azure Cosmos DB automatically indexes all the documents in the database and does not expect or require any schema or creation of secondary indices. Se non si vuole indicizzare ogni elemento,Don't want to index everything? è anche possibile rifiutare esplicitamente i percorsi nei file JSON.Don't worry, you can opt out of paths in your JSON files too.

  • Supporto del feed delle modifiche: il feed delle modifiche offre un elenco di documenti in una raccolta di Azure Cosmos DB, nell'ordine in cui questi sono stati modificati.Change feed support: Change feed provides a sorted list of documents within an Azure Cosmos DB collection in the order in which they were modified. Questo feed può essere usato per restare in ascolto delle modifiche ai dati per replicare i dati, attivare le chiamate API o eseguire l'elaborazione dei flussi negli aggiornamenti.This feed can be used to listen for modifications to data in order to replicate data, trigger API calls or perform stream processing on updates. Il feed delle modifiche viene abilitato automaticamente ed è facile da usare: altre informazioni sul feed delle modifiche.Change feed is automatically enabled and easy to use: learn more about change feed.

Come gestire i dati con l'API di DocumentDBHow do you manage data with the DocumentDB API?

L'API di DocumentDB consente di gestire i dati JSON tramite risorse di database ben definite.The DocumentDB API helps manage JSON data through well-defined database resources. Queste risorse sono replicate per ottenere disponibilità elevata e sono indirizzabili in modo univoco da parte dei rispettivi URI logici.These resources are replicated for high availability and are uniquely addressable by their logical URI. L'API di DocumentDB offre un semplice modello di programmazione RESTful basato su HTTP per tutte le risorse.The DocumentDB API offers a simple HTTP based RESTful programming model for all resources.

L'account di database di Azure Cosmos DB è uno spazio dei nomi univoco che permette di accedere ad Azure Cosmos DB.The Azure Cosmos DB database account is a unique namespace that gives you access to Azure Cosmos DB. Prima di creare un account di database, è necessario avere una sottoscrizione di Azure, che consente di accedere ai diversi servizi di Azure.Before you can create a database account, you must have an Azure subscription, which gives you access to a variety of Azure services.

Tutte le risorse disponibili in Azure Cosmos DB sono modellate e archiviate come documenti JSON.All resources within Azure Cosmos DB are modeled and stored as JSON documents. Le risorse sono gestite come elementi, ovvero documenti JSON contenenti metadati, e come feed, ovvero raccolte di elementi.Resources are managed as items, which are JSON documents containing metadata, and as feeds which are collections of items. Gli insiemi di elementi sono inclusi nei rispettivi feed.Sets of items are contained within their respective feeds.

La figura seguente mostra le relazioni tra le risorse di Azure Cosmos DB:The image below shows the relationships between the Azure Cosmos DB resources:

Relazione gerarchica tra le risorse in Azure Cosmos DB

Un account di database è costituito da un insieme di database, ognuno dei quali include più raccolte, che possono contenere stored procedure, trigger, UDF, documenti e allegati correlati.A database account consists of a set of databases, each containing multiple collections, each of which can contain stored procedures, triggers, UDFs, documents, and related attachments. Un database include anche utenti associati, ognuno dei quali ha un insieme di autorizzazioni per accedere alle diverse raccolte, stored procedure, trigger, UDF, documenti o allegati disponibili.A database also has associated users, each with a set of permissions to access various other collections, stored procedures, triggers, UDFs, documents, or attachments. Mentre i database, gli utenti, le autorizzazioni e le raccolte sono risorse definite dal sistema con schemi noti, i documenti, le stored procedure, i trigger, le funzioni UDF e gli allegati includono contenuto JSON arbitrario definito dagli utenti.While databases, users, permissions, and collections are system-defined resources with well-known schemas - documents, stored procedures, triggers, UDFs, and attachments contain arbitrary, user defined JSON content.

Nota

Dal momento che l'API di DocumentDB era precedentemente disponibile come servizio Azure DocumentDB, è possibile continuare a effettuare il provisioning, monitorare e gestire gli account creati tramite gli strumenti o l'API REST di Azure Resource Manager usando i nomi di risorse di Azure DocumentDB o di Azure Cosmos DB.Since the DocumentDB API was previously available as the Azure DocumentDB service, you can continue to provision, monitor, and manage accounts created via the Azure Resource Management REST API or tools using either the Azure DocumentDB or Azure Cosmos DB resource names. In riferimento alle API di Azure DocumentDB i nomi vengono usati in modo intercambiabile.We use the names interchangeably when referring to the Azure DocumentDB APIs.

Sviluppo di app con l'API di DocumentDBHow can I develop apps with the DocumentDB API?

Azure Cosmos DB espone le risorse tramite le API REST che possono essere chiamate da qualsiasi linguaggio in grado di inviare richieste HTTP/HTTPS.Azure Cosmos DB exposes resources through the REST APIs that can be called by any language capable of making HTTP/HTTPS requests. Sono anche disponibili librerie di programmazione per diversi linguaggi comuni per l'API di DocumentDB.Additionally, we offer programming libraries for several popular languages for the DocumentDB API. Le librerie client semplificano molti aspetti dell'uso dell'API, grazie alla gestione di dettagli quali la memorizzazione nella cache degli indirizzi, la gestione delle eccezioni, i tentativi automatici e così via.The client libraries simplify many aspects of working with the API by handling details such as address caching, exception management, automatic retries and so forth. Le librerie attualmente disponibili riguardano i linguaggi e le piattaforme seguenti:Libraries are currently available for the following languages and platforms:

ScaricareDownload DocumentazioneDocumentation
.NET SDK.NET SDK Libreria .NET.NET library
Node.js SDKNode.js SDK Libreria Node.jsNode.js library
SDK per JavaJava SDK Libreria JavaJava library
JavaScript SDKJavaScript SDK Libreria JavaScriptJavaScript library
n/dn/a JavaScript SDK lato serverServer-side JavaScript SDK
Python SDKPython SDK Libreria di PythonPython library
N/Dn/a API per MongoDBAPI for MongoDB

Usando l'emulatore di Azure Cosmos DB, è possibile sviluppare e testare l'applicazione in locale con l'API di DocumentDB, senza creare una sottoscrizione di Azure né sostenere costi.Using the Azure Cosmos DB Emulator, you can develop and test your application locally with the DocumentDB API, without creating an Azure subscription or incurring any costs. Quando si è soddisfatti del funzionamento dell'applicazione nell'emulatore, è possibile iniziare a usare l'account Azure Cosmos DB nel cloud.When you're satisfied with how your application is working in the emulator, you can switch to using an Azure Cosmos DB account in the cloud.

Oltre alle operazioni di base di creazione, lettura, aggiornamento ed eliminazione, l'API di DocumentDB offre un'interfaccia di query SQL avanzata per il recupero di documenti JSON e supporto lato server per l'esecuzione transazionale di logica dell'applicazione JavaScript.Beyond basic create, read, update, and delete operations, the DocumentDB API provides a rich SQL query interface for retrieving JSON documents and server side support for transactional execution of JavaScript application logic. Le interfacce di esecuzione di query e script sono disponibili tramite tutte le librerie delle piattaforme, oltre alle API REST.The query and script execution interfaces are available through all platform libraries as well as the REST APIs.

Query SQLSQL query

L'API di DocumentDB supporta l'esecuzione di query sui documenti tramite un linguaggio SQL, basato sul sistema di tipi JavaScript, ed espressioni con supporto per query relazionali, gerarchiche e spaziali.The DocumentDB API supports querying documents using a SQL language, which is rooted in the JavaScript type system, and expressions with support for relational, hierarchical, and spatial queries. Il linguaggio di query di DocumentDB è un'interfaccia semplice ma avanzata per l'esecuzione di query su documenti JSON.The DocumentDB query language is a simple yet powerful interface to query JSON documents. Il linguaggio supporta un sottoinsieme della grammatica SQL ANSI e aggiunge un'integrazione profonda di oggetti JavaScript, matrici, costruzione di oggetti e chiamata di funzioni.The language supports a subset of ANSI SQL grammar and adds deep integration of JavaScript object, arrays, object construction, and function invocation. L'API di DocumentDB offre il modello di query senza schemi espliciti o hint di indicizzazioni dallo sviluppatore.The DocumentDB API provides its query model without any explicit schema or indexing hints from the developer.

È possibile registrare le funzioni definite dall'utente nell'API di DocumentDB e farvi riferimento come parte di una query SQL, estendendo così la grammatica in modo da supportare la logica dell'applicazione personalizzata.User Defined Functions (UDFs) can be registered with the DocumentDB API and referenced as part of a SQL query, thereby extending the grammar to support custom application logic. Queste funzioni UDF sono scritte come programmi JavaScript e sono eseguite nel database.These UDFs are written as JavaScript programs and executed within the database.

Per gli sviluppatori .NET, l'API di DocumentDB .NET SDK offre anche un provider di query LINQ.For .NET developers, the DocumentDB API .NET SDK also offers a LINQ query provider.

Transazioni ed esecuzione di JavaScriptTransactions and JavaScript execution

L'API di DocumentDB permette di scrivere logica dell'applicazione sotto forma di programmi con nome, scritti interamente in JavaScript.The DocumentDB API allows you to write application logic as named programs written entirely in JavaScript. Questi programmi sono registrati per una raccolta e possono eseguire di operazioni di database nei documenti all'interno di una raccolta specifica.These programs are registered for a collection and can issue database operations on the documents within a given collection. Il codice JavaScript può essere registrato per l'esecuzione come trigger, stored procedure o funzione UDF.JavaScript can be registered for execution as a trigger, stored procedure or user defined function. I trigger e le stored procedure possono creare, leggere, aggiornare ed eliminare documenti, mentre le funzioni UDF sono eseguite come parte della logica di esecuzione delle query, senza accesso in scrittura alla raccolta.Triggers and stored procedures can create, read, update, and delete documents whereas user defined functions execute as part of the query execution logic without write access to the collection.

L'esecuzione di JavaScript in Cosmos DB è modellata sui concetti supportati dai sistemi di database relazionali, in cui JavaScript rappresenta un sostituto attuale di Transact-SQL.JavaScript execution within the Cosmos DB is modeled after the concepts supported by relational database systems, with JavaScript as a modern replacement for Transact-SQL. Tutta la logica JavaScript è eseguita in una transazione di ambiente ACID con isolamento dello snapshot.All JavaScript logic is executed within an ambient ACID transaction with snapshot isolation. Se JavaScript genera un'eccezione durante l'esecuzione, l'intera transazione sarà interrotta.During the course of its execution, if the JavaScript throws an exception, then the entire transaction is aborted.

Disponibilità di corsi online su Azure Cosmos DBAre there any online courses on Azure Cosmos DB?

È disponibile un corso della Microsoft Virtual Academy su Azure DocumentDB.Yes, there's a Microsoft Virtual Academy course on Azure DocumentDB.

Passaggi successiviNext steps

Se si ha già un account di Azure,Already have an Azure account? è possibile iniziare a usare Azure Cosmos DB seguendo le guide introduttive, che illustrano come creare un account e iniziare a usare Cosmos DB.Then you can get started with Azure Cosmos DB by following our quick starts, which will walk you through creating an account and getting started with Cosmos DB.