Ersätta ett erbjudande

  • Artikel

Om du vill ersätta en hel erbjudanderesurs utför du en PUT-åtgärd på den specifika erbjudanderesursen. Mer information om det högsta och lägsta etablerade dataflödet som kan anges för en container eller en databas finns i artikeln Etablera dataflöde för containrar och databaser .

Förfrågan

Metod URI för förfrågan Description
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount} är namnet på det Azure Cosmos DB-konto som du skapade under din prenumeration. Värdet {_rid-offer} är det systemgenererade resurs-ID:t för erbjudandet.

Tips

Om du vill hitta _rid för erbjudandet som är associerat med en databas eller samling måste du först HÄMTA databasen eller HÄMTA samlingen och anteckna resursens _rid-egenskap. Fråga sedan erbjudandena för att hitta det _rid erbjudande som motsvarar databasens eller samlingens _rid. Vanligtvis är en databas _rid längd 8, en samling _rid är längd 12 och ett erbjudande _rid är längd 4.

Sidhuvuden

Se Vanliga REST-begärandehuvuden för Azure Cosmos DB för rubriker som används av alla Cosmos DB-begäranden

Brödtext

Egenskap Krävs Beskrivning
offerVersion Obligatorisk Det kan vara V1 för de äldre nivåerna S1, S2 och S3 och V2 för användardefinierade dataflödesnivåer (rekommenderas).
offerType Valfritt Den här egenskapen gäller endast i V1-erbjudandeversionen. Ställ in den på S1, S2 eller S3 för V1-erbjudandetyper. Den är ogiltig för användardefinierade prestandanivåer eller etablerad dataflödesbaserad modell.
Innehåll Obligatorisk Innehåller information om erbjudandet – för V2-erbjudanden innehåller det här värdet samlingens dataflöde.
Resurs Obligatorisk När du skapar en ny samling anges den här egenskapen till samlingens självlänk, till exempel dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Obligatorisk När en samling skapas associeras den här egenskapen automatiskt till resurs-ID: t, det vill _rid av samlingen. I exemplet ovan är _rid för samlingen pLJdAOlEdgA=.
id Obligatorisk Det är en systemgenererad egenskap. ID:t för erbjudanderesursen genereras automatiskt när den skapas. Det har samma värde som _rid för erbjudandet.
_Bli Obligatorisk Det är en systemgenererad egenskap. Resurs-ID :t (_rid) är en unik identifierare som också är hierarkisk per resursstacken i resursmodellen. Det används internt för placering och navigering av erbjudandet. 
{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": 4000   
  },   
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",   
  "offerResourceId": "rgkVAMHcJww=",   
  "id": "uT2L",   
  "_rid": "uT2L",   
}

Svarsåtgärder

Returnerar den uppdaterade erbjudanderesursen.

Sidhuvuden

Se Vanliga REST-svarshuvuden för Azure Cosmos DB för rubriker som returneras av alla Cosmos DB-svar.

Statuskoder

I följande tabell visas vanliga statuskoder som returneras av den här åtgärden. En fullständig lista över statuskoder finns i HTTP-statuskoder.

HTTP-statuskod Beskrivning
200 OK Ersättningsåtgärden lyckades.
400 Felaktig begäran JSON-brödtexten är ogiltig. Sök efter saknade klammerparenteser eller citattecken.
401 – Ej behörig Rubriken Authorization (Auktorisering) eller x-ms-date (x-ms-date) har inte angetts. 401 returneras också när auktoriseringshuvudet är inställt på en ogiltig auktoriseringstoken.
404 – Hittades inte Erbjudandet är inte längre en resurs, det vill sa att resursen har tagits bort.
429 För många förfrågningar Ersättningserbjudandet begränsas eftersom åtgärden för nedskalning av erbjudandet görs inom tidsgränsen för inaktivitet, dvs. 4 timmar. Se rubriken "x-ms-retry-after-ms response" för att se hur länge du bör vänta innan du försöker utföra åtgärden igen.

Brödtext

Egenskap Beskrivning
offerVersion Det här värdet kan vara V1 för fördefinierade dataflödesnivåer och V2 för användardefinierade dataflödesnivåer.
offerType Fördefinierade prestandanivåer S1, S2 eller S3 för V1-erbjudanden. Värdet är Ogiltigt för användardefinierade prestandanivåer.
Innehåll Den innehåller information om erbjudandet. För V2-erbjudanden innehåller den dataflödet för samlingen.
Resurs När du skapar en ny samling anges den här egenskapen till samlingens självlänk, till exempel dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId När en samling skapas associeras den här egenskapen automatiskt till resurs-ID: t, det vill _rid av samlingen. I exemplet ovan är _rid för samlingen pLJdAOlEdgA=.
id Det är en systemgenererad egenskap. ID:t för erbjudanderesursen genereras automatiskt när den skapas. Det har samma värde som _rid för erbjudandet.
_Bli Det är en systemgenererad egenskap. Resurs-ID :t (_rid) är en unik identifierare som också är hierarkisk per resursstacken i resursmodellen. Det används internt för placering och navigering av erbjudandet.
_Ts Det är en systemgenererad egenskap. Den anger den senast uppdaterade tidsstämpeln för resursen. Värdet är en tidsstämpel.
_Själv Det är en systemgenererad egenskap. Det är den unika adresserbara URI:n för resursen.
_Etag Det är en systemgenererad egenskap som anger resursetaggen som krävs för optimistisk samtidighetskontroll. 
{  
  "offerVersion": "V2",  
  "_rid": "uT2L",
   "content": {  
    "offerThroughput": 4000
  }, 
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/"
}

Exempel 1

Det här exemplet visar hur du ändrar det manuella dataflödet (RU/s) för en samling till 1 000 RU/s.

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="  
}

Nedan visas ett exempelsvar.

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  
}

Exempel 2

Det här exemplet visar hur du ändrar det maximala dataflödet (RU/s) för ett erbjudande med dataflöde för automatisk skalning till 8 000 RU/s (skalar mellan 800 och 8 000 RU/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"
}

Exempel 3

Det här exemplet visar hur du migrerar ett erbjudande med manuellt dataflöde för automatisk skalning av dataflöde. x-ms-cosmos-migrate-offer-to-autopilot Huvudet med värdet true krävs.

Vid migrering avgör Azure Cosmos DB automatiskt det nya maxantalet RU/s för autoskalning baserat på de aktuella resursinställningarna. Egenskapen maxThroughput i svarsobjektet representerar standardvärdet för maximalt antal RU/s för autoskalning som angetts av systemet.

I brödtexten krävs egenskapen content med en definierad offerThroughput , men värdet ignoreras av tjänsten. I följande exempel används -1.

När ändringen är klar kan du följa exempel 2 för att ändra max RU/s för autoskalning till ett anpassat värde.

Läs mer om att migrera till autoskalning.

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"
}

Nedan visas ett exempel på svarstext.

Egenskapen maxThroughput representerar max RU/s för autoskalning som angetts av systemet. Egenskapen offerThroughput representerar de RU/s som systemet för närvarande skalas till.

{
    "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
}

Exempel 4

Det här exemplet visar hur du migrerar ett erbjudande med dataflöde för automatisk skalning till manuellt dataflöde. x-ms-cosmos-migrate-offer-to-manual-throughput Huvudet med värdet true krävs.

Vid migrering avgör Azure Cosmos DB automatiskt det nya manuella dataflödet (RU/s) baserat på de aktuella resursinställningarna. När ändringen är klar kan du följa exempel 1 för att ändra manuella RU/s till ett anpassat värde.

I brödtexten content är egenskapen med en definierad offerAutopilotSettings och maxThroughput obligatorisk, men värdet ignoreras av tjänsten. Under skickar vi in -1.

Läs mer om att migrera till manuellt dataflöde.

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"
}

Nedan visas ett exempel på svarstext. Egenskapen offerThroughput representerar det manuella dataflöde (RU/s) som angetts för resursen.

{
    "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
}

Kommentarer

När du ändrar det manuella dataflödet eller autoskalningsdataflödet för en databas eller container tillämpar systemet begränsningar för de RU/s som kan ställas in för resursen. Mer information om det lägsta och högsta etablerade dataflödet (RU/s) som kan anges med manuellt dataflöde finns i artikeln Etablera dataflöde för containrar och databaser . Mer information om det minsta antalet RU/s för autoskalning som du kan ange finns i vanliga frågor och svar om autoskalning.

Om du vill hämta det minsta dataflöde som kan anges för databasen eller containern utför du GET på erbjudanderesursen. Svarshuvudet x-ms-cosmos-min-throughput anger systemets minsta dataflöde. Detta representerar det minsta värde som du kan ange för RU/s för en resurs med manuellt dataflöde, eller det minsta värde som du kan ange för autoskalning av max RU/s för en resurs med dataflöde för automatisk skalning.

Se även