Zastępowanie oferty
Aby zastąpić cały zasób oferty, wykonaj operację PUT dla określonego zasobu oferty. Aby dowiedzieć się więcej o maksymalnej i minimalnej aprowizowanej przepływności, którą można ustawić w kontenerze lub bazie danych, zobacz artykuł Provision throughput on containers and databases (Aprowizowanie przepływności dla kontenerów i baz danych).
Żądanie
| Metoda | Identyfikator URI żądania | Opis |
|---|---|---|
| PUT | https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} |
{databaseaccount} to nazwa konta usługi Azure Cosmos DB utworzonego w ramach subskrypcji. Wartość {_rid-offer} to wygenerowany przez system identyfikator zasobu oferty. |
Porada
Aby znaleźć _rid oferty skojarzonej z bazą danych lub kolekcją, najpierw pobierz bazę danych lub POBIERZ kolekcję i zanotuj właściwość _rid zasobu. Następnie wykonaj zapytanie dotyczące ofert , aby znaleźć ofertę _rid odpowiadającą _rid bazy danych lub kolekcji. Zazwyczaj _rid bazy danych ma długość 8, _rid kolekcja ma długość 12, a _rid oferty wynosi 4.
Nagłówki
Zobacz Typowe nagłówki żądań REST usługi Azure Cosmos DB dla nagłówków używanych przez wszystkie żądania usługi Cosmos DB
Treść
| Właściwość | Wymagane | Opis |
|---|---|---|
| offerVersion | Wymagane | Może to być wersja 1 dla starszych poziomów S1, S2 i S3 oraz V2 dla poziomów przepływności zdefiniowanych przez użytkownika (zalecane). |
| offerType | Opcjonalne | Ta właściwość ma zastosowanie tylko w wersji oferty V1. Ustaw dla typów ofert S1, S2 lub S3 dla typów ofert w wersji 1. Jest on nieprawidłowy dla poziomów wydajności zdefiniowanych przez użytkownika lub modelu opartego na aprowizowanej przepływności. |
| Zawartości | Wymagane | Zawiera informacje o ofercie — w przypadku ofert w wersji 2 ta wartość zawiera przepływność kolekcji. |
| Zasobów | Wymagane | Podczas tworzenia nowej kolekcji ta właściwość jest ustawiana na link własny kolekcji, na przykład dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Wymagane | Podczas tworzenia kolekcji ta właściwość jest automatycznie skojarzona z identyfikatorem zasobu, czyli _rid kolekcji. W powyższym przykładzie _rid kolekcji to pLJdAOlEdgA=. |
| id | Wymagane | Jest to właściwość wygenerowana przez system. Identyfikator zasobu oferty jest generowany automatycznie podczas jego tworzenia. Ma tę samą wartość co _rid dla oferty. |
| _Rid | Wymagane | Jest to właściwość wygenerowana przez system. Identyfikator zasobu (_rid) jest unikatowym identyfikatorem, który jest również hierarchiczny dla stosu zasobów w modelu zasobów. Jest ona używana wewnętrznie do umieszczania i nawigacji oferty. |
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L",
}
Reakcja
Zwraca zaktualizowany zasób oferty.
Nagłówki
Zobacz Typowe nagłówki odpowiedzi REST usługi Azure Cosmos DB dla nagłówków zwracanych przez wszystkie odpowiedzi usługi Cosmos DB.
Kody stanu
W poniższej tabeli wymieniono typowe kody stanu zwracane przez tę operację. Aby uzyskać pełną listę kodów stanu, zobacz Kody stanu HTTP.
| Kod stanu HTTP | Opis |
|---|---|
| 200 OK | Operacja zamiany zakończyła się pomyślnie. |
| 400 Nieprawidłowe żądanie | Treść JSON jest nieprawidłowa. Sprawdź brak nawiasów klamrowych lub cudzysłowów. |
| 401 Brak autoryzacji | Nagłówek Authorization lub x-ms-date nie jest ustawiony. Błąd 401 jest również zwracany, gdy nagłówek autoryzacji jest ustawiony na nieprawidłowy token autoryzacji. |
| 404 — Nie znaleziono | Oferta nie jest już zasobem, czyli zasób został usunięty. |
| 429 Zbyt wiele żądań | Oferta zamiany jest ograniczana, ponieważ operacja skalowania oferty w dół jest podejmowana w okresie bezczynności, czyli 4 godziny. Zapoznaj się z nagłówkem "x-ms-retry-after-ms response", aby zobaczyć, jak długo należy czekać przed ponowieniu próby wykonania tej operacji. |
Treść
| Właściwość | Opis |
|---|---|
| offerVersion | Ta wartość może być w wersji 1 dla wstępnie zdefiniowanych poziomów przepływności i wersji 2 dla poziomów przepływności zdefiniowanej przez użytkownika. |
| offerType | Wstępnie zdefiniowane poziomy wydajności S1, S2 lub S3 dla ofert w wersji 1. Ustawiono wartość Nieprawidłowa dla poziomów wydajności zdefiniowanych przez użytkownika. |
| Zawartości | Zawiera informacje o ofercie. W przypadku ofert w wersji 2 zawiera ona przepływność kolekcji. |
| Zasobów | Podczas tworzenia nowej kolekcji ta właściwość jest ustawiana na link własny kolekcji, na przykład dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Podczas tworzenia kolekcji ta właściwość jest automatycznie skojarzona z identyfikatorem zasobu, czyli _rid kolekcji. W powyższym przykładzie _rid kolekcji to pLJdAOlEdgA=. |
| id | Jest to właściwość wygenerowana przez system. Identyfikator zasobu oferty jest generowany automatycznie podczas jego tworzenia. Ma tę samą wartość co _rid dla oferty. |
| _Rid | Jest to właściwość wygenerowana przez system. Identyfikator zasobu (_rid) jest unikatowym identyfikatorem, który jest również hierarchiczny dla stosu zasobów w modelu zasobów. Jest ona używana wewnętrznie do umieszczania i nawigacji oferty. |
| _Ts | Jest to właściwość wygenerowana przez system. Określa ostatni zaktualizowany znacznik czasu zasobu. Wartość jest znacznikiem czasu. |
| _Własny | Jest to właściwość wygenerowana przez system. Jest to unikatowy adresowy identyfikator URI zasobu. |
| _Etag | Jest to właściwość wygenerowana przez system, która określa tag zasobu wymagany do optymistycznej kontroli współbieżności. |
{
"offerVersion": "V2",
"_rid": "uT2L",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_self": "offers/uT2L/"
}
Przykład 1
W tym przykładzie pokazano, jak zmienić przepływność ręczną (RU/s) kolekcji na 1000 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="
}
Poniżej znajduje się przykładowa odpowiedź.
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
}
Przykład 2
W tym przykładzie pokazano, jak zmienić maksymalną przepływność (RU/s) oferty z przepływnością autoskalowania na 8000 RU/s (skalowanie z zakresu od 800 do 8000 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"
}
Przykład 3
W tym przykładzie pokazano, jak przeprowadzić migrację oferty z przepływnością ręczną do przepływności autoskalowania. Nagłówek x-ms-cosmos-migrate-offer-to-autopilot z wartością true jest wymagany.
Podczas migracji usługa Azure Cosmos DB automatycznie określa nową maksymalną wartość RU/s autoskalowania na podstawie bieżących ustawień zasobów. Właściwość maxThroughput w obiekcie odpowiedzi reprezentuje domyślną maksymalną wartość RU/s autoskalowanie ustawioną przez system.
W treści content właściwość z zdefiniowaną wartością offerThroughput jest wymagana, ale wartość zostanie zignorowana przez usługę. W poniższym przykładzie użyto -1.
Po zakończeniu zmiany możesz skorzystać z przykładu 2 , aby zmienić maksymalną wartość RU/s autoskalowania na wartość niestandardową.
Dowiedz się więcej o migracji do autoskalowania.
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"
}
Poniżej znajduje się przykładowa treść odpowiedzi.
Właściwość maxThroughput reprezentuje maksymalną wartość RU/s autoskalowanie ustawioną przez system. Właściwość offerThroughput reprezentuje ru/s, do których system jest obecnie skalowany.
{
"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
}
Przykład 4
W tym przykładzie pokazano, jak przeprowadzić migrację oferty z przepływnością autoskalowania do przepływności ręcznej. Nagłówek x-ms-cosmos-migrate-offer-to-manual-throughput z wartością true jest wymagany.
Podczas migracji usługa Azure Cosmos DB automatycznie określa nową przepływność ręczną (RU/s) na podstawie bieżących ustawień zasobów. Po zakończeniu zmiany możesz skorzystać z przykładu 1 , aby zmienić ręczną wartość RU/s na niestandardową.
W treści content właściwość ze zdefiniowaną wartością offerAutopilotSettings i maxThroughput jest wymagana, ale wartość zostanie zignorowana przez usługę. Poniżej przekazujemy wartość -1.
Dowiedz się więcej o migracji do przepływności ręcznej.
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"
}
Poniżej znajduje się przykładowa treść odpowiedzi. Właściwość offerThroughput reprezentuje przepływność ręczną (RU/s) ustawioną na zasobie.
{
"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
}
Uwagi
W przypadku zmiany przepływności ręcznego lub automatycznego skalowania w bazie danych lub kontenerze system wymusza ograniczenia dotyczące jednostek RU/s, które można ustawić w zasobie. Aby dowiedzieć się więcej na temat minimalnej i maksymalnej aprowizowanej przepływności (RU/s), które można ustawić przy użyciu przepływności ręcznej, zobacz artykuł Provision throughput on containers and databases (Aprowizowanie przepływności dla kontenerów i baz danych). Aby dowiedzieć się więcej na temat minimalnej maksymalnej liczby jednostek RU/s autoskalowania, które można ustawić, zobacz często zadawane pytania dotyczące autoskalowania.
Aby pobrać minimalną przepływność, którą można ustawić w bazie danych lub kontenerze, wykonaj operację GET dla zasobu oferty. Nagłówek x-ms-cosmos-min-throughput odpowiedzi określa minimalną przepływność w systemie. Reprezentuje wartość minimalną, którą można ustawić dla jednostek RU/s w zasobie z ręczną przepływnością, lub minimalną wartość, którą można ustawić dla maksymalnej wartości RU/s autoskalowania dla zasobu z przepływnością autoskalowania.