Suggerimenti sulle prestazioni per Azure Cosmos DBPerformance tips for Azure Cosmos DB

Azure Cosmos DB è un database distribuito veloce e flessibile, facilmente scalabile e con latenza e velocità effettiva garantite.Azure Cosmos DB is a fast and flexible distributed database that scales seamlessly with guaranteed latency and throughput. Non è necessario apportare modifiche significative all'architettura o scrivere codice complesso per ridimensionare il database con Cosmos DB.You do not have to make major architecture changes or write complex code to scale your database with Cosmos DB. Aumentare o ridurre le prestazioni è semplice come eseguire una singola chiamata API o una chiamata al metodo SDK.Scaling up and down is as easy as making a single API call or SDK method call. Dato che si accede a Cosmos DB tramite chiamate di rete, tuttavia, è possibile apportare ottimizzazioni lato client per ottenere prestazioni ottimali.However, because Cosmos DB is accessed via network calls there are client-side optimizations you can make to achieve peak performance.

Se si vogliono migliorare le prestazioni del database,So if you're asking "How can I improve my database performance?" prendere in considerazione le opzioni seguenti:consider the following options:

ReteNetworking

  1. Criteri di connessione: usare la modalità di connessione direttaConnection policy: Use direct connection mode

    La modalità di connessione di un client a Cosmos DB influisce significativamente sulle prestazioni, in particolare in termini di latenza lato client osservata.How a client connects to Cosmos DB has important implications on performance, especially in terms of observed client-side latency. Sono disponibili due impostazioni di configurazione chiave per la configurazione dei criteri di connessione client, ovvero la modalità di connessione e il protocollo di connessione.There are two key configuration settings available for configuring client Connection Policy – the connection mode and the connection protocol. Le due modalità disponibili sono:The two available modes are:

    1. Modalità gateway (predefinita)Gateway Mode (default)
    2. Modalità direttaDirect Mode

      La modalità gateway è supportata in tutte le piattaforme SDK ed è l'impostazione predefinita configurata.Gateway Mode is supported on all SDK platforms and is the configured default. Se l'applicazione è in esecuzione in una rete aziendale con limitazioni rigide del firewall, la modalità gateway è la scelta migliore, perché usa la porta HTTPS standard e un singolo endpoint.If your application runs within a corporate network with strict firewall restrictions, Gateway Mode is the best choice since it uses the standard HTTPS port and a single endpoint. A livello di prestazioni, tuttavia, la modalità gateway prevede un hop di rete aggiuntivo ogni volta che i dati vengono letti o scritti in Cosmos DB.The performance tradeoff, however, is that Gateway Mode involves an additional network hop every time data is read or written to Cosmos DB. La modalità diretta offre quindi prestazioni migliori grazie al numero minore di hop di rete.Because of this, Direct Mode offers better performance due to fewer network hops.

  2. Criteri di connessione: usare il protocollo TCPConnection policy: Use the TCP protocol

    Quando si usa la modalità diretta, sono disponibili due opzioni del protocollo:When using Direct Mode, there are two protocol options available:

    • TCPTCP
    • HTTPSHTTPS

      Cosmos DB offre un modello di programmazione RESTful su HTTPS semplice e aperto.Cosmos DB offers a simple and open RESTful programming model over HTTPS. DocumentDB offre anche un protocollo TCP efficiente, con un modello di comunicazione di tipo RESTful disponibile tramite .NET SDK per client.Additionally, it offers an efficient TCP protocol, which is also RESTful in its communication model and is available through the .NET client SDK. Sia il protocollo TCP diretto che il protocollo HTTPS usano SSL per l'autenticazione iniziale e la crittografia del traffico.Both Direct TCP and HTTPS use SSL for initial authentication and encrypting traffic. Per prestazioni ottimali, usare il protocollo TCP quando possibile.For best performance, use the TCP protocol when possible.

      Quando si usa TCP in modalità gateway, la porta TCP 443 è la porta di Cosmos DB, mentre la porta 10255 è la porta dell'API MongoDB.When using TCP in Gateway Mode, TCP Port 443 is the Cosmos DB port, and 10255 is the MongoDB API port. Quando si usa TCP in modalità diretta, oltre alle porte gateway è necessario verificare che le porte nell'intervallo tra 10000 e 20000 siano aperte perché Cosmos DB usa porte TCP dinamiche.When using TCP in Direct Mode, in addition to the Gateway ports, you need to ensure the port range between 10000 and 20000 is open because Cosmos DB uses dynamic TCP ports. Se queste porte non sono aperte e si tenta di usare TCP, si riceverà un errore 503 (Servizio non disponibile).If these ports are not open and you attempt to use TCP, you receive a 503 Service Unavailable error.

      La modalità di connessione viene configurata durante la creazione dell'istanza di DocumentClient con il parametro ConnectionPolicy.The Connectivity Mode is configured during the construction of the DocumentClient instance with the ConnectionPolicy parameter. Se si usa la modalità diretta, è possibile configurare il protocollo entro il parametro ConnectionPolicy.If Direct Mode is used, the Protocol can also be set within the ConnectionPolicy parameter.

      var serviceEndpoint = new Uri("https://contoso.documents.net");
      var authKey = new "your authKey from the Azure portal";
      DocumentClient client = new DocumentClient(serviceEndpoint, authKey,
      new ConnectionPolicy
      {
         ConnectionMode = ConnectionMode.Direct,
         ConnectionProtocol = Protocol.Tcp
      });
      

      Poiché TCP è supportato solo in modalità diretta, se si usa la modalità gateway viene usato sempre il protocollo HTTPS per comunicare con il gateway e il valore del protocollo in ConnectionPolicy viene ignorato.Because TCP is only supported in Direct Mode, if Gateway Mode is used, then the HTTPS protocol is always used to communicate with the Gateway and the Protocol value in the ConnectionPolicy is ignored.

      Illustrazione dei criteri di connessione di Azure Cosmos DB

  3. Chiamare OpenAsync per evitare la latenza di avvio alla prima richiestaCall OpenAsync to avoid startup latency on first request

    Per impostazione predefinita, la prima richiesta ha una latenza più elevata perché deve recuperare la tabella di routing degli indirizzi.By default, the first request has a higher latency because it has to fetch the address routing table. Per evitare questa latenza di avvio alla prima richiesta, è necessario chiamare OpenAsync() una volta durante l'inizializzazione, come indicato di seguito.To avoid this startup latency on the first request, you should call OpenAsync() once during initialization as follows.

     await client.OpenAsync();
    

  4. Collocare i client nella stessa area di Azure per ottenere prestazioni miglioriCollocate clients in same Azure region for performance

    Quando possibile, posizionare eventuali applicazioni che chiamano Cosmos DB nella stessa area del database Cosmos DB.When possible, place any applications calling Cosmos DB in the same region as the Cosmos DB database. Per un confronto approssimativo, le chiamate a Cosmos DB eseguite nella stessa area vengono completate entro 1-2 millisecondi, mentre la latenza tra la costa occidentale e quella orientale degli Stati Uniti è > 50 millisecondi.For an approximate comparison, calls to Cosmos DB within the same region complete within 1-2 ms, but the latency between the West and East coast of the US is >50 ms. Questa latenza può variare da richiesta a richiesta, in base alla route seguita dalla richiesta durante il passaggio dal client al limite del data center di Azure.This latency can likely vary from request to request depending on the route taken by the request as it passes from the client to the Azure datacenter boundary. È possibile ottenere la latenza più bassa possibile assicurandosi che l'applicazione chiamante si trovi nella stessa area di Azure in cui si trova l'endpoint di Cosmos DB con provisioning.The lowest possible latency is achieved by ensuring the calling application is located within the same Azure region as the provisioned Cosmos DB endpoint. Per un elenco delle aree disponibili, vedere Aree di Azure.For a list of available regions, see Azure Regions.

    Illustrazione dei criteri di connessione di Azure Cosmos DB Illustration of the Azure Cosmos DB connection policy

  5. Aumentare il numero di thread/attivitàIncrease number of threads/tasks

    Dato che le chiamate ad Azure Cosmos DB vengono eseguite sulla rete, può essere necessario modificare il grado di parallelismo delle richieste in modo che i tempi di attesa dell'applicazione client tra le richieste siano molto ridotti.Since calls to Azure Cosmos DB are made over the network, you may need to vary the degree of parallelism of your requests so that the client application spends very little time waiting between requests. Se si usa Task Parallel Library di .NET, ad esempio, creare centinaia di attività di lettura o scrittura in Cosmos DB.For example, if you're using .NET's Task Parallel Library, create in the order of 100s of Tasks reading or writing to Cosmos DB.

Uso dell'SDKSDK Usage

  1. Installare l'SDK più recenteInstall the most recent SDK

    Agli SDK di Cosmos DB vengono apportati continui miglioramenti per offrire prestazioni ottimali.The Cosmos DB SDKs are constantly being improved to provide the best performance. Per determinare la versione di SDK più recente e verificare i miglioramenti, vedere le pagine relative agli SDK di Cosmos DB.See the Cosmos DB SDK pages to determine the most recent SDK and review improvements.

  2. Usare un client Cosmos DB singleton per la durata dell'applicazioneUse a singleton Cosmos DB client for the lifetime of your application

    Si noti che ogni istanza di DocumentClient è thread-safe ed esegue la gestione efficiente delle connessioni e la memorizzazione nella cache degli indirizzi quando viene usata la modalità diretta.Note that each DocumentClient instance is thread-safe and performs efficient connection management and address caching when operating in Direct Mode. Per consentire una gestione efficiente delle connessioni e prestazioni migliori da parte di DocumentClient, è consigliabile usare una singola istanza di DocumentClient per ogni AppDomain per la durata dell'applicazione.To allow efficient connection management and better performance by DocumentClient, it is recommended to use a single instance of DocumentClient per AppDomain for the lifetime of the application.

  3. Aumentare il valore di System.Net MaxConnections per host se si usa la modalità Gateway.Increase System.Net MaxConnections per host when using Gateway mode

    Quando si usa la modalità gateway, le richieste di Cosmos DB vengono eseguite su HTTPS/REST e sono soggette ai limiti di connessione predefiniti per ogni nome host o indirizzo IP.Cosmos DB requests are made over HTTPS/REST when using Gateway mode, and are subjected to the default connection limit per hostname or IP address. Può essere necessario impostare MaxConnections su un valore più alto (100-1000) in modo che la libreria client possa usare più connessioni simultanee a Cosmos DB.You may need to set the MaxConnections to a higher value (100-1000) so that the client library can utilize multiple simultaneous connections to Cosmos DB. In .NET SDK 1.8.0 e versioni successive il valore predefinito per ServicePointManager.DefaultConnectionLimit è 50 e per modificare il valore è possibile impostare Documents.Client.ConnectionPolicy.MaxConnectionLimit su un valore più elevato.In the .NET SDK 1.8.0 and above, the default value for ServicePointManager.DefaultConnectionLimit is 50 and to change the value, you can set the Documents.Client.ConnectionPolicy.MaxConnectionLimit to a higher value.

  4. Ottimizzazione delle query parallele per le raccolte partizionateTuning parallel queries for partitioned collections

    DocumentDB .NET SDK 1.9.0 e versioni successive supportano le query parallele, che consentono di eseguire query in una raccolta partizionata in parallelo. Vedere Uso degli SDK e i relativi esempi di codice per maggiori dettagli.DocumentDB .NET SDK version 1.9.0 and above support parallel queries, which enable you to query a partitioned collection in parallel (see Working with the SDKs and the related code samples for more info). Le query parallele sono state concepite per migliorare la velocità e la latenza delle query sulle loro controparti seriali.Parallel queries are designed to improve query latency and throughput over their serial counterpart. Mettono a disposizione due parametri che gli utenti possono ottimizzare in funzione dei requisiti, ovvero (a) MaxDegreeOfParallelism per definire il numero massimo di partizioni sulle quali è possibile eseguire query in parallelo e (b) MaxBufferedItemCount per definire il numero di risultati di prelettura.Parallel queries provide two parameters that users can tune to custom-fit their requirements, (a) MaxDegreeOfParallelism: to control the maximum number of partitions then can be queried in parallel, and (b) MaxBufferedItemCount: to control the number of pre-fetched results.

    (a) Ottimizzazione di MaxDegreeOfParallelism: la query parallela funziona eseguendo query su più partizioni in parallelo.(a) Tuning MaxDegreeOfParallelism: Parallel query works by querying multiple partitions in parallel. I dati di una singola raccolta partizionata vengono recuperati in modo seriale per quanto riguarda la query.However, data from an individual partitioned collect is fetched serially with respect to the query. L'impostazione di MaxDegreeOfParallelism sul numero di partizioni offre quindi la massima probabilità di ottenere la query più efficiente, se tutte le altre condizioni del sistema rimangono invariate.So, setting the MaxDegreeOfParallelism to the number of partitions has the maximum chance of achieving the most performant query, provided all other system conditions remain the same. Se non si conosce il numero di partizioni, è possibile impostare il valore di MaxDegreeOfParallelism su un numero elevato; il sistema sceglie il numero minimo (numero di partizioni, input specificato dall'utente) come valore di MaxDegreeOfParallelism.If you don't know the number of partitions, you can set the MaxDegreeOfParallelism to a high number, and the system chooses the minimum (number of partitions, user provided input) as the MaxDegreeOfParallelism.

    È importante notare che le query parallele producono i vantaggi migliori se i dati sono distribuiti uniformemente tra tutte le partizioni per quanto riguarda la query.It is important to note that parallel queries produce the best benefits if the data is evenly distributed across all partitions with respect to the query. Se la raccolta è partizionata in modo tale che tutti o la maggior parte dei dati restituiti da una query siano concentrati in alcune partizioni (una sola partizione nel peggiore dei casi), le prestazioni della query potrebbero essere limitate da tali partizioni.If the partitioned collection is partitioned such a way that all or a majority of the data returned by a query is concentrated in a few partitions (one partition in worst case), then the performance of the query would be bottlenecked by those partitions.

    (b) Ottimizzazione di MaxBufferedItemCount: la query parallela è progettata per la prelettura dei risultati mentre il client elabora il batch di risultati corrente.(b) Tuning MaxBufferedItemCount: Parallel query is designed to pre-fetch results while the current batch of results is being processed by the client. La prelettura consente il miglioramento complessivo della latenza di una query.The pre-fetching helps in overall latency improvement of a query. MaxBufferedItemCount è il parametro che consente di limitare il numero di risultati di prelettura.MaxBufferedItemCount is the parameter to limit the number of pre-fetched results. L'impostazione di MaxBufferedItemCount sul numero previsto di risultati restituiti (o un numero più alto) consente alla query di ottenere il massimo vantaggio dalla prelettura.Setting MaxBufferedItemCount to the expected number of results returned (or a higher number) allows the query to receive maximum benefit from pre-fetching.

    Si noti che la prelettura funziona allo stesso modo indipendentemente dall'impostazione di MaxDegreeOfParallelism e che è presente un solo buffer per i dati di tutte le partizioni.Note that pre-fetching works the same way irrespective of the MaxDegreeOfParallelism, and there is a single buffer for the data from all partitions.

  5. Attivare GC sul lato serverTurn on server-side GC

    In alcuni casi, può essere utile ridurre la frequenza di Garbage Collection.Reducing the frequency of garbage collection may help in some cases. In .NET impostare gcServer su true.In .NET, set gcServer to true.

  6. Implementare il backoff in corrispondenza di intervalli RetryAfterImplement backoff at RetryAfter intervals

    Durante il test delle prestazioni, è necessario aumentare il carico fino a limitare un numero ridotto di richieste.During performance testing, you should increase load until a small rate of requests get throttled. Se limitata, l'applicazione client deve eseguire il backoff sulla limitazione per l'intervallo tra tentativi specificato dal server.If throttled, the client application should backoff on throttle for the server-specified retry interval. Rispettando il backoff si garantiscono tempi di attesa minimi tra i tentativi.Respecting the backoff ensures that you spend minimal amount of time waiting between retries. Il supporto dei criteri di ripetizione dei tentativi è incluso nella versione 1.8.0 e versioni successive degli SDK .NET e Java, nella versione 1.9.0 e versioni successive degli SDK Node.js e Python e in tutte le versioni supportate degli SDK .NET Core di DocumentDB.Retry policy support is included in Version 1.8.0 and above of the DocumentDB .NET and Java, version 1.9.0 and above of the Node.js and Python, and all supported versions of the .NET Core SDKs. Per altre informazioni, vedere Superamento dei limiti della velocità effettiva riservata e RetryAfter.For more information, see Exceeding reserved throughput limits and RetryAfter.

  7. Aumentare il carico di lavoro clientScale out your client-workload

    Se si sta eseguendo il test a livelli di velocità effettiva elevati (> 50.000 UR/sec), l'applicazione client può diventare un collo di bottiglia a causa della limitazione di utilizzo della CPU o della rete.If you are testing at high throughput levels (>50,000 RU/s), the client application may become the bottleneck due to the machine capping out on CPU or Network utilization. In questo caso, è possibile continuare a effettuare il push dell'account Cosmos DB aumentando il numero di istanze delle applicazioni client in più server.If you reach this point, you can continue to push the Cosmos DB account further by scaling out your client applications across multiple servers.

  8. Memorizzare nella cache gli URI dei documenti per una minore latenza di letturaCache document URIs for lower read latency

    Memorizzare nella cache gli URI dei documenti quando possibile per ottenere prestazioni di lettura ottimali.Cache document URIs whenever possible for the best read performance.

  9. Modificare le dimensioni di pagina per le query o i feed di lettura per ottenere prestazioni miglioriTune the page size for queries/read feeds for better performance

    Quando si esegue una lettura in blocco di documenti usando la funzionalità dei feed di lettura, ad esempio ReadDocumentFeedAsync, oppure quando si emette una query SQL di DocumentDB, i risultati vengono restituiti in modo segmentato se il set di risultati è troppo grande.When performing a bulk read of documents using read feed functionality (for example, ReadDocumentFeedAsync) or when issuing a DocumentDB SQL query, the results are returned in a segmented fashion if the result set is too large. Per impostazione predefinita, i risultati vengono restituiti in blocchi di 100 elementi o 1 MB, a seconda del limite che viene raggiunto prima.By default, results are returned in chunks of 100 items or 1 MB, whichever limit is hit first.

    Per ridurre il numero di round trip di rete necessari per recuperare tutti i risultati applicabili, è possibile aumentare le dimensioni di pagina usando l'intestazione di richiesta x-ms-max-item-count fino a 1000.To reduce the number of network round trips required to retrieve all applicable results, you can increase the page size using x-ms-max-item-count request header to up to 1000. Nei casi in cui è necessario visualizzare solo alcuni risultati, ad esempio se l'interfaccia utente o l'API dell'applicazione restituisce solo 10 risultati alla volta, è anche possibile ridurre le dimensioni di pagina a 10 in modo da ridurre la velocità effettiva usata per le letture e le query.In cases where you need to display only a few results, for example, if your user interface or application API returns only 10 results a time, you can also decrease the page size to 10 to reduce the throughput consumed for reads and queries.

    È anche possibile impostare le dimensioni di pagina usando gli SDK di Cosmos DB disponibili.You may also set the page size using the available Cosmos DB SDKs. ad esempio:For example:

     IQueryable<dynamic> authorResults = client.CreateDocumentQuery(documentCollection.SelfLink, "SELECT p.Author FROM Pages p WHERE p.Title = 'About Seattle'", new FeedOptions { MaxItemCount = 1000 });
    
  10. Aumentare il numero di thread/attivitàIncrease number of threads/tasks

    Vedere Aumentare il numero di thread/attività nella sezione Rete.See Increase number of threads/tasks in the Networking section.

  11. Usare processi host a 64 bitUse 64-bit host processing

    L'SDK di DocumentDB funziona in un processo host a 32 bit quando si usa DocumentDB .NET SDK versione 1.11.4 e versioni successive.The DocumentDB SDK works in a 32-bit host process when you are using DocumentDB .NET SDK version 1.11.4 and above. Tuttavia, se si usano query tra partizioni, è consigliabile usare l'elaborazione dell'host a 64 bit per migliorare le prestazioni.However, if you are using cross partition queries, 64-bit host processing is recommended for improved performance. I tipi seguenti di applicazioni dispongono di un processo host a 32 bit per impostazione predefinita; per passare a un processo a 64 bit, seguire questi passaggi in base al tipo di applicazione:The following types of applications have 32-bit host process as the default, so in order to change that to 64-bit, follow these steps based on the type of your application:

    • Per le applicazioni eseguibili è possibile, a tale scopo, deselezionare l'opzione Preferisci 32 bit nella scheda Compila della finestra Proprietà progetto.For Executable applications, this can be done by unchecking the Prefer 32-bit option in the Project Properties window, on the Build tab.

    • Per progetti di test basati su VSTest questa operazione può essere eseguita selezionando Test->Impostazioni test->Default Processor Architecture as X64 (Imposta architettura processore X64 come predefinita) dall'opzione Visual Studio Test.For VSTest based test projects, this can be done by selecting Test->Test Settings->Default Processor Architecture as X64, from the Visual Studio Test menu option.

    • Per le applicazioni Web ASP.NET distribuite in locale questa operazione può essere eseguita selezionando Utilizzare la versione a 64 bit di IIS Express per progetti e siti Web in Strumenti->Opzioni->Progetti e soluzioni->Progetti Web.For locally deployed ASP.NET Web applications, this can be done by checking the Use the 64-bit version of IIS Express for web sites and projects, under Tools->Options->Projects and Solutions->Web Projects.

    • Per le applicazioni Web ASP.NET distribuite in Azure questa operazione può essere eseguita selezionando Platform as 64-bit (Piattaforma 64 bit) in Impostazioni applicazione nel Portale di Azure.For ASP.NET Web applications deployed on Azure, this can be done by choosing the Platform as 64-bit in the Application Settings on the Azure portal.

Criterio di indicizzazioneIndexing Policy

  1. Escludere i percorsi non usati dall'indicizzazione per scritture più velociExclude unused paths from indexing for faster writes

    I criteri di indicizzazione di Cosmos DB consentono anche di specificare i percorsi dei documenti da includere o escludere dall'indicizzazione sfruttando i percorsi di indicizzazione (IndexingPolicy.IncludedPaths e IndexingPolicy.ExcludedPaths).Cosmos DB’s indexing policy also allows you to specify which document paths to include or exclude from indexing by leveraging Indexing Paths (IndexingPolicy.IncludedPaths and IndexingPolicy.ExcludedPaths). L'uso dei percorsi di indicizzazione può consentire di ottenere prestazioni migliori e di ridurre le risorse di archiviazione dell'indice per gli scenari in cui i modelli di query sono noti in anticipo, poiché i costi dell'indicizzazione sono correlati direttamente al numero di percorsi univoci indicizzati.The use of indexing paths can offer improved write performance and lower index storage for scenarios in which the query patterns are known beforehand, as indexing costs are directly correlated to the number of unique paths indexed. Ad esempio, il codice seguente illustra come escludere un'intera sezione dei documenti, detta ancheFor example, the following code shows how to exclude an entire section of the documents (a.k.a. sottoalbero, dall'indicizzazione usando il carattere jolly "".a subtree) from indexing using the "" wildcard.

    var collection = new DocumentCollection { Id = "excludedPathCollection" };
    collection.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
    collection.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
    collection = await client.CreateDocumentCollectionAsync(UriFactory.CreateDatabaseUri("db"), excluded);
    

    Per altre informazioni, vedere l'articolo relativo ai criteri di indicizzazione di Azure Cosmos DB.For more information, see Azure Cosmos DB indexing policies.

Velocità effettivaThroughput

  1. Misurare e ottimizzare per ottenere un utilizzo minore di unità richiesta al secondoMeasure and tune for lower request units/second usage

    Cosmos DB offre un'ampia gamma di operazioni di database, incluse le query relazionali e gerarchiche con funzioni definite dall'utente, stored procedure e trigger, operative nei documenti in una raccolta di database.Cosmos DB offers a rich set of database operations including relational and hierarchical queries with UDFs, stored procedures, and triggers – all operating on the documents within a database collection. Il costo associato a ognuna di queste operazioni dipende da CPU, I/O e memoria necessari per il completamento dell'operazione.The cost associated with each of these operations varies based on the CPU, IO, and memory required to complete the operation. Invece di occuparsi della pianificazione e della gestione delle risorse hardware, sarà possibile usare un'unità di richiesta come misura singola per le risorse necessarie per eseguire diverse operazioni di database e rispondere a una richiesta dell'applicazione.Instead of thinking about and managing hardware resources, you can think of a request unit (RU) as a single measure for the resources required to perform various database operations and service an application request.

    Viene eseguito il provisioning della velocità effettiva in base alla quantità di unità di richiesta impostata per ogni contenitore.Throughput is provisioned based on the amount of request units set for each container. Il consumo delle unità di richiesta è valutato in base alla frequenza al secondo.Request unit consumption is evaluated as a rate per second. Le applicazioni che superano la frequenza di unità richiesta con provisioning previsto per il contenitore sono limitate fino al ritorno della frequenza sotto il valore riservato per il contenitore.Applications that exceed the provisioned request unit rate for their container are limited until the rate drops below the provisioned level for the container. Se l'applicazione necessita di un livello superiore di velocità effettiva, sarà possibile aumentare la velocità effettiva eseguendo il provisioning di unità di richiesta aggiuntive.If your application requires a higher level of throughput, you can increase your throughput by provisioning additional request units.

    La complessità di una query influisce sulla quantità di unità richiesta utilizzate per un'operazione.The complexity of a query impacts how many Request Units are consumed for an operation. Il numero di predicati, la natura dei predicati, il numero di funzioni definite dall'utente e le dimensioni del set di dati di origine sono tutti fattori che incidono sul costo delle operazioni di query.The number of predicates, nature of the predicates, number of UDFs, and the size of the source data set all influence the cost of query operations.

    Per misurare l'overhead di qualunque operazione (create, update o delete), esaminare l'intestazione x-ms-request-charge (o la proprietà RequestCharge equivalente in ResourceResponse oppure FeedResponse in .NET SDK) per determinare il numero di unità richiesta usate da queste operazioni.To measure the overhead of any operation (create, update, or delete), inspect the x-ms-request-charge header (or the equivalent RequestCharge property in ResourceResponse or FeedResponse in the .NET SDK) to measure the number of request units consumed by these operations.

    // Measure the performance (request units) of writes
    ResourceResponse<Document> response = await client.CreateDocumentAsync(collectionSelfLink, myDocument);
    Console.WriteLine("Insert of document consumed {0} request units", response.RequestCharge);
    // Measure the performance (request units) of queries
    IDocumentQuery<dynamic> queryable = client.CreateDocumentQuery(collectionSelfLink, queryString).AsDocumentQuery();
    while (queryable.HasMoreResults)
         {
              FeedResponse<dynamic> queryResponse = await queryable.ExecuteNextAsync<dynamic>();
              Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
         }
    

    L'addebito richiesta restituito in questa intestazione è una frazione della velocità effettiva con provisioning, ad esempio 2000 UR/secondo.The request charge returned in this header is a fraction of your provisioned throughput (i.e., 2000 RUs / second). Se, ad esempio, la query precedente restituisce 1000 documenti da 1 KB, il costo dell'operazione è 1000.For example, if the preceding query returns 1000 1KB-documents, the cost of the operation is 1000. Entro un secondo, il server rispetterà quindi solo due richieste di questo tipo prima di limitare le richieste successive.As such, within one second, the server honors only two such requests before throttling subsequent requests. Per altre informazioni, vedere Unità richiesta e il calcolatore di unità richiesta.For more information, see Request units and the request unit calculator.

  2. Gestire la limitazione della frequenza o una frequenza di richieste troppo elevataHandle rate limiting/request rate too large

    Quando un client prova a superare la velocità effettiva riservata per un account, non si verifica alcun calo delle prestazioni del server e l'uso della capacità della velocità effettiva non supera il livello riservato.When a client attempts to exceed the reserved throughput for an account, there is no performance degradation at the server and no use of throughput capacity beyond the reserved level. Il server termina preventivamente la richiesta con RequestRateTooLarge (codice di stato HTTP 429) e restituisce l'intestazione x-ms-retry-after-ms, che indica la quantità di tempo, in millisecondi, che l'utente deve attendere prima di eseguire di nuovo la richiesta.The server will preemptively end the request with RequestRateTooLarge (HTTP status code 429) and return the x-ms-retry-after-ms header indicating the amount of time, in milliseconds, that the user must wait before reattempting the request.

     HTTP Status 429,
     Status Line: RequestRateTooLarge
     x-ms-retry-after-ms :100
    

    Tutti gli SDK intercettano implicitamente questa risposta, rispettano l'intestazione retry-after specificata dal server e ripetono la richiesta.The SDKs all implicitly catch this response, respect the server-specified retry-after header, and retry the request. A meno che all'account non accedano contemporaneamente più client, il tentativo successivo riuscirà.Unless your account is being accessed concurrently by multiple clients, the next retry will succeed.

    Se più client operano collettivamente in modo costante al di sopra della frequenza delle richieste, il numero di ripetizioni dei tentativi predefinito attualmente impostato su 9 internamente dal client potrebbe non essere sufficiente. In questo caso, il client genererà una DocumentClientException con codice di stato 429 per l'applicazione.If you have more than one client cumulatively operating consistently above the request rate, the default retry count currently set to 9 internally by the client may not suffice; in this case, the client throws a DocumentClientException with status code 429 to the application. Il numero di ripetizioni dei tentativi predefinito può essere modificato impostando RetryOptions nell'istanza di ConnectionPolicy.The default retry count can be changed by setting the RetryOptions on the ConnectionPolicy instance. Per impostazione predefinita, l'eccezione DocumentClientException con codice di stato 429 viene restituita dopo un tempo di attesa cumulativo di 30 secondi, se la richiesta continua a funzionare al di sopra della frequenza delle richieste.By default, the DocumentClientException with status code 429 is returned after a cumulative wait time of 30 seconds if the request continues to operate above the request rate. Ciò si verifica anche quando il numero di ripetizioni dei tentativi corrente è inferiore al numero massimo di tentativi, indipendentemente dal fatto che si tratti del valore predefinito 9 o di un valore definito dall'utente.This occurs even when the current retry count is less than the max retry count, be it the default of 9 or a user-defined value.

    Benché il comportamento automatizzato per la ripetizione dei tentativi consenta di migliorare la resilienza e l'usabilità per la maggior parte delle applicazioni, è possibile che provochi conflitti durante l'esecuzione dei benchmark delle prestazioni, in particolare durante la misurazione della latenza.While the automated retry behavior helps to improve resiliency and usability for the most applications, it might come at odds when doing performance benchmarks, especially when measuring latency. La latenza osservata dal client presenterà dei picchi se l'esperimento raggiunge il limite del server e fa in modo che l'SDK client ripeta automaticamente i tentativi.The client-observed latency will spike if the experiment hits the server throttle and causes the client SDK to silently retry. Per evitare i picchi di latenza durante gli esperimenti relativi alle prestazioni, misurare l'addebito restituito da ogni operazione e assicurarsi che le richieste operino al di sotto della frequenza delle richieste riservata.To avoid latency spikes during performance experiments, measure the charge returned by each operation and ensure that requests are operating below the reserved request rate. Per altre informazioni, vedere Unità richiesta.For more information, see Request units.

  3. Progettare documenti di dimensioni minori per ottenere una velocità effettiva maggioreDesign for smaller documents for higher throughput

    L'addebito per le richieste, ovvero il costo di elaborazione delle richieste, per un'operazione specifica è correlato direttamente alle dimensioni del documento.The request charge (i.e. request processing cost) of a given operation is directly correlated to the size of the document. Le operazioni sui documenti di grandi dimensioni sono più costose rispetto alle operazioni per i documenti di piccole dimensioni.Operations on large documents cost more than operations for small documents.

Passaggi successiviNext steps

Per un'applicazione di esempio usata per valutare Cosmos DB per scenari a prestazioni elevate su un numero ridotto di computer client, vedere Test delle prestazioni e della scalabilità con Azure Cosmos DB.For a sample application used to evaluate Cosmos DB for high-performance scenarios on a few client machines, see Performance and scale testing with Cosmos DB.

Per altre informazioni sulla progettazione dell'applicazione per scalabilità e prestazioni elevate, vedere l'articolo relativo a partizionamento e scalabilità in Azure Cosmos DB.Also, to learn more about designing your application for scale and high performance, see Partitioning and scaling in Azure Cosmos DB.