Sostituire un'offerta
Per sostituire un'intera risorsa offerta, eseguire un'operazione PUT nella risorsa offerta specifica. Per altre informazioni sulla velocità effettiva massima e minima di provisioning che può essere impostata su un contenitore o su un database, vedere l'articolo Effettuare il provisioning della velocità effettiva nei contenitori e nei database .
Richiesta
| Metodo | URI richiesta | Descrizione |
|---|---|---|
| PUT | 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 la _rid dell'offerta associata a un database o a una raccolta, ottenere prima il database o GET la raccolta e prendere nota della proprietà _rid della risorsa. Eseguire quindi una query sulle offerte per trovare l'offerta di _rid corrispondente alla _rid del database o della raccolta. In genere, un database _rid è lunghezza 8, una raccolta _rid è lunghezza 12 e un'offerta _rid è lunghezza 4.
Intestazioni
Vedere Intestazioni di richiesta REST di Azure Cosmos DB comuni per le intestazioni usate da tutte le richieste di Cosmos DB
Corpo
| Proprietà | Obbligatoria | Descrizione |
|---|---|---|
| offerVersion | Necessario | Può essere V1 per i livelli S1, S2 e S3 legacy e V2 per i livelli di velocità effettiva definiti dall'utente (consigliato). |
| offerType | Facoltativo | 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 con provisioning. |
| content | Necessario | Contiene informazioni sull'offerta: per le offerte V2, questo valore contiene la velocità effettiva della raccolta. |
| resource | Necessario | Quando si crea una nuova raccolta, questa proprietà viene impostata sul collegamento automatico della raccolta, ad esempio dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Necessario | 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 | Necessario | È una proprietà generata dal sistema. L'ID per la risorsa offerta viene generato automaticamente quando viene creato. Ha lo stesso valore della _rid per l'offerta. |
| _rid | Necessario | È una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco che è anche gerarchico per ogni stack di risorse nel modello di risorsa. Viene usato internamente per il posizionamento e l'esplorazione 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 di Azure Cosmos DB comuni per le intestazioni restituite da tutte le risposte di Cosmos DB.
Codici di stato
La seguente tabella elenca 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 - OK | L'operazione di sostituzione è riuscita. |
| 400 - Richiesta non valida | Il corpo JSON non è valido. Controllare parentesi graffe o virgolette mancanti. |
| 401 - Non autorizzato | L'intestazione Authorization o x-ms-date non è impostata. Il codice 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 della scalabilità dell'offerta viene tentata entro il periodo di timeout inattivo, ovvero 4 ore. Fare riferimento all'intestazione "x-ms-retry-after-ms response" per vedere quanto tempo è necessario attendere prima di ripetere l'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. |
| offerType | Livelli di prestazioni predefiniti S1, S2 o S3 per le offerte V1. Impostato su Non valido per i livelli di prestazioni definiti dall'utente. |
| content | Contiene informazioni sull'offerta. Per le offerte V2, contiene la velocità effettiva della raccolta. |
| resource | 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 | È una proprietà generata dal sistema. L'ID per la risorsa offerta viene generato automaticamente quando viene creato. Ha lo stesso valore della _rid per l'offerta. |
| _rid | È una proprietà generata dal sistema. L'ID risorsa (_rid) è un identificatore univoco che è anche gerarchico per ogni stack di risorse nel modello di risorsa. Viene usato internamente per il posizionamento e l'esplorazione dell'offerta. |
| _Ts | È una proprietà generata dal sistema. Indica il timestamp dell'ultimo aggiornamento della risorsa. Il valore è un timestamp. |
| _stesso | Si tratta di una proprietà generata dal sistema. URI indirizzabile univoco per la risorsa. |
| _Etag | Si tratta di una proprietà generata dal sistema che specifica l'etag della risorsa necessaria 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
Questo esempio illustra 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="
}
Di seguito è riportata una risposta di esempio.
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/sec) di un'offerta con velocità effettiva con scalabilità automatica a 8000 UR/sec (scalabilità compresa tra 800 e 8000 UR/sec)
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 di 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 di scalabilità automatica predefinito impostato dal sistema.
Nel corpo la content proprietà con un definito offerThroughput è obbligatoria, ma il valore verrà ignorato dal servizio. Nell'esempio seguente viene usato -1.
Al termine della modifica, è possibile seguire l'esempio 2 per modificare il numero massimo di UR/sec di 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 corpo di risposta di esempio.
La proprietà maxThroughput rappresenta il numero massimo di UR/sec di scalabilità automatica impostato dal sistema. La proprietà offerThroughput rappresenta le UR/s su 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 con 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 oggetto definito offerAutopilotSettings ed maxThroughput è obbligatoria, ma il valore verrà ignorato dal servizio. Di seguito passiamo -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 corpo di risposta di esempio. La proprietà offerThroughput rappresenta la velocità effettiva manuale 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
}
Commenti
Quando si modifica la velocità effettiva manuale o di scalabilità automatica in un database o in un contenitore, il sistema applica vincoli alle UR/s che possono essere impostate sulla risorsa. Per altre informazioni sulla velocità effettiva minima e massima con provisioning (UR/sec) che può essere impostata con velocità effettiva manuale, vedere l'articolo Effettuare il provisioning della velocità effettiva nei contenitori e nei database . Per informazioni sul numero massimo di UR/sec di scalabilità automatica minima 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 la velocità effettiva minima determinata dal sistema. Questo rappresenta il valore minimo che è possibile impostare per le UR/sec in una risorsa con velocità effettiva manuale oppure il valore minimo che è possibile impostare per il numero massimo di UR/sec di scalabilità automatica in una risorsa con velocità effettiva di scalabilità automatica.