Ersetzen eines Angebots

Um eine gesamte Angebotsressource zu ersetzen, führen Sie einen PUT-Vorgang für die spezifische 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 zum Bereitstellen des Bereitstellungsdurchsatzes 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 Auflistung zugeordnet ist, rufen Sie zuerst die Datenbank oder get die Auflistung ab, und notieren Sie die _rid Eigenschaft der Ressource. Fragen Sie dann die Angebote ab, um das _rid-Angebot zu finden, das den _rid der Datenbank oder Auflistung entspricht. Normalerweise ist eine Datenbank _rid Länge 8, eine Sammlung _rid länge 12, und ein Angebot _rid ist 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 älteren S1-, S2- und S3-Ebenen und V2 für benutzerdefinierte Durchsatzebenen sein (empfohlen).
offerType Optional Diese Eigenschaft gilt nur in der V1-Angebotsversion. Legen Sie ihn auf S1, S2 oder S3 für V1-Angebotstypen fest. Es ist ungültig für benutzerdefinierte Leistungsstufen oder bereitgestelltes Durchsatzbasiertes Modell.
content Erforderlich Enthält Informationen zum Angebot – für V2-Angebote 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, also _rid der Auflistung. Im obigen Beispiel ist die _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 denselben Wert wie die _rid für das Angebot.
_rid Erforderlich Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch hierarchisch pro Ressourcenstapel im Ressourcenmodell 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

Siehe Allgemeine Azure Cosmos DB REST-Antwortheader für Header, die von allen Cosmos DB-Antworten zurückgegeben werden.

Statuscodes

In der folgenden Tabelle sind die allgemeinen Statuscodes aufgeführt, die von diesem Vorgang zurückgegeben werden. Eine vollständige Liste der Statuscodes 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, also die Ressource wurde gelöscht.
429 – Zu viele Anforderungen Das Ersatzangebot wird gedrosselt, da der Angebotskalierungsvorgang innerhalb des Leerlaufzeitraums versucht wird, also 4 Stunden. Lesen Sie den Header "x-ms-retry-after-ms", um zu sehen, wie lange Sie warten sollten, bevor Sie diesen Vorgang wiederholen.

Body

Eigenschaft BESCHREIBUNG
offerVersion Dieser Wert kann V1 für vordefinierte Durchsatzebenen und V2 für benutzerdefinierte Durchsatzebenen sein.
offerType Vordefinierte Leistungsstufen S1, S2 oder S3 für V1-Angebote. Der Wert ist für benutzerdefinierte Leistungsstufen auf "Ungültig" festgelegt.
content Es enthält Informationen zum Angebot. Für V2-Angebote enthält sie den Durchsatz der Sammlung.
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, also _rid der Auflistung. Im obigen Beispiel ist die _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 denselben Wert wie die _rid für das Angebot.
_rid Es handelt sich um eine vom System generierte Eigenschaft. Die Ressourcen-ID (_rid) ist ein eindeutiger Bezeichner, der auch hierarchisch pro Ressourcenstapel im Ressourcenmodell 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.
_self Es handelt sich um eine systemgenerierte Eigenschaft. Es handelt sich um den eindeutigen, adressierbaren URI für die Ressource.
_etag Es handelt sich um eine systemgenerierte Eigenschaft, die das Ressourcen-Etag angibt, das für die optimistische Übereinstimmungssteuerung 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 1000 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="  
}  
  

Nachfolgend 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 automatischem Durchsatz 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 zum automatischen Durchsatz migrieren. Der Header x-ms-cosmos-migrate-offer-to-autopilot mit Wert true ist erforderlich.

Bei der Migration bestimmt Azure Cosmos DB automatisch die neue automatische Skalierung max RU/s basierend auf den aktuellen Ressourceneinstellungen. Die maxThroughput Eigenschaft im Antwortobjekt stellt die standardmäßige automatische Skalierung max RU/s dar, die vom System festgelegt wird.

Im Textkörper ist die content Eigenschaft mit einer definierten offerThroughput Eigenschaft erforderlich, der Wert wird jedoch vom Dienst ignoriert. Im folgenden Beispiel wird -1 verwendet.

Nachdem die Änderung abgeschlossen ist, können Sie beispiel 2 folgen, um die automatische Skalierung max 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"
}

Unten finden Sie einen Beispielantworttext.

Die Eigenschaft maxThroughput stellt die vom System festgelegte automatische Skalierung max 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 Sie ein Angebot mit automatischem Durchsatz zu manuellem Durchsatz migrieren. Der Header x-ms-cosmos-migrate-offer-to-manual-throughput mit 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 folgen, um das manuelle RU/s in einen benutzerdefinierten Wert zu ändern.

Im Textkörper wird die Eigenschaft mit einer definierten offerAutopilotSettings Und maxThroughput erforderlich, aber der content Wert wird vom Dienst ignoriert. Unten übergeben wir -1.

Erfahren Sie mehr über die Migration zu manuellem 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"
}

Unten finden Sie einen Beispielantworttext. Die Eigenschaft offerThroughput stellt den manuellen Durchsatz (RU/s) dar, der auf der Ressource festgelegt ist.

{
    "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 automatischen Durchsatz in einer Datenbank oder einem Container ändern, erzwingt das System Einschränkungen für die RU/s, die auf der Ressource festgelegt werden können. Weitere Informationen zum mindest- und maximal bereitgestellten Durchsatz (RU/s), der mit manuellem Durchsatz festgelegt werden kann, finden Sie im Artikel zur Bereitstellung des Durchsatzes für Container und Datenbanken . Informationen zu den minimalen autoscale max RU/s, die Sie festlegen können, finden Sie in der Häufig gestellte Fragen zur automatischen Skalierung.

Um den minimalen Durchsatz abzurufen, der auf Datenbank oder Container festgelegt werden kann, führen Sie GET auf der Angebotsressource aus. Der Antwortheader x-ms-cosmos-min-throughput gibt an, dass das System den minimalen Durchsatz bestimmt. Dies stellt den Mindestwert dar, den Sie für die RU/s für eine Ressource mit manuellem Durchsatz festlegen können, oder den Mindestwert, den Sie für die automatische Skalierung max RU/s auf einer Ressource mit automatischem Durchsatz festlegen können.

Weitere Informationen