Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Per sostituire un'intera risorsa dell'offerta, eseguire un'operazione PUT sulla risorsa dell'offerta specifica. Per altre informazioni sulla velocità effettiva massima e minima con provisioning che può essere impostata in un contenitore o in un database, vedere l'articolo Effettuare il provisioning della velocità effettiva in contenitori e database .
Richiesta
| Metodo | URI della richiesta | Descrizione |
|---|---|---|
| INSERIRE | https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} |
{databaseaccount} è il nome dell'account Azure Cosmos DB creato nella sottoscrizione. Il valore {_rid-offer} è l'ID risorsa generato dal sistema dell'offerta. |
Suggerimento
Per trovare il _rid dell'offerta associata a un database o a una raccolta, eseguire prima le istruzioni GET per il database o per la raccolta e prendere nota della proprietà _rid della risorsa. Quindi, interroga le offerte per trovare la _rid-offerta che corrisponde al database o alla _rid della raccolta. In genere, un _rid di database è di lunghezza 8, un _rid di raccolta è di lunghezza 12 e un _rid di offerta è di lunghezza 4.
Intestazioni
Vedere Intestazioni comuni delle richieste REST di Azure Cosmos DB per le intestazioni usate da tutte le richieste di Cosmos DB
Corpo
| Proprietà | Obbligatorio | Descrizione |
|---|---|---|
| offerVersion | Obbligatorio | Può essere V1 per i livelli legacy S1, S2 e S3 e V2 per i livelli di velocità effettiva definiti dall'utente (scelta consigliata). |
| Tipo di offerta | Opzionale | Questa proprietà è applicabile solo nella versione dell'offerta V1. Impostarlo su S1, S2 o S3 per i tipi di offerta V1. Non è valido per i livelli di prestazioni definiti dall'utente o per il modello basato sulla velocità effettiva di cui è stato effettuato il provisioning. |
| contenuto | Obbligatorio | Contiene informazioni sull'offerta: per le offerte V2, questo valore contiene la velocità effettiva della raccolta. |
| risorsa | Obbligatorio | Quando si crea una nuova raccolta, questa proprietà viene impostata sul collegamento automatico della raccolta, ad esempio dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Obbligatorio | Durante la creazione di una raccolta, questa proprietà viene associata automaticamente all'ID risorsa, ovvero _rid della raccolta. Nell'esempio precedente, il _rid per la raccolta è pLJdAOlEdgA=. |
| ID | Obbligatorio | Si tratta di una proprietà generata dal sistema. L'ID per la risorsa dell'offerta viene generato automaticamente al momento della creazione. Ha lo stesso valore dell '_rid per l'offerta. |
| _liberarsi | Obbligatorio | Si tratta di una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco che è anche gerarchico per ogni stack di risorse nel modello di risorse. Viene utilizzato internamente per il posizionamento e la navigazione dell'offerta. |
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L",
}
Risposta
Restituisce la risorsa dell'offerta aggiornata.
Intestazioni
Vedere Intestazioni di risposta REST comuni di Azure Cosmos DB per le intestazioni restituite da tutte le risposte di Cosmos DB.
Codici di stato
Nella tabella seguente sono elencati i codici di stato comuni restituiti da questa operazione. Per un elenco completo dei codici di stato, vedere Codici di stato HTTP.
| Codice di stato HTTP | Descrizione |
|---|---|
| 200 Va bene | L'operazione di sostituzione è riuscita. |
| 400 Richiesta non valida | Il corpo JSON non è valido. Controllare le parentesi graffe o le virgolette mancanti. |
| 401 - Non autorizzato | L'intestazione Authorization o x-ms-date non è impostata. 401 viene restituito anche quando l'intestazione Authorization è impostata su un token di autorizzazione non valido. |
| 404 Non trovato | L'offerta non è più una risorsa, ovvero la risorsa è stata eliminata. |
| 429 - Numero eccessivo di richieste | L'offerta di sostituzione è limitata perché l'operazione di riduzione dell'offerta viene tentata entro il periodo di timeout di inattività, ovvero 4 ore. Fare riferimento all'intestazione "x-ms-retry-after-ms response" per verificare quanto tempo è necessario attendere prima di ritentare questa operazione. |
Corpo
| Proprietà | Descrizione |
|---|---|
| offerVersion | Questo valore può essere V1 per i livelli di velocità effettiva predefiniti e V2 per i livelli di velocità effettiva definiti dall'utente. |
| Tipo di offerta | Livelli di prestazioni predefiniti S1, S2 o S3 per le offerte V1. È impostato su Non valido per i livelli di prestazioni definiti dall'utente. |
| contenuto | Contiene informazioni sull'offerta. Per le offerte V2, contiene la velocità effettiva della raccolta. |
| risorsa | Quando si crea una nuova raccolta, questa proprietà viene impostata sul collegamento automatico della raccolta, ad esempio dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Durante la creazione di una raccolta, questa proprietà viene associata automaticamente all'ID risorsa, ovvero _rid della raccolta. Nell'esempio precedente, il _rid per la raccolta è pLJdAOlEdgA=. |
| ID | Si tratta di una proprietà generata dal sistema. L'ID per la risorsa dell'offerta viene generato automaticamente al momento della creazione. Ha lo stesso valore dell '_rid per l'offerta. |
| _liberarsi | Si tratta di una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco che è anche gerarchico per ogni stack di risorse nel modello di risorse. Viene utilizzato internamente per il posizionamento e la navigazione dell'offerta. |
| _Ts | Si tratta di una proprietà generata dal sistema. Specifica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp. |
| _stesso | Si tratta di una proprietà generata dal sistema. È l'URI indirizzabile univoco per la risorsa. |
| _etag | Si tratta di una proprietà generata dal sistema che specifica l'etag della risorsa necessario per il controllo della concorrenza ottimistica. |
{
"offerVersion": "V2",
"_rid": "uT2L",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_self": "offers/uT2L/"
}
Esempio 1
In questo esempio viene illustrato come modificare la velocità effettiva manuale (UR/sec) di una raccolta a 1000 UR/sec.
PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1
x-ms-date: Tue, 29 Mar 2016 17:50:18 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d
Cache-Control: no-cache
User-Agent: contoso/1.0
x-ms-version: 2015-12-16
Accept: application/json
Host: querydemo.documents.azure.com
Content-Length: 234
Expect: 100-continue
{
"id": "uT2L",
"_rid": "uT2L",
"_self": "offers/uT2L/",
"offerVersion": "V2",
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"content": {
"offerThroughput": 1000
},
"offerResourceId": "rgkVAMHcJww="
}
Ecco un esempio di risposta.
HTTP/1.1 200 Ok
Cache-Control: no-store, no-cache
Pragma: no-cache
Transfer-Encoding: chunked
Content-Type: application/json
Content-Location: https://querydemo.documents.azure.com/offers/uT2L
Server: Microsoft-HTTPAPI/2.0
Strict-Transport-Security: max-age=31536000
x-ms-last-state-change-utc: Fri, 25 Mar 2016 22:54:09.213 GMT
etag: "0000a900-0000-0000-0000-56fac05a0000"
x-ms-schemaversion: 1.1
x-ms-quorum-acked-lsn: 8110
x-ms-current-write-quorum: 3
x-ms-current-replica-set-size: 4
x-ms-request-charge: 9.9
x-ms-serviceversion: version=1.6.52.5
x-ms-activity-id: fa543c39-a64e-44bd-ba9a-c4f313a9d7d4
x-ms-session-token: M:8111
x-ms-gatewayversion: version=1.6.52.5
Date: Tue, 29 Mar 2016 17:50:20 GMT
{
"offerVersion": "V2",
"_rid": "uT2L",
"content": {
"offerThroughput": 1000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_self": "offers/uT2L/",
"_etag": "\"0000a900-0000-0000-0000-56fac05a0000\"",
"_ts": 1459273818
}
Esempio 2
Questo esempio illustra come modificare la velocità effettiva massima (UR/s) di un'offerta con scalabilità automatica a 8000 UR/s (scalabilità compresa tra 800 e 8000 UR/s)
PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1
x-ms-version: 2018-12-31
x-ms-date: Thu, 23 Jul 2020 00:04:41 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d
Accept: application/json
Content-Type: application/json
User-Agent: contoso/1.0
Host: querydemo.documents.azure.com:443
Connection: keep-alive
Content-Length: 278
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerAutopilotSettings": {"maxThroughput": 8000}
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww="
"id": "uT2L",
"_rid": "uT2L"
}
Esempio 3
Questo esempio illustra come eseguire la migrazione di un'offerta con velocità effettiva manuale alla velocità effettiva con scalabilità automatica. L'intestazione x-ms-cosmos-migrate-offer-to-autopilot con valore true è obbligatoria.
Durante la migrazione, Azure Cosmos DB determina automaticamente il nuovo numero massimo di UR/sec di scalabilità automatica in base alle impostazioni correnti delle risorse. La maxThroughput proprietà nell'oggetto risposta rappresenta il numero massimo di UR/sec predefinito per la scalabilità automatica impostato dal sistema.
Nel corpo, la content proprietà con un definito offerThroughput è obbligatoria, ma il valore verrà ignorato dal servizio. Nell'esempio seguente viene utilizzato -1.
Al termine della modifica, è possibile seguire l'esempio 2 per modificare il numero massimo di UR/sec della scalabilità automatica in un valore personalizzato.
Altre informazioni sulla migrazione alla scalabilità automatica.
PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1
x-ms-version: 2018-12-31
x-ms-date: Wed, 22 Jul 2020 23:33:41 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d
Accept: application/json
x-ms-cosmos-migrate-offer-to-autopilot: true
Content-Type: application/json
User-Agent: contoso/1.0
Host: querydemo.documents.azure.com
Connection: keep-alive
Content-Length: 254
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerThroughput": -1
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L"
}
Di seguito è riportato un esempio di corpo della risposta.
La proprietà maxThroughput rappresenta il numero massimo di UR/sec della scalabilità automatica impostato dal sistema. La proprietà offerThroughput rappresenta le UR/sec a cui il sistema è attualmente ridimensionato.
{
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerType": "Invalid",
"offerResourceId": "rgkVAMHcJww=",
"offerVersion": "V2",
"content": {
"offerThroughput": 400,
"offerIsRUPerMinuteThroughputEnabled": false,
"offerMinimumThroughputParameters": {
"maxThroughputEverProvisioned": 4000,
"maxConsumedStorageEverInKB": 0
},
"offerLastReplaceTimestamp": 1595460122,
"offerAutopilotSettings": {
"maxThroughput": 4000
}
},
"id": "uT2L",
"_rid": "uT2L",
"_self": "offers/uT2L/",
"_etag": "\"2d002059-0000-0800-0000-5f18cbf80000\"",
"_ts": 1595460600
}
Esempio 4
Questo esempio illustra come eseguire la migrazione di un'offerta con velocità effettiva di scalabilità automatica alla velocità effettiva manuale. L'intestazione x-ms-cosmos-migrate-offer-to-manual-throughput con valore true è obbligatoria.
Durante la migrazione, Azure Cosmos DB determina automaticamente la nuova velocità effettiva manuale (UR/sec) in base alle impostazioni correnti delle risorse. Al termine della modifica, è possibile seguire l'esempio 1 per modificare le UR/sec manuali in un valore personalizzato.
Nel corpo, la content proprietà con un and maxThroughput definito offerAutopilotSettings è obbligatorio, ma il valore verrà ignorato dal servizio. Qui passiamo in -1.
Altre informazioni sulla migrazione alla velocità effettiva manuale.
PUT https://querydemo.documents.azure.com/offers/uT2L HTTP/1.1
x-ms-version: 2018-12-31
x-ms-date: Wed, 22 Jul 2020 23:43:03 GMT
authorization: type%3dmaster%26ver%3d1.0%26sig%3dRdNwi9H3molMOsEoHXCUHa56N8U5eFDlfuewcSoiHgc%3d
Accept: application/json
x-ms-cosmos-migrate-offer-to-manual-throughput: true
Content-Type: application/json
User-Agent: contoso/1.0
Host: querydemo.documents.azure.com
Connection: keep-alive
Content-Length: 280
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerAutopilotSettings": {"maxThroughput": -1}
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L"
}
Di seguito è riportato un esempio di corpo della risposta. La proprietà offerThroughput rappresenta la velocità effettiva manuale (UR/sec) impostata sulla risorsa.
{
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerType": "Invalid",
"offerResourceId": "rgkVAMHcJww=",
"offerVersion": "V2",
"content": {
"offerThroughput": 4000,
"offerIsRUPerMinuteThroughputEnabled": false,
"offerMinimumThroughputParameters": {
"maxThroughputEverProvisioned": 4000,
"maxConsumedStorageEverInKB": 0
},
"offerLastReplaceTimestamp": 1595461384
},
"id": "uT2L",
"_rid": "uT2L",
"_self": "offers/uT2L/",
"_etag": "\"2d002359-0000-0800-0000-5f18cf080000\"",
"_ts": 1595461384
}
Osservazioni:
Quando si modifica la velocità effettiva manuale o di scalabilità automatica in un database o in un contenitore, il sistema applica vincoli alle UR/sec che possono essere impostate sulla risorsa. Per altre informazioni sulla velocità effettiva con provisioning minima e massima che può essere impostata con la velocità effettiva manuale, vedere l'articolo Effettuare il provisioning della velocità effettiva in contenitori e database . Per informazioni sul numero massimo di UR/sec minimo per la scalabilità automatica che è possibile impostare, vedere le domande frequenti sulla scalabilità automatica.
Per recuperare la velocità effettiva minima che può essere impostata nel database o nel contenitore, eseguire GET sulla risorsa dell'offerta. L'intestazione x-ms-cosmos-min-throughput della risposta indica il throughput minimo determinato dal sistema. Questo rappresenta il valore minimo che è possibile impostare per le UR/sec in una risorsa con velocità effettiva manuale o il valore minimo che è possibile impostare per la scalabilità automatica max UR/s in una risorsa con velocità effettiva con scalabilità automatica.