Modello di risorsa gerarchico e concetti di base relativi ad Azure Cosmos DBAzure Cosmos DB hierarchical resource model and core concepts

Le entità del database gestite da Azure Cosmos DB vengono chiamate risorse.The database entities that Azure Cosmos DB manages are referred to as resources. Ogni risorsa viene identificata in modo univoco da un URI logico.Each resource is uniquely identified by a logical URI. È possibile interagire con le risorse usando verbi HTTP, intestazioni di richiesta/risposta e codici di stato standard.You can interact with the resources using standard HTTP verbs, request/response headers and status codes.

Dopo aver letto questo articolo, si riuscirà a rispondere alle domande seguenti:By reading this article, you'll be able to answer the following questions:

  • Cos'è il modello di risorsa di Azure Cosmos DB?What is Azure Cosmos DB's resource model?
  • Quali sono le risorse definite dal sistema e quali le risorse definite dall'utente?What are system defined resources as opposed to user defined resources?
  • Come si indirizza una risorsa?How do I address a resource?
  • Come si usano le raccolte?How do I work with collections?
  • Come si usano le stored procedure, i trigger e le funzioni definite dall'utenteHow do I work with stored procedures, triggers and User Defined Functions (UDFs)?

Modello di risorse gerarchicoHierarchical resource model

Come illustrato nel diagramma seguente, il modello di risorsa gerarchico di Azure Cosmos DB è costituito da set di risorse in un account di database, ognuna indirizzabile tramite un URI logico e stabile.As the following diagram illustrates, the Azure Cosmos DB hierarchical resource model consists of sets of resources under a database account, each addressable via a logical and stable URI. Un set di risorse viene definito feed in questo articolo.A set of resources will be referred to as a feed in this article.

Nota

Azure Cosmos DB offre un protocollo TCP molto efficiente, con un modello di comunicazione di tipo RESTful, disponibile tramite l'API .NET client DocumentDB.Azure Cosmos DB offers a highly efficient TCP protocol which is also RESTful in its communication model, available through the DocumentDB .NET client API.

Modello di risorsa gerarchico di Azure Cosmos DBAzure Cosmos DB hierarchical resource model
Modello di risorse gerarchicoHierarchical resource model

Per iniziare a usare le risorse è necessario creare un account di database usando la sottoscrizione di Azure.To start working with resources, you must create a database account using your Azure subscription. Un account di database può essere costituito da un set di database, ognuno contenente più raccolte. Ogni raccolta include a propria volta stored procedure, trigger, funzioni definite dall'utente, documenti e allegati correlati.A database account can consist of a set of databases, each containing multiple collections, each of which in turn contain stored procedures, triggers, UDFs, documents and related attachments. Un database include anche gli utenti associati, ognuno dei quali possiede un set di autorizzazioni per accedere a raccolte, stored procedure, trigger, UDF, documenti o allegati.A database also has associated users, each with a set of permissions to access collections, stored procedures, triggers, UDFs, documents or attachments. Mentre i database, gli utenti, le autorizzazioni e le raccolte sono ricorse definite dal sistema con schemi noti, i documenti 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 and attachments contain arbitrary, user defined JSON content.

RisorsaResource DescrizioneDescription
Account di databaseDatabase account Un account di database è associato a un set di database e a una quantità fissa di archivio BLOB per gli allegati.A database account is associated with a set of databases and a fixed amount of blob storage for attachments. È possibile creare uno o più account di database usando la sottoscrizione di Azure.You can create one or more database accounts using your Azure subscription. Per altre informazioni, visitare la pagina dei prezzi.For more information, visit our pricing page.
DatabaseDatabase Un database è un contenitore logico di archiviazione documenti partizionato nelle raccolte.A database is a logical container of document storage partitioned across collections. Un database è anche un contenitore degli utentiIt is also a users container.
UtenteUser Spazio dei nomi logico per la definizione dell'ambito delle autorizzazioni.The logical namespace for scoping permissions.
AutorizzazionePermission Token di autorizzazione associato a un utente per l'accesso a una risorsa specifica.An authorization token associated with a user for access to a specific resource.
RaccoltaCollection Una raccolta è un contenitore di documenti JSON e di logica dell'applicazione JavaScript associata.A collection is a container of JSON documents and the associated JavaScript application logic. Una raccolta è un'entità fatturabile, in cui il costo è determinato dal livello di prestazioni associato alla raccolta.A collection is a billable entity, where the cost is determined by the performance level associated with the collection. Le raccolte possono estendersi su più partizioni o server e possono essere ridimensionate per gestire volumi praticamente illimitati di archiviazione o di velocità effettiva.Collections can span one or more partitions/servers and can scale to handle practically unlimited volumes of storage or throughput.
Stored ProcedureStored Procedure Logica dell'applicazione scritta in JavaScript, registrata con una raccolta ed eseguita a livello di transazione all'interno del motore di database.Application logic written in JavaScript which is registered with a collection and transactionally executed within the database engine.
TriggerTrigger Logica dell'applicazione scritta in JavaScript ed eseguita prima o dopo un'operazione di inserimento, sostituzione o eliminazione.Application logic written in JavaScript executed before or after either an insert, replace or delete operation.
UDFUDF Logica dell'applicazione scritta in JavaScript.Application logic written in JavaScript. Le funzioni definite dall'utente consentono di modellare un operatore query personalizzato e quindi di estendere il linguaggio di query di base dell'API di DocumentDB.UDFs enable you to model a custom query operator and thereby extend the core DocumentDB API query language.
DocumentoDocument Contenuto JSON definito dall'utente (arbitrario).User defined (arbitrary) JSON content. Per impostazione predefinita, non è necessario definire alcuno schema, né fornire indici secondari per tutti i documenti aggiunti a una raccolta.By default, no schema needs to be defined nor do secondary indices need to be provided for all the documents added to a collection.
AttachmentAttachment Un allegato è un documento speciale contenente riferimenti e metadati associati per BLOB/file multimediali esterni.An attachment is a special document containing references and associated metadata for external blob/media. Lo sviluppatore può scegliere se gestire il BLOB con Cosmos DB o archiviarlo con un provider di servizi BLOB esterno, ad esempio OneDrive, Dropbox e così via.The developer can choose to have the blob managed by Cosmos DB or store it with an external blob service provider such as OneDrive, Dropbox, etc.

Risorse definite dal sistema e risorse definite dall'utenteSystem vs. user defined resources

Tutte le risorse quali account di database, database, raccolte, utenti, autorizzazioni, stored procedure, trigger e funzioni UDF hanno uno schema fisso e sono definite risorse di sistema.Resources such as database accounts, databases, collections, users, permissions, stored procedures, triggers, and UDFs - all have a fixed schema and are called system resources. Per le risorse quali documenti e allegati, invece, non sono previste restrizioni a livello di schema. Si tratta di risorse definite dall'utente.In contrast, resources such as documents and attachments have no restrictions on the schema and are examples of user defined resources. In Cosmos DB le risorse definite sia dal sistema che dall'utente vengono rappresentate e gestite come risorse JSON conformi allo standard.In Cosmos DB, both system and user defined resources are represented and managed as standard-compliant JSON. Tutte le risorse, di sistema o definite dall'utente, presentano le proprietà comuni indicate di seguito.All resources, system or user defined, have the following common properties.

Nota

Si noti che, nell'implementazione JSON, tutte le proprietà generate dal sistema in una risorsa hanno come prefisso un carattere di sottolineatura ().Note that all system generated properties in a resource are prefixed with an underscore () in their JSON representation.

ProprietàProperty

Impostabile dall'utente o generata dal sistemaUser settable or system generated?

ScopoPurpose

_rid_rid

Generata dal sistemaSystem generated

Identificatore gerarchico della risorsa, univoco e generato dal sistemaSystem generated, unique and hierarchical identifier of the resource

_etag_etag

Generata dal sistemaSystem generated

etag della risorsa richiesta per il controllo della concorrenza ottimisticaetag of the resource required for optimistic concurrency control

_ts_ts

Generata dal sistemaSystem generated

Ultimo timestamp aggiornato della risorsaLast updated timestamp of the resource

_self_self

Generata dal sistemaSystem generated

URI univoco indirizzabile della risorsaUnique addressable URI of the resource

idid

È possibile usare ilEither

Nome univoco della risorsa (con lo stesso valore della chiave di partizione) definito dall'utente.User defined unique name of the resource (with the same partition key value). Se l'utente non specifica un ID, quest'ultimo verrà generato dal sistema.If the user does not specify an id, an id will be system generated

Rappresentazione delle risorseWire representation of resources

Cosmos DB non impone estensioni proprietarie o codifiche speciali allo standard JSON e funziona con i documenti JSON conformi a tale standard.Cosmos DB does not mandate any proprietary extensions to the JSON standard or special encodings; it works with standard compliant JSON documents.

Indirizzamento di una risorsaAddressing a resource

Tutte le risorse sono indirizzabili mediante URI.All resources are URI addressable. Il valore della proprietà _self di una risorsa rappresenta l'URI relativo della risorsa.The value of the _self property of a resource represents the relative URI of the resource. Il formato dell'URI è dato dai segmenti del percorso /<feed>/{_rid}:The format of the URI consists of the /<feed>/{_rid} path segments:

Valore di _selfValue of the _self DescrizioneDescription
/dbs/dbs Feed dei database in un account di databaseFeed of databases under a database account
/dbs/{dbName}/dbs/{dbName} Database con id corrispondente al valore {dbName}Database with an id matching the value {dbName}
/dbs/{dbName}/colls//dbs/{dbName}/colls/ Feed delle raccolte in un databaseFeed of collections under a database
/dbs/{dbName}/colls/{collName}/dbs/{dbName}/colls/{collName} Raccolta con un id corrispondente al valore {collName}Collection with an id matching the value {collName}
/dbs/{dbName}/colls/{collName}/docs/dbs/{dbName}/colls/{collName}/docs Feed dei documenti in una raccoltaFeed of documents under a collection
/dbs/{dbName}/colls/{collName}/docs/{docId}/dbs/{dbName}/colls/{collName}/docs/{docId} Documento con id corrispondente al valore {doc}Document with an id matching the value {doc}
/dbs/{dbName}/users//dbs/{dbName}/users/ Feed degli utenti in un databaseFeed of users under a database
/dbs/{dbName}/users/{userId}/dbs/{dbName}/users/{userId} Utente con id corrispondente al valore {user}User with an id matching the value {user}
/dbs/{dbName}/users/{userId}/permissions/dbs/{dbName}/users/{userId}/permissions Feed delle autorizzazioni in un utenteFeed of permissions under a user
/dbs/{dbName}/users/{userId}/permissions/{permissionId}/dbs/{dbName}/users/{userId}/permissions/{permissionId} Autorizzazione con id corrispondente al valore {permission}Permission with an id matching the value {permission}

Ogni risorsa dispone di un nome utente univoco esposto mediante la proprietà ID.Each resource has a unique user defined name exposed via the id property. Nota: se l'utente non specifica un ID per i documenti, gli SDK supportati genereranno automaticamente un ID univoco per ogni documento.Note: for documents, if the user does not specify an id, our supported SDKs will automatically generate a unique id for the document. l'ID è una stringa definita dall'utente contenente fino a 256 caratteri, univoca all'interno del contesto di una risorsa padre specifica.The id is a user defined string, of up to 256 characters that is unique within the context of a specific parent resource.

Ogni risorsa ha anche un identificatore gerarchico generato dal sistema (chiamato anche RID), disponibile tramite la proprietà _rid.Each resource also has a system generated hierarchical resource identifier (also referred to as an RID), which is available via the _rid property. Il RID codifica l'intera gerarchia di una determinata risorsa ed è una rappresentazione interna utile da usare per imporre l'integrità referenziale secondo un metodo distribuito.The RID encodes the entire hierarchy of a given resource and it is a convenient internal representation used to enforce referential integrity in a distributed manner. Il RID è univoco all'interno di un account di database e viene usato internamente da Cosmos DB per un routing efficiente senza necessità di eseguire ricerche su più partizioni.The RID is unique within a database account and it is internally used by Cosmos DB for efficient routing without requiring cross partition lookups. I valori delle proprietà _self e _rid sono entrambi rappresentazioni alternate e canoniche di una risorsa.The values of the _self and the _rid properties are both alternate and canonical representations of a resource.

Le API REST supportano l'indirizzamento delle risorse e il routing delle richieste tramite l'id e le proprietà _rid.The REST APIs support addressing of resources and routing of requests by both the id and the _rid properties.

Account di databaseDatabase accounts

È possibile effettuare il provisioning di uno o più account di database di Cosmos DB usando la sottoscrizione di Azure.You can provision one or more Cosmos DB database accounts using your Azure subscription.

È possibile creare e gestire account di database di Cosmos DB tramite il portale di Azure all'indirizzo http://portal.azure.com/.You can create and manage Cosmos DB database accounts via the Azure Portal at http://portal.azure.com/. Per la creazione e la gestione di un account di database è necessario l'accesso amministrativo e queste operazioni possono essere eseguite solo con una sottoscrizione di Azure.Creating and managing a database account requires administrative access and can only be performed under your Azure subscription.

Proprietà degli account di databaseDatabase account properties

Come parte del provisioning e della gestione di un account di database, è possibile configurare e leggere le proprietà seguenti:As part of provisioning and managing a database account you can configure and read the following properties:

Nome proprietàProperty Name

DescrizioneDescription

Criterio di coerenzaConsistency Policy

Impostare questa proprietà per configurare il livello di coerenza predefinito per tutte le raccolte nell'account di database.Set this property to configure the default consistency level for all the collections under your database account. È possibile eseguire l'override del livello di coerenza per singole richieste usando l'intestazione di richiesta [x-ms-consistency-level].You can override the consistency level on a per request basis using the [x-ms-consistency-level] request header.

Si noti che questa proprietà è applicabile solo alle risorse definite dall'utente.Note that this property only applies to the user defined resources. Tutte le risorse definite dal sistema sono configurate per il supporto di letture/query con coerenza assoluta.All system defined resources are configured to support reads/queries with strong consistency.

Chiavi di autorizzazioneAuthorization Keys

Si tratta delle chiavi master e readonly primaria e secondaria che consentono accesso amministrativo a tutte le risorse nell'account di database.These are the primary and secondary master and readonly keys that provide administrative access to all of the resources under the database account.

Si noti che oltre al provisioning, alla configurazione e alla gestione dell'account di database dal portale di Azure, è anche possibile creare e gestire account di database Cosmos DB a livello di codice usando le API REST di Azure Cosmos DB e gli SDK client.Note that in addition to provisioning, configuring and managing your database account from the Azure Portal, you can also programmatically create and manage Cosmos DB database accounts by using the Azure Cosmos DB REST APIs as well as client SDKs.

DatabaseDatabases

Un database di Cosmos DB è un contenitore logico di uno o più utenti e raccolte, come illustrato nel diagramma seguente.A Cosmos DB database is a logical container of one or more collections and users, as shown in the following diagram. È possibile creare un numero qualsiasi di database in un account di database Cosmos DB, a condizione di rispettare i limiti di offerta.You can create any number of databases under a Cosmos DB database account subject to offer limits.

Modello gerarchico di account di database e raccolteDatabase account and collections hierarchical model
Un database è un contenitore logico di utenti e raccolteA Database is a logical container of users and collections

Un database può contenere risorse di archiviazione di documenti praticamente illimitate partizionate all'interno delle raccolte.A database can contain virtually unlimited document storage partitioned within collections.

Scalabilità elastica di un database di Azure Cosmos DBElastic scale of a Azure Cosmos DB database

Un database di Cosmos DB è elastico per impostazione predefinita e può includere da pochi GB a diversi petabyte di spazio di archiviazione per i documenti basato su SSD e velocità effettiva con provisioning.A Cosmos DB database is elastic by default – ranging from a few GB to petabytes of SSD backed document storage and provisioned throughput.

A differenza di un database RDBMS tradizionale, l'ambito di un database in Cosmos DB non è limitato a un singolo computer.Unlike a database in traditional RDBMS, a database in Cosmos DB is not scoped to a single machine. Con Cosmos DB, in caso di crescita delle esigenze di scalabilità dell'applicazione, sarà possibile creare più raccolte, più database o entrambi.With Cosmos DB, as your application’s scale needs to grow, you can create more collections, databases, or both. Molte applicazioni prodotte direttamente da Microsoft usano Azure Cosmos DB su scala consumer, creando database di Azure Cosmos DB molto grandi, ognuno dei quali include migliaia di raccolte con terabyte di spazio di archiviazione per i documenti.Indeed, various first party applications within Microsoft have been using Azure Cosmos DB at a consumer scale by creating extremely large Azure Cosmos DB databases each containing thousands of collections with terabytes of document storage. È possibile aumentare o ridurre le dimensioni di un database aggiungendo o rimuovendo raccolte per soddisfare i requisiti di scalabilità dell'applicazione.You can grow or shrink a database by adding or removing collections to meet your application’s scale requirements.

Il numero di raccolte che è possibile creare in un database dipende dall'offerta.You can create any number of collections within a database subject to the offer. Ogni raccolta dispone di risorse di archiviazione basate su SSD e velocità effettiva di cui è stato eseguito il provisioning in base al livello di prestazioni selezionato.Each collection has SSD backed storage and throughput provisioned for you depending on the selected performance tier.

Un database di Azure Cosmos DB è anche un contenitore di utenti.An Azure Cosmos DB database is also a container of users. Un utente, a sua volta, è uno spazio dei nomi logico per un set di autorizzazioni che fornisce autorizzazioni specifiche e accesso a raccolte, documenti e allegati.A user, in-turn, is a logical namespace for a set of permissions that provides fine-grained authorization and access to collections, documents and attachments.

Come per le altre risorse nel modello di risorsa di Azure Cosmos DB, i database possono essere creati, sostituiti, eliminati, letti o enumerati facilmente usando le API REST o uno degli SDK client.As with other resources in the Azure Cosmos DB resource model, databases can be created, replaced, deleted, read or enumerated easily using either the REST APIs or any of the client SDKs. Azure Cosmos DB assicura una coerenza assoluta per la lettura o l'esecuzione di query sui metadati di una risorsa del database.Azure Cosmos DB guarantees strong consistency for reading or querying the metadata of a database resource. Se si elimina un database, non sarà automaticamente più possibile accedere alle raccolte o agli utenti inclusi nel database.Deleting a database automatically ensures that you cannot access any of the collections or users contained within it.

RaccolteCollections

Una raccolta di Cosmos DB è un contenitore per i documenti JSON.A Cosmos DB collection is a container for your JSON documents.

Archiviazione flessibile di documenti basata su unità SSDElastic SSD backed document storage

Una raccolta è intrinsecamente flessibile, poiché le dimensioni della raccolta aumentano o si riducono in seguito all'aggiunta o alla rimozione di documenti.A collection is intrinsically elastic - it automatically grows and shrinks as you add or remove documents. Le raccolte sono risorse logiche e possono comprendere una o più partizioni fisiche o server.Collections are logical resources and can span one or more physical partitions or servers. Il numero di partizioni in una raccolta è determinato da Cosmos DB in base allo spazio di archiviazione e alla velocità effettiva con provisioning della raccolta.The number of partitions within a collection is determined by Cosmos DB based on the storage size and the provisioned throughput of your collection. Ogni partizione in Cosmos DB ha una quantità fissa di archiviazione supportata da unità SSD associata e viene replicata per la disponibilità elevata.Every partition in Cosmos DB has a fixed amount of SSD-backed storage associated with it, and is replicated for high availability. Le partizioni vengono completamente gestite da Azure Cosmos DB e non è necessario scrivere codice complesso o gestire le partizioni.Partition management is fully managed by Azure Cosmos DB, and you do not have to write complex code or manage your partitions. Le raccolte di Cosmos DB sono praticamente illimitate in termini di spazio di archiviazione e velocità effettiva.Cosmos DB collections are practically unlimited in terms of storage and throughput.

Indicizzazione automatica delle raccolteAutomatic indexing of collections

Azure Cosmos DB è un sistema di database realmente privo di schema.Azure Cosmos DB is a true schema-free database system. Non si presuppone o richiede alcuno schema per i documenti JSON.It does not assume or require any schema for the JSON documents. Azure Cosmos DB indicizza automaticamente i documenti aggiunti a una raccolta e li rende disponibili per l'esecuzione di query.As you add documents to a collection, Azure Cosmos DB automatically indexes them and they are available for you to query. L'indicizzazione automatica di documenti senza la necessità di schemi o di indici secondari è una funzionalità chiave di Azure Cosmos DB ed è resa possibile da tecniche di manutenzione dell'indice ottimizzate per la scrittura, prive di blocco e strutturate in log.Automatic indexing of documents without requiring schema or secondary indexes is a key capability of Azure Cosmos DB and is enabled by write-optimized, lock-free and log-structured index maintenance techniques. Azure Cosmos DB supporta un volume elevato di scritture estremamente veloci, gestendo al tempo stesso query coerenti.Azure Cosmos DB supports sustained volume of extremely fast writes while still serving consistent queries. L'archiviazione documenti e l'archiviazione dell'indice sono usate per calcolare le risorse di archiviazione usate da ogni raccolta.Both document and index storage are used to calculate the storage consumed by each collection. È possibile controllare i compromessi tra archiviazione e prestazioni associati all'indicizzazione tramite la configurazione di un criterio di indicizzazione per una raccolta.You can control the storage and performance trade-offs associated with indexing by configuring the indexing policy for a collection.

Configurazione dei criteri di indicizzazione di una raccoltaConfiguring the indexing policy of a collection

Il criterio di indicizzazione di ogni raccolta rende possibili i compromessi tra prestazioni e archiviazione associati all'indicizzazione.The indexing policy of each collection allows you to make performance and storage trade-offs associated with indexing. Le opzioni seguenti sono disponibili come parte della configurazione dell'indicizzazione:The following options are available to you as part of indexing configuration:

  • Possibilità di scegliere se la raccolta indicizza automaticamente o meno tutti i documenti.Choose whether the collection automatically indexes all of the documents or not. Per impostazione predefinita, saranno indicizzati automaticamente tutti i documenti.By default, all documents are automatically indexed. È possibile scegliere di disattivare l'indicizzazione automatica e aggiungere in modo selettivo solo documenti specifici all'indice.You can choose to turn off automatic indexing and selectively add only specific documents to the index. In alternativa, è possibile scegliere di escludere in modo selettivo solo documenti specifici.Conversely, you can selectively choose to exclude only specific documents. Per ottenere questo risultato, impostare la proprietà automatica su true o false nella proprietà indexingPolicy di una raccolta e usare l'intestazione di richiesta [x-ms-indexingdirective] durante l'inserimento, la sostituzione o l'eliminazione di un documento.You can achieve this by setting the automatic property to be true or false on the indexingPolicy of a collection and using the [x-ms-indexingdirective] request header while inserting, replacing or deleting a document.
  • Possibilità di scegliere se includere o escludere percorsi o modelli specifici nei documenti dall'indice.Choose whether to include or exclude specific paths or patterns in your documents from the index. Per ottenere questo risultato, impostare rispettivamente includedPaths e excludedPaths in indexingPolicy di una raccolta.You can achieve this by setting includedPaths and excludedPaths on the indexingPolicy of a collection respectively. È anche possibile configurare i compromessi relativi ad archiviazione e prestazioni per query di intervallo e hash per modelli di percorso specifici.You can also configure the storage and performance trade-offs for range and hash queries for specific path patterns.
  • Possibilità di scegliere tra aggiornamenti sincroni (coerenti) e asincroni (differiti) dell'indice.Choose between synchronous (consistent) and asynchronous (lazy) index updates. Per impostazione predefinita, l'indice è aggiornato in modo sincrono a ogni inserimento, sostituzione o eliminazione di un documento nella raccolta.By default, the index is updated synchronously on each insert, replace or delete of a document to the collection. Ciò permette alle query di rispettare lo stesso livello di coerenza delle letture di documenti.This enables the queries to honor the same consistency level as that of the document reads. Anche se Azure Cosmos DB è ottimizzato per la scrittura e supporta volumi elevati di scritture di documenti, oltre a consentire la manutenzione sincrona dell'indice e la gestione di query coerenti, è possibile configurare determinate raccolte per l'aggiornamento differito dell'indice.While Azure Cosmos DB is write optimized and supports sustained volumes of document writes along with synchronous index maintenance and serving consistent queries, you can configure certain collections to update their index lazily. L'indicizzazione differita migliora ulteriormente le prestazioni di scrittura ed è ideale per scenari di inserimento in blocco per raccolte principalmente a uso intensivo di lettura.Lazy indexing boosts the write performance further and is ideal for bulk ingestion scenarios for primarily read-heavy collections.

Il criterio di indicizzazione può essere modificato tramite l'esecuzione di un'operazione PUT sulla raccolta.The indexing policy can be changed by executing a PUT on the collection. Può essere ottenuto tramite l'SDK client, il portale di Azure o le API REST.This can be achieved either through the client SDK, the Azure Portal or the REST APIs.

Esecuzione di query su una raccoltaQuerying a collection

I documenti in una raccolta possono avere schemi arbitrari ed è possibile eseguire query sui documenti in una raccolta senza fornire anticipatamente alcuno schema o alcun indice secondario.The documents within a collection can have arbitrary schemas and you can query documents within a collection without providing any schema or secondary indices upfront. È possibile eseguire query sulla raccolta seguendo la procedura descritta in API di DocumentDB per Azure Cosmos DB: riferimento per la sintassi SQL, che offre avanzati operatori gerarchici, relazionali e spaziali ed estendibilità tramite funzioni definite dall'utente basate su JavaScript.You can query the collection using the Azure Cosmos DB DocumentDB API: SQL syntax reference, which provides rich hierarchical, relational, and spatial operators and extensibility via JavaScript-based UDFs. La grammatica JSON permette la modellazione di documenti JSON come alberi con etichette come nodi dell'albero.JSON grammar allows for modeling JSON documents as trees with labels as the tree nodes. Viene usata dalle tecniche di indicizzazione automatica dell'API di DocumentDB e dal dialetto SQL dell'API di DocumentDB.This is exploited both by DocumentDB API’s automatic indexing techniques as well as DocumentDB API's SQL dialect. Il linguaggio di query dell'API di DocumentDB è caratterizzato da tre aspetti principali:The DocumetDB API query language consists of three main aspects:

  1. Un set ridotto di operazioni di query mappate in modo naturale alla struttura ad albero, che include query e proiezioni gerarchiche.A small set of query operations that map naturally to the tree structure including hierarchical queries and projections.
  2. Un sottoinsieme di operazioni relazionali, incluse la composizione, l'applicazione di filtri, le proiezioni, le aggregazioni e i self join.A subset of relational operations including composition, filter, projections, aggregates and self joins.
  3. Funzioni definite dall'utente pure basate su JavaScript in grado di funzionare con (1) e (2).Pure JavaScript based UDFs that work with (1) and (2).

Il modello di query di Azure Cosmos DB cerca di raggiungere un equilibrio tra funzionalità, efficienza e semplicità.The Azure Cosmos DB query model attempts to strike a balance between functionality, efficiency and simplicity. Il motore di database di Azure Cosmos DB compila ed esegue in modo nativo le istruzioni di query SQL.The Azure Cosmos DB database engine natively compiles and executes the SQL query statements. È possibile eseguire query su una raccolta usando le API REST o uno degli SDK client.You can query a collection using the REST APIs or any of the client SDKs. In .NET SDK è disponibile un provider LINQ.The .NET SDK comes with a LINQ provider.

Suggerimento

È possibile provare l'API di DocumentDB ed eseguire query SQL con il set di dati in Query Playground.You can try out the DocumentDB API and run SQL queries against our dataset in the Query Playground.

Transazioni in più documentiMulti-document transactions

Le transazioni di database offrono un modello di programmazione sicuro e prevedibile per la gestione delle modifiche simultanee ai dati.Database transactions provide a safe and predictable programming model for dealing with concurrent changes to the data. In RDBMS la logica di business è tradizionalmente scritta tramite la scrittura di stored procedure e/o trigger ed è inviata al server database per l'esecuzione transazionale.In RDBMS, the traditional way to write business logic is to write stored-procedures and/or triggers and ship it to the database server for transactional execution. In RDBMS il programmatore di applicazioni deve gestire due linguaggi di programmazione diversi:In RDBMS, the application programmer is required to deal with two disparate programming languages:

  • Linguaggio di programmazione delle applicazioni (non transazionale), ad esempio JavaScript, Python, C#, Java e così via.The (non-transactional) application programming language (e.g. JavaScript, Python, C#, Java, etc.)
  • T-SQL, ovvero il linguaggio di programmazione transazionale eseguito in modo nativo dal database.T-SQL, the transactional programming language which is natively executed by the database

In virtù dell'integrazione completa di JavaScript e JSON direttamente nel motore di database, Azure Cosmos DB offre un modello di programmazione intuitivo per eseguire la logica dell'applicazione basata su JavaScript direttamente nelle raccolte in termini di stored procedure e trigger.By virtue of its deep commitment to JavaScript and JSON directly within the database engine, Azure Cosmos DB provides an intuitive programming model for executing JavaScript based application logic directly on the collections in terms of stored procedures and triggers. Questo offre entrambi i vantaggi seguenti:This allows for both of the following:

  • Implementazione efficiente del controllo della concorrenza, ripristino e indicizzazione automatica dei grafici di oggetti JSON direttamente nel motore di database.Efficient implementation of concurrency control, recovery, automatic indexing of the JSON object graphs directly in the database engine
  • Espressione naturale di flusso di controllo, definizione dell'ambito delle variabili e assegnazione e integrazione delle primitive di gestione delle eccezioni con transazioni di database direttamente sotto forma di linguaggio di programmazione JavaScript.Naturally expressing control flow, variable scoping, assignment and integration of exception handling primitives with database transactions directly in terms of the JavaScript programming language

La logica JavaScript registrata a livello di raccolta può quindi rilasciare operazioni sui documenti della raccolta specifica.The JavaScript logic registered at a collection level can then issue database operations on the documents of the given collection. Azure Cosmos DB esegue implicitamente il wrapping di stored procedure e trigger basati su JavaScript in transazioni di ambiente ACID con isolamento degli snapshot nei documenti in una raccolta.Azure Cosmos DB implicitly wraps the JavaScript based stored procedures and triggers within an ambient ACID transactions with snapshot isolation across documents within a collection. 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. Il modello di programmazione risultante è molto semplice ma efficace.The resulting programming model is very simple yet powerful. Gli sviluppatori JavaScript ottengono un modello di programmazione "durevole", usando al tempo stesso i costrutti dei propri linguaggi preferiti e i primitivi di librerie.JavaScript developers get a “durable” programming model while still using their familiar language constructs and library primitives.

La possibilità di eseguire JavaScript direttamente nel motore di database nello stesso spazio di indirizzi del pool di buffer permette l'esecuzione efficiente e transazionale di operazioni di database nei documenti di una raccolta.The ability to execute JavaScript directly within the database engine in the same address space as the buffer pool enables performant and transactional execution of database operations against the documents of a collection. Poiché il motore di database di Cosmos DB adotta completamente JSON e JavaScript, elimina eventuali mancate corrispondenze di impedenza tra i sistemi di tipi dell'applicazione e del database.Furthermore, Cosmos DB database engine makes a deep commitment to the JSON and JavaScript eliminates any impedance mismatch between the type systems of application and the database.

Dopo aver creato una raccolta, è possibile registrare stored procedure, trigger e UDF con la raccolta usando le API REST o uno degli SDK client.After creating a collection, you can register stored procedures, triggers and UDFs with a collection using the REST APIs or any of the client SDKs. Dopo la registrazione, sarà possibile farvi riferimento ed eseguire questi elementi.After registration, you can reference and execute them. La stored procedure seguente, scritta interamente in JavaScript, accetta due argomenti (titolo del libro e nome dell'autore) e crea un nuovo documento, esegue query per un documento e quindi lo aggiorna. Tutte queste operazioni sono eseguite tramite una transazione ACID implicita.Consider the following stored procedure written entirely in JavaScript, the code below takes two arguments (book name and author name) and creates a new document, queries for a document and then updates it – all within an implicit ACID transaction. Se in un punto qualsiasi dell'esecuzione viene generata un'eccezione JavaScript, l'intera transazione viene interrotta.At any point during the execution, if a JavaScript exception is thrown, the entire transaction aborts.

function businessLogic(name, author) {
    var context = getContext();
    var collectionManager = context.getCollection();        
    var collectionLink = collectionManager.getSelfLink()

    // create a new document.
    collectionManager.createDocument(collectionLink,
        {id: name, author: author},
        function(err, documentCreated) {
            if(err) throw new Error(err.message);

            // filter documents by author
            var filterQuery = "SELECT * from root r WHERE r.author = 'George R.'";
            collectionManager.queryDocuments(collectionLink,
                filterQuery,
                function(err, matchingDocuments) {
                    if(err) throw new Error(err.message);

                    context.getResponse().setBody(matchingDocuments.length);

                    // Replace the author name for all documents that satisfied the query.
                    for (var i = 0; i < matchingDocuments.length; i++) {
                        matchingDocuments[i].author = "George R. R. Martin";
                        // we don’t need to execute a callback because they are in parallel
                        collectionManager.replaceDocument(matchingDocuments[i]._self,
                            matchingDocuments[i]);   
                    }
                })
        })
};

Il client può "inviare" la logica JavaScript precedente al database per l'esecuzione transazionale tramite POST HTTP.The client can “ship” the above JavaScript logic to the database for transactional execution via HTTP POST. Per altre informazioni sull'uso di metodi HTTP, vedere RESTful interactions with Azure Cosmos DB resources (Interazioni RESTful con risorse di Azure Cosmos DB).For more information about using HTTP methods, see RESTful interactions with Azure Cosmos DB resources.

client.createStoredProcedureAsync(collection._self, {id: "CRUDProc", body: businessLogic})
   .then(function(createdStoredProcedure) {
        return client.executeStoredProcedureAsync(createdStoredProcedure.resource._self,
            "NoSQL Distilled",
            "Martin Fowler");
    })
    .then(function(result) {
        console.log(result);
    },
    function(error) {
        console.log(error);
    });

Poiché il database comprende in modo nativo JSON e JavaScript, non si verificano mancate corrispondenze tra sistemi di tipi né sono necessari "mapping OR" o generazione di codice.Notice that because the database natively understands JSON and JavaScript, there is no type system mismatch, no “OR mapping” or code generation magic required.

Le stored procedure e i trigger interagiscono con una raccolta e con i documenti in una raccolta tramite un modello a oggetti ben definito, che espone il contesto corrente della raccolta.Stored procedures and triggers interact with a collection and the documents in a collection through a well-defined object model, which exposes the current collection context.

Le raccolte nell'API di DocumentDB possono essere create, eliminate, lette o enumerate facilmente usando le API REST o uno degli SDK client.Collections in the DocumentDB API can be created, deleted, read or enumerated easily using either the REST APIs or any of the client SDKs. L'API di DocumentDB offre sempre una coerenza assoluta per la lettura o l'esecuzione di query sui metadati di una raccolta.The DocumentDB API always provides strong consistency for reading or querying the metadata of a collection. Se si elimina una raccolta, non sarà automaticamente più possibile accedere a documenti, allegati, stored procedure, trigger e funzioni UDF inclusi nella raccolta stessa.Deleting a collection automatically ensures that you cannot access any of the documents, attachments, stored procedures, triggers, and UDFs contained within it.

Stored procedure, trigger e funzioni definite dall'utente (UDF)Stored procedures, triggers and User Defined Functions (UDF)

Come illustrato nella sezione precedente, è possibile scrivere logica dell'applicazione per l'esecuzione direttamente in una transazione nel motore del database.As described in the previous section, you can write application logic to run directly within a transaction inside of the database engine. La logica dell'applicazione può essere scritta interamente in JavaScript e può essere modellata come stored procedure, trigger o funzione definita dall'utente (UDF, User-Defined Function).The application logic can be written entirely in JavaScript and can be modeled as a stored procedure, trigger or a UDF. Il codice JavaScript in una stored procedure o un trigger può inserire, sostituire, eliminare, leggere o sottoporre a query documenti all'interno di una raccolta.The JavaScript code within a stored procedure or a trigger can insert, replace, delete, read or query documents within a collection. Il codice JavaScript all'interno di una funzione definita dall'utente, invece, non può inserire, sostituire o eliminare documenti.On the other hand, the JavaScript within a UDF cannot insert, replace, or delete documents. Le funzioni definite dall'utente enumerano i documenti di un set di risultati di query e producono un altro set di risultati.UDFs enumerate the documents of a query's result set and produce another result set. Per la multi-tenancy, Azure Cosmos DB applica una rigida governance delle risorse basata sulle prenotazioni.For multi-tenancy, Azure Cosmos DB enforces a strict reservation based resource governance. Ogni stored procedure, trigger o funzione UDF ottiene una quantità fissa di risorse del sistema operativo per l'esecuzione delle operazioni.Each stored procedure, trigger or a UDF gets a fixed quantum of operating system resources to do its work. Le stored procedure, i trigger o le funzioni UDF, inoltre, non possono collegarsi a librerie JavaScript esterne e saranno disattivati in caso di superamento dei rispettivi budget di risorse allocati.Furthermore, stored procedures, triggers or UDFs cannot link against external JavaScript libraries and are blacklisted if they exceed the resource budgets allocated to them. È possibile eseguire o annullare la registrazione di stored procedure, trigger o funzioni definite dall'utente con una raccolta usando le API REST.You can register, unregister stored procedures, triggers or UDFs with a collection by using the REST APIs. Durante la registrazione, una stored procedure, un trigger o una funzione UDF saranno precompilati e archiviati come codice byte, che sarà eseguito in seguito.Upon registration a stored procedure, trigger, or a UDF is pre-compiled and stored as byte code which gets executed later. La sezione seguente illustra come usare Azure Cosmos DB JavaScript SDK per la registrazione, l'esecuzione e l'annullamento della registrazione di una stored procedure, un trigger e una funzione definita dall'utente.The following section illustrate how you can use the Azure Cosmos DB JavaScript SDK to register, execute, and unregister a stored procedure, trigger, and a UDF. JavaScript SDK è un semplice wrapper per le API REST.The JavaScript SDK is a simple wrapper over the REST APIs.

Registrazione di una stored procedureRegistering a stored procedure

La registrazione di una stored procedure consiste nel creare una nuova risorsa stored procedure in una raccolta tramite un metodo HTTP POST.Registration of a stored procedure creates a new stored procedure resource on a collection via HTTP POST.

var storedProc = {
    id: "validateAndCreate",
    body: function (documentToCreate) {
        documentToCreate.id = documentToCreate.id.toUpperCase();

        var collectionManager = getContext().getCollection();
        collectionManager.createDocument(collectionManager.getSelfLink(),
            documentToCreate,
            function(err, documentCreated) {
                if(err) throw new Error('Error while creating document: ' + err.message;
                getContext().getResponse().setBody('success - created ' + 
                        documentCreated.name);
            });
    }
};

client.createStoredProcedureAsync(collection._self, storedProc)
    .then(function (createdStoredProcedure) {
        console.log("Successfully created stored procedure");
    }, function(error) {
        console.log("Error");
    });

Esecuzione di una stored procedureExecuting a stored procedure

L'esecuzione di una stored procedure avviene tramite l'esecuzione di un metodo HTTP POST su una risorsa stored procedure esistente passando i parametri alla procedura nel corpo della richiesta.Execution of a stored procedure is done by issuing an HTTP POST against an existing stored procedure resource by passing parameters to the procedure in the request body.

var inputDocument = {id : "document1", author: "G. G. Marquez"};
client.executeStoredProcedureAsync(createdStoredProcedure.resource._self, inputDocument)
    .then(function(executionResult) {
        assert.equal(executionResult, "success - created DOCUMENT1");
    }, function(error) {
        console.log("Error");
    });

Annullamento della registrazione di una stored procedureUnregistering a stored procedure

L'annullamento della registrazione di una stored procedure avviene tramite la semplice esecuzione di un'operazione HTTP DELETE su una risorsa stored procedure esistente.Unregistering a stored procedure is simply done by issuing an HTTP DELETE against an existing stored procedure resource.

client.deleteStoredProcedureAsync(createdStoredProcedure.resource._self)
    .then(function (response) {
        return;
    }, function(error) {
        console.log("Error");
    });

Registrazione di un triggerRegistering a pre-trigger

La registrazione di un trigger è eseguita tramite la creazione di una nuova risorsa trigger in una raccolta tramite HTTP POST.Registration of a trigger is done by creating a new trigger resource on a collection via HTTP POST. È possibile specificare se si tratta di un trigger di tipo pre o post e il tipo di operazione a cui può essere associato, ad esempio creazione, sostituzione, eliminazione o tutte le operazioni.You can specify if the trigger is a pre or a post trigger and the type of operation it can be associated with (e.g. Create, Replace, Delete, or All).

var preTrigger = {
    id: "upperCaseId",
    body: function() {
            var item = getContext().getRequest().getBody();
            item.id = item.id.toUpperCase();
            getContext().getRequest().setBody(item);
    },
    triggerType: TriggerType.Pre,
    triggerOperation: TriggerOperation.All
}

client.createTriggerAsync(collection._self, preTrigger)
    .then(function (createdPreTrigger) {
        console.log("Successfully created trigger");
    }, function(error) {
        console.log("Error");
    });

Esecuzione di un triggerExecuting a pre-trigger

L'esecuzione di un trigger è effettuata specificando il nome di un trigger esistente contemporaneamente all'emissione della richiesta POST/PUT/DELETE di una risorsa documento tramite l'intestazione della richiesta.Execution of a trigger is done by specifying the name of an existing trigger at the time of issuing the POST/PUT/DELETE request of a document resource via the request header.

client.createDocumentAsync(collection._self, { id: "doc1", key: "Love in the Time of Cholera" }, { preTriggerInclude: "upperCaseId" })
    .then(function(createdDocument) {
        assert.equal(createdDocument.resource.id, "DOC1");
    }, function(error) {
        console.log("Error");
    });

Annullamento della registrazione di un triggerUnregistering a pre-trigger

L'annullamento della registrazione di un trigger avviene tramite la semplice esecuzione di un'operazione HTTP DELETE su una risorsa trigger esistente.Unregistering a trigger is simply done via issuing an HTTP DELETE against an existing trigger resource.

client.deleteTriggerAsync(createdPreTrigger._self);
    .then(function(response) {
        return;
    }, function(error) {
        console.log("Error");
    });

Registrazione di una funzione UDFRegistering a UDF

La registrazione di una funzione UDF è eseguita tramite la creazione di una nuova risorsa UDF in una raccolta tramite HTTP POST.Registration of a UDF is done by creating a new UDF resource on a collection via HTTP POST.

var udf = { 
    id: "mathSqrt",
    body: function(number) {
            return Math.sqrt(number);
    },
};
client.createUserDefinedFunctionAsync(collection._self, udf)
    .then(function (createdUdf) {
        console.log("Successfully created stored procedure");
    }, function(error) {
        console.log("Error");
    });

Esecuzione di una funzione UDF come parte della queryExecuting a UDF as part of the query

Una funzione definita dall'utente può essere specificata come parte della query SQL e viene usata per estendere il linguaggio di query SQL dell'API di DocumentDB di base.A UDF can be specified as part of the SQL query and is used as a way to extend the core SQL query language for the DocumentDB API.

var filterQuery = "SELECT udf.mathSqrt(r.Age) AS sqrtAge FROM root r WHERE r.FirstName='John'";
client.queryDocuments(collection._self, filterQuery).toArrayAsync();
    .then(function(queryResponse) {
        var queryResponseDocuments = queryResponse.feed;
    }, function(error) {
        console.log("Error");
    });

Annullamento della registrazione di una funzione UDFUnregistering a UDF

L'annullamento della registrazione di una funzione definita dall'utente avviene tramite la semplice esecuzione di un'operazione HTTP DELETE su una risorsa di funzione definita dall'utente esistente.Unregistering a UDF is simply done by issuing an HTTP DELETE against an existing UDF resource.

client.deleteUserDefinedFunctionAsync(createdUdf._self)
    .then(function(response) {
        return;
    }, function(error) {
        console.log("Error");
    });

Anche se i frammenti di codice precedenti illustrano la registrazione (POST), l'annullamento della registrazione (PUT), la lettura/creazione di un elenco (GET) e l'esecuzione (POST) tramite JavaScript SDK, è anche possibile usare le API REST o altri SDK del client.Although the snippets above showed the registration (POST), unregistration (PUT), read/list (GET) and execution (POST) via the JavaScript SDK, you can also use the REST APIs or other client SDKs.

DocumentiDocuments

È possibile inserire, sostituire, eliminare, leggere, enumerare ed eseguire query in documenti JSON arbitrari in una raccolta.You can insert, replace, delete, read, enumerate and query arbitrary JSON documents in a collection. Azure Cosmos DB non impone alcuno schema e non richiede indici secondari per il supporto delle query sui documenti di una raccolta.Azure Cosmos DB does not mandate any schema and does not require secondary indexes in order to support querying over documents in a collection. Le dimensioni massime per un documento sono pari a 2 MB.The maximum size for a document is 2 MB.

Essendo un vero e proprio servizio di database aperto, Azure Cosmos DB non genera tipi di dati specializzati (ad esempio, data e ora) né codifiche specifiche per i documenti JSON.Being a truly open database service, Azure Cosmos DB does not invent any specialized data types (e.g. date time) or specific encodings for JSON documents. Tenere presente che Azure Cosmos DB non richiede alcuna convenzione JSON specifica per codificare le relazioni tra i diversi documenti. La sintassi SQL di Azure Cosmos DB fornisce operatori di query gerarchici e relazionali molto potenti per eseguire query e proiezioni sui documenti senza annotazioni speciali o senza dover codificare le relazioni tra i documenti usando proprietà distinte.Note that Azure Cosmos DB does not require any special JSON conventions to codify the relationships among various documents; the SQL syntax of Azure Cosmos DB provides very powerful hierarchical and relational query operators to query and project documents without any special annotations or need to codify relationships among documents using distinguished properties.

Analogamente a tutte le altre risorse, i documenti possono essere creati, sostituiti, eliminati, letti, enumerati e sottoposti a query con facilità tramite le API REST o uno degli SDK dei client.As with all other resources, documents can be created, replaced, deleted, read, enumerated and queried easily using either REST APIs or any of the client SDKs. Se si elimina un documento, la quota corrispondente a tutti gli allegati annidati sarà resa immediatamente disponibile.Deleting a document instantly frees up the quota corresponding to all of the nested attachments. Il livello di coerenza di lettura dei documenti segue i criteri di coerenza applicati all'account di database.The read consistency level of documents follows the consistency policy on the database account. È possibile eseguire l'override di questo criterio per le singole richieste, in base ai requisiti di coerenza dei dati specifici dell'applicazione.This policy can be overridden on a per-request basis depending on data consistency requirements of your application. Durante l'esecuzione di query nei documenti, la coerenza di lettura si basa sulla modalità di indicizzazione impostata per la raccolta.When querying documents, the read consistency follows the indexing mode set on the collection. Ai fini della coerenza, si basa sui criteri di coerenza dell'account.For “consistent”, this follows the account’s consistency policy.

Allegati e file multimedialiAttachments and media

Azure Cosmos DB consente di archiviare BLOB/file multimediali binari con Azure Cosmos DB (al massimo 2 GB per account) o nel proprio archivio multimediale remoto.Azure Cosmos DB allows you to store binary blobs/media either with Azure Cosmos DB (maximum of 2 GB per account) or to your own remote media store. Permette anche di rappresentare i metadati dei file multimediali sotto forma di un documento speciale definito allegato.It also allows you to represent the metadata of a media in terms of a special document called attachment. Un allegato in Azure Cosmos DB è un documento speciale (JSON) che fa riferimento a file multimediali/BLOB archiviati altrove.An attachment in Azure Cosmos DB is a special (JSON) document that references the media/blob stored elsewhere. Un allegato è semplicemente un documento speciale che acquisisce i metadati, come percorso, autore e così via, di un file multimediale archiviato in una risorsa di archiviazione multimediale remota.An attachment is simply a special document that captures the metadata (e.g. location, author etc.) of a media stored in a remote media storage.

Si prenda in considerazione un'applicazione di lettura di social media che usa Azure Cosmos DB per archiviare annotazioni a penna e metadati, inclusi commenti, evidenziazioni, segnalibri, valutazioni, commenti di tipo mi piace/non mi piace e così via, associati a un e-book di un utente specifico.Consider a social reading application which uses Azure Cosmos DB to store ink annotations, and metadata including comments, highlights, bookmarks, ratings, likes/dislikes etc. associated for an e-book of a given user.

  • Il contenuto del libro stesso è archiviato nell'archivio multimediale disponibile come parte dell'account di database di Azure Cosmos DB o in un archivio multimediale remoto.The content of the book itself is stored in the media storage either available as part of Azure Cosmos DB database account or a remote media store.
  • Un'applicazione può archiviare i metadati di ogni utente come documento distinto, ad esempio i metadati di Joe per book1 saranno archiviati in un documento a cui si fa riferimento come /colls/joe/docs/book1.An application may store each user’s metadata as a distinct document -- e.g. Joe’s metadata for book1 is stored in a document referenced by /colls/joe/docs/book1.
  • Gli allegati che fanno riferimento alle pagine di contenuto di un determinato e-book di un utente sono archiviati nel documento corrispondente, ad esempio /colls/joe/docs/book1/chapter1, /colls/joe/docs/book1/chapter2 e così via.Attachments pointing to the content pages of a given book of a user are stored under the corresponding document e.g. /colls/joe/docs/book1/chapter1, /colls/joe/docs/book1/chapter2 etc.

Si noti che gli esempi appena riportati usano ID descrittivi per indicare la gerarchia delle risorse.Note that the examples listed above use friendly ids to convey the resource hierarchy. L'accesso alle risorse è effettuato tramite le API REST mediante ID di risorsa univoci.Resources are accessed via the REST APIs through unique resource ids.

Nel caso dei file multimediali gestiti da Azure Cosmos DB, la proprietà _media dell'allegato farà riferimento al file multimediale tramite l'URI.For the media that is managed by Azure Cosmos DB, the _media property of the attachment will reference the media by its URI. Azure Cosmos DB assicura la procedura di Garbage Collection del file multimediale dopo il rilascio di tutti i riferimenti in sospeso.Azure Cosmos DB will ensure to garbage collect the media when all of the outstanding references are dropped. Azure Cosmos DB genera automaticamente l'allegato quando si carica il nuovo file multimediale e popola la proprietà _media in modo che faccia riferimento ai nuovi file multimediali aggiunti.Azure Cosmos DB automatically generates the attachment when you upload the new media and populates the _media to point to the newly added media. Se si sceglie di archiviare i file multimediali in un archivio BLOB remoto gestito personalmente, ad esempio OneDrive, Archiviazione di Azure, Dropbox e così via, sarà comunque possibile usare gli allegati per fare riferimento ai file multimediali.If you choose to store the media in a remote blob store managed by you (e.g. OneDrive, Azure Storage, DropBox etc), you can still use attachments to reference the media. In questo caso sarà necessario creare personalmente l'allegato e popolarne la proprietà _media.In this case, you will create the attachment yourself and populate its _media property.

Analogamente a tutte le altre risorse, gli allegati possono essere creati, sostituiti, eliminati, letti o enumerati con facilità tramite le API REST o uno degli SDK dei client.As with all other resources, attachments can be created, replaced, deleted, read or enumerated easily using either REST APIs or any of the client SDKs. Come per i documenti, il livello di coerenza di lettura degli allegati segue i criteri di coerenza applicati all'account di database.As with documents, the read consistency level of attachments follows the consistency policy on the database account. È possibile eseguire l'override di questo criterio per le singole richieste, in base ai requisiti di coerenza dei dati specifici dell'applicazione.This policy can be overridden on a per-request basis depending on data consistency requirements of your application. Durante l'esecuzione di query relative agli allegati, la coerenza di lettura si basa sulla modalità di indicizzazione impostata per la raccolta.When querying for attachments, the read consistency follows the indexing mode set on the collection. Ai fini della coerenza, si basa sui criteri di coerenza dell'account.For “consistent”, this follows the account’s consistency policy.

UtentiUsers

Un utente di Azure Cosmos DB rappresenta uno spazio dei nomi logico per il raggruppamento di autorizzazioni.An Azure Cosmos DB user represents a logical namespace for grouping permissions. Un utente di Azure Cosmos DB può corrispondere a un utente in un sistema di gestione delle identità o a un ruolo applicazione predefinito.An Azure Cosmos DB user may correspond to a user in an identity management system or a predefined application role. In Azure Cosmos DB un utente rappresenta semplicemente un'astrazione per raggruppare un set di autorizzazioni in un database.For Azure Cosmos DB, a user simply represents an abstraction to group a set of permissions under a database.

Per l'implementazione della multi-tenancy nell'applicazione, è possibile creare utenti in Azure Cosmos DB corrispondenti agli utenti effettivi o ai tenant dell'applicazione.For implementing multi-tenancy in your application, you can create users in Azure Cosmos DB which corresponds to your actual users or the tenants of your application. È quindi possibile creare autorizzazioni per un utente specifico, corrispondenti al controllo di accesso su diversi documenti, raccolte, allegati e così via.You can then create permissions for a given user that correspond to the access control over various collections, documents, attachments, etc.

Poiché la scalabilità delle applicazione deve essere adeguata all'incremento degli utenti, è possibile adottare modi diversi per partizionare i dati.As your applications need to scale with your user growth, you can adopt various ways to shard your data. È possibile modellare ogni utente in modo che:You can model each of your users as follows:

  • Ogni utente venga mappato a un database.Each user maps to a database.
  • Ogni utente venga mappato a una raccolta.Each user maps to a collection.
  • I documenti corrispondenti a più utenti passino a una raccolta dedicata.Documents corresponding to multiple users go to a dedicated collection.
  • I documenti corrispondenti a più utenti passino a un set di raccolte.Documents corresponding to multiple users go to a set of collections.

Indipendentemente dalla strategia di partizionamento orizzontale scelta, è possibile modellare gli utenti effettivi come utenti nel database di Azure Cosmos DB e associare autorizzazioni dettagliate a ogni utente.Regardless of the specific sharding strategy you choose, you can model your actual users as users in Azure Cosmos DB database and associate fine grained permissions to each user.

Raccolte degli utentiUser collections
Strategie di partizionamento orizzontale e modellazione degli utentiSharding strategies and modeling users

Analogamente a tutte le altre risorse, gli utenti in Azure Cosmos DB possono essere creati, sostituiti, eliminati, letti o enumerati con facilità usando le API REST o uno degli SDK client.Like all other resources, users in Azure Cosmos DB can be created, replaced, deleted, read or enumerated easily using either REST APIs or any of the client SDKs. Azure Cosmos DB offre sempre una coerenza assoluta per la lettura o l'esecuzione di query sui metadati di una risorsa utente.Azure Cosmos DB always provides strong consistency for reading or querying the metadata of a user resource. È utile segnalare che se si elimina un utente, non sarà automaticamente più possibile accedere alle autorizzazioni incluse nell'utente stesso.It is worth pointing out that deleting a user automatically ensures that you cannot access any of the permissions contained within it. Anche se Azure Cosmos DB recupera la quota di autorizzazioni come parte dell'utente eliminato in background, le autorizzazioni eliminate saranno disponibili immediatamente per un nuovo uso.Even though the Azure Cosmos DB reclaims the quota of the permissions as part of the deleted user in the background, the deleted permissions is available instantly again for you to use.

AutorizzazioniPermissions

Dal punto di vista del controllo di accesso, le risorse quali account di database, database, utenti e autorizzazioni sono considerate come risorse amministrative perché necessitano di autorizzazioni amministrative.From an access control perspective, resources such as database accounts, databases, users and permission are considered administrative resources since these require administrative permissions. L'ambito di risorse quali raccolte, documenti, allegati, stored procedure, trigger e funzioni UDF invece è limitato a un database specifico e queste risorse sono considerate risorse dell'applicazione.On the other hand, resources including the collections, documents, attachments, stored procedures, triggers, and UDFs are scoped under a given database and considered application resources. Il modello di autorizzazione, che corrisponde ai due tipi di risorse e ai ruoli che vi accedono, ovvero l'amministratore e l'utente, definisce due tipi di chiavi di accesso: chiave master e chiave risorsa.Corresponding to the two types of resources and the roles that access them (namely the administrator and user), the authorization model defines two types of access keys: master key and resource key. La chiave master fa parte dell'account di database ed è fornita allo sviluppatore o all'amministratore che esegue il provisioning dell'account di database.The master key is a part of the database account and is provided to the developer (or administrator) who is provisioning the database account. La chiave master usa semantica di amministratore, ovvero può essere usata per autorizzare l'accesso alle risorse amministrative e dell'applicazione.This master key has administrator semantics, in that it can be used to authorize access to both administrative and application resources. La chiave di risorsa, invece, è una chiave di accesso granulare che permette l'accesso a una risorsa specifica dell'applicazione.In contrast, a resource key is a granular access key that allows access to a specific application resource. Acquisisce quindi la relazione tra l'utente di un database e le autorizzazioni di cui l'utente dispone per una risorsa specifica, ad esempio una raccolta, un documento, un allegato, una stored procedure, un trigger o una funzione UDF.Thus, it captures the relationship between the user of a database and the permissions the user has for a specific resource (e.g. collection, document, attachment, stored procedure, trigger, or UDF).

L'unico modo per ottenere una chiave di risorsa consiste nella creazione di una risorsa di autorizzazione per un utente specifico.The only way to obtain a resource key is by creating a permission resource under a given user. Si noti che per creare o recuperare un'autorizzazione è necessario presentare una chiave master nell'intestazione dell'autorizzazione.Note that In order to create or retrieve a permission, a master key must be presented in the authorization header. Una risorsa di autorizzazione associa la risorsa, l'accesso e l'utente.A permission resource ties the resource, its access and the user. Dopo la creazione di una risorsa di autorizzazione, l'utente dovrà solo presentare la chiave di risorsa associata per ottenere l'accesso alla risorsa rilevante.After creating a permission resource, the user only needs to present the associated resource key in order to gain access to the relevant resource. Una chiave di risorsa può essere quindi considerata come una rappresentazione logica e compatta della risorsa di autorizzazione.Hence, a resource key can be viewed as a logical and compact representation of the permission resource.

Come per tutte le altre risorse, le autorizzazioni in Azure Cosmos DB possono essere create, sostituite, eliminate, lette o enumerate facilmente usando le API REST o uno degli SDK client.As with all other resources, permissions in Azure Cosmos DB can be created, replaced, deleted, read or enumerated easily using either REST APIs or any of the client SDKs. Azure Cosmos DB offre sempre una coerenza assoluta per la lettura o l'esecuzione di query sui metadati di un'autorizzazione.Azure Cosmos DB always provides strong consistency for reading or querying the metadata of a permission.

Passaggi successiviNext steps

Per altre informazioni sull'uso di risorse tramite comandi HTTP, vedere RESTful interactions with Azure Cosmos DB resources (Interazioni di tipo RESTful con risorse di Azure Cosmos DB).Learn more about working with resources by using HTTP commands in RESTful interactions with Azure Cosmos DB resources.