Ersetzen eines Angebots
Um eine gesamte Angebotsressource zu ersetzen, führen Sie einen PUT-Vorgang für die jeweilige Angebotsressource aus. Weitere Informationen zum maximalen und minimalen bereitgestellten Durchsatz, der für einen Container oder eine Datenbank festgelegt werden kann, finden Sie im Artikel Bereitstellen von Durchsatz für Container und Datenbanken .
Anforderung
| Methode | Anforderungs-URI | BESCHREIBUNG |
|---|---|---|
| PUT | https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} |
{databaseaccount} ist der Name des Azure Cosmos DB-Kontos, das Sie unter Ihrem Abonnement erstellt haben. Der Wert {_rid-offer} ist die vom System generierte Ressourcen-ID des Angebots. |
Tipp
Um die _rid des Angebots zu finden, das einer Datenbank oder Sammlung zugeordnet ist, rufen Sie zuerst die Datenbank oder GET die Auflistung ab , und notieren Sie sich die _rid Eigenschaft der Ressource. Fragen Sie dann die Angebote ab, um das _rid-Angebot zu finden, das dem _rid der Datenbank oder Sammlung entspricht. In der Regel hat eine Datenbank _rid länge 8, eine Sammlung _rid die Länge 12 und ein Angebot _rid länge 4.
Header
Siehe Allgemeine Azure Cosmos DB-REST-Anforderungsheader für Header, die von allen Cosmos DB-Anforderungen verwendet werden.
Body
| Eigenschaft | Erforderlich | BESCHREIBUNG |
|---|---|---|
| offerVersion | Erforderlich | Es kann V1 für die Legacyebenen S1, S2 und S3 und V2 für benutzerdefinierte Durchsatzstufen sein (empfohlen). |
| offerType | Optional | Diese Eigenschaft gilt nur in der V1-Angebotsversion. Legen Sie sie auf S1, S2 oder S3 für V1-Angebotstypen fest. Es ist ungültig für benutzerdefinierte Leistungsstufen oder ein bereitgestelltes durchsatzbasiertes Modell. |
| content | Erforderlich | Enthält Informationen zum Angebot: Bei V2-Angeboten enthält dieser Wert den Durchsatz der Sammlung. |
| resource | Erforderlich | Beim Erstellen einer neuen Auflistung wird diese Eigenschaft auf die Selbstverknüpfung der Auflistung festgelegt, z. B. dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Erforderlich | Während der Erstellung einer Auflistung wird diese Eigenschaft automatisch der Ressourcen-ID zugeordnet, d. h. _rid der Auflistung. Im obigen Beispiel lautet der _rid für die Auflistung pLJdAOlEdgA=. |
| id | Erforderlich | Es handelt sich um eine vom System generierte Eigenschaft. Die ID für die Angebotsressource wird automatisch generiert, wenn sie erstellt wird. Es hat den gleichen Wert wie die _rid für das Angebot. |
| _los | Erforderlich | Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch je nach Ressourcenstapel im Ressourcenmodell hierarchisch ist. Sie wird intern für die Platzierung und Navigation des Angebots verwendet. |
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L",
}
Antwort
Gibt die aktualisierte Angebotsressource zurück.
Header
Informationen zu Headern, die von allen Cosmos DB-Antworten zurückgegeben werden, finden Sie unter Allgemeine Azure Cosmos DB-REST-Antwortheader .
Statuscodes
In der folgenden Tabelle sind die allgemeinen Statuscodes aufgeführt, die von diesem Vorgang zurückgegeben werden. Eine vollständige Liste der status Codes finden Sie unter HTTP-Statuscodes.
| HTTP-Statuscode | BESCHREIBUNG |
|---|---|
| 200 – OK | Der Ersetzungsvorgang war erfolgreich. |
| 400 – Ungültige Anforderung | Der JSON-Text ist ungültig. Überprüfen Sie, ob geschweifte Klammern oder Anführungszeichen fehlen. |
| 401 – Nicht autorisiert | Der Authorization- oder x-ms-date-Header ist nicht festgelegt. "401 Unauthorized" wird auch zurückgegeben, wenn der Authorization-Header auf ein ungültiges Autorisierungstoken festgelegt ist. |
| 404 – Nicht gefunden | Das Angebot ist keine Ressource mehr, d. h. die Ressource wurde gelöscht. |
| 429 – Zu viele Anforderungen | Das Ersatzangebot wird gedrosselt, da der Vorgang zum Herunterskalieren des Angebots innerhalb des Leerlauftimeoutzeitraums (4 Stunden) versucht wird. Im Header "x-ms-retry-after-ms response" erfahren Sie, wie lange Sie warten sollten, bevor Sie diesen Vorgang wiederholen. |
Body
| Eigenschaft | BESCHREIBUNG |
|---|---|
| offerVersion | Dieser Wert kann V1 für vordefinierte Durchsatzstufen und V2 für benutzerdefinierte Durchsatzstufen sein. |
| offerType | Vordefinierte Leistungsstufen S1, S2 oder S3 für V1-Angebote. Ist für benutzerdefinierte Leistungsstufen auf Ungültig festgelegt. |
| content | Sie enthält Informationen zum Angebot. Bei V2-Angeboten enthält sie den Durchsatz der Auflistung. |
| resource | Beim Erstellen einer neuen Auflistung wird diese Eigenschaft auf die Selbstverknüpfung der Auflistung festgelegt, z. B. dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Während der Erstellung einer Auflistung wird diese Eigenschaft automatisch der Ressourcen-ID zugeordnet, d. h. _rid der Auflistung. Im obigen Beispiel lautet der _rid für die Auflistung pLJdAOlEdgA=. |
| id | Es handelt sich um eine vom System generierte Eigenschaft. Die ID für die Angebotsressource wird automatisch generiert, wenn sie erstellt wird. Es hat den gleichen Wert wie die _rid für das Angebot. |
| _los | Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch je nach Ressourcenstapel im Ressourcenmodell hierarchisch ist. Sie wird intern für die Platzierung und Navigation des Angebots verwendet. |
| _Ts | Es handelt sich um eine vom System generierte Eigenschaft. Sie gibt den zuletzt aktualisierten Zeitstempel der Ressource an. Der Wert ist ein Zeitstempel. |
| _Selbst | Es handelt sich um eine vom System generierte Eigenschaft. Es handelt sich um den eindeutigen, adressierbaren URI für die Ressource. |
| _Etag | Es handelt sich um eine vom System generierte Eigenschaft, die das Ressourcen-Etag angibt, das für die Kontrolle der optimistischen Parallelität erforderlich ist. |
{
"offerVersion": "V2",
"_rid": "uT2L",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_self": "offers/uT2L/"
}
Beispiel 1
In diesem Beispiel wird gezeigt, wie Sie den manuellen Durchsatz (RU/s) einer Auflistung auf 1.000 RU/s ändern.
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="
}
Im Folgenden finden Sie eine Beispielantwort.
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
}
Beispiel 2
In diesem Beispiel wird gezeigt, wie sie den maximalen Durchsatz (RU/s) eines Angebots mit Durchsatz der automatischen Skalierung auf 8000 RU/s ändern (Skalierungen zwischen 800 und 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"
}
Beispiel 3
In diesem Beispiel wird gezeigt, wie Sie ein Angebot mit manuellem Durchsatz migrieren, um den Durchsatz automatisch zu skalieren. Der Header x-ms-cosmos-migrate-offer-to-autopilot mit dem Wert true ist erforderlich.
Bei der Migration ermittelt Azure Cosmos DB automatisch die neue automatische Skalierung der maximalen RU/s basierend auf den aktuellen Ressourceneinstellungen. Die maxThroughput -Eigenschaft im Antwortobjekt stellt die vom System festgelegte standardeinstellung für die automatische Skalierung der maximalen RU/s dar.
Im Textkörper ist die content Eigenschaft mit einer definierten offerThroughput erforderlich, aber der Wert wird vom Dienst ignoriert. Im folgenden Beispiel wird -1 verwendet.
Nachdem die Änderung abgeschlossen ist, können Sie Beispiel 2 befolgen, um die automatische Skalierung der maximalen RU/s in einen benutzerdefinierten Wert zu ändern.
Erfahren Sie mehr über die Migration zur automatischen Skalierung.
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"
}
Im Folgenden finden Sie einen Beispielantworttext.
Die -Eigenschaft maxThroughput stellt die vom System festgelegte automatische Skalierung der maximalen RU/s dar. Die -Eigenschaft offerThroughput stellt die RU/s dar, auf die das System derzeit skaliert wird.
{
"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
}
Beispiel 4
In diesem Beispiel wird gezeigt, wie Ein Angebot mit automatisch skaliertem Durchsatz in einen manuellen Durchsatz migriert wird. Der Header x-ms-cosmos-migrate-offer-to-manual-throughput mit dem Wert true ist erforderlich.
Bei der Migration bestimmt Azure Cosmos DB automatisch den neuen manuellen Durchsatz (RU/s) basierend auf den aktuellen Ressourceneinstellungen. Nachdem die Änderung abgeschlossen ist, können Sie Beispiel 1 befolgen, um die manuellen RU/s in einen benutzerdefinierten Wert zu ändern.
Im Textkörper ist die content Eigenschaft mit einem definierten offerAutopilotSettings und maxThroughput erforderlich, aber der Wert wird vom Dienst ignoriert. Unten übergeben wir -1.
Erfahren Sie mehr über die Migration zum manuellen Durchsatz.
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"
}
Im Folgenden finden Sie einen Beispielantworttext. Die -Eigenschaft offerThroughput stellt den für die Ressource festgelegten manuellen Durchsatz (RU/s) dar.
{
"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
}
Hinweise
Wenn Sie den manuellen oder automatisch skalierte Durchsatz für eine Datenbank oder einen Container ändern, erzwingt das System Einschränkungen für die RU/s, die für die Ressource festgelegt werden können. Weitere Informationen zum minimalen und maximalen bereitgestellten Durchsatz (RU/s), der mit manuellem Durchsatz festgelegt werden kann, finden Sie im Artikel Bereitstellen von Durchsatz für Container und Datenbanken . Informationen zu den minimalen maximalen RU/s für die automatische Skalierung, die Sie festlegen können, finden Sie in den häufig gestellten Fragen zur automatischen Skalierung.
Führen Sie GET für die Angebotsressource aus, um den minimalen Durchsatz abzurufen, der für die Datenbank oder den Container festgelegt werden kann. Der Antwortheader x-ms-cosmos-min-throughput gibt den vom System ermittelten Mindestdurchsatz an. Dies stellt den Mindestwert dar, den Sie für die RU/s für eine Ressource mit manuellem Durchsatz festlegen können, oder den Minimalwert, den Sie für die automatische Skalierung der maximalen RU/s für eine Ressource mit automatischer Skalierung festlegen können.