Share via

Reemplazar una oferta

  • Artículo

Para reemplazar un recurso de oferta completo, realice una operación PUT en el recurso de oferta específico. Para más información sobre el rendimiento aprovisionado máximo y mínimo que se puede establecer en un contenedor o una base de datos, consulte el artículo Aprovisionamiento del rendimiento en contenedores y bases de datos .

Solicitud

Método URI de solicitud Descripción
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount} es el nombre de la cuenta de Azure Cosmos DB que creó en la suscripción. El valor {_rid-offer} es el identificador de recurso generado por el sistema de la oferta.

Sugerencia

Para buscar el _rid de la oferta asociada a una base de datos o colección, primero obtenga la base de datos o GET la colección y anote la propiedad _rid del recurso. A continuación, consulte las ofertas para buscar la oferta _rid que corresponde a la base de datos o al _rid de la colección. Normalmente, un _rid de base de datos es de longitud 8, un _rid de colección es de 12 y una oferta _rid es de longitud 4.

encabezados

Consulte Encabezados de solicitud REST comunes de Azure Cosmos DB para los encabezados que usan todas las solicitudes de Cosmos DB.

Body

Propiedad Obligatorio Descripción
offerVersion Obligatorio Puede ser V1 para los niveles heredados S1, S2 y S3 y V2 para los niveles de rendimiento definidos por el usuario (recomendado).
offerType Opcionales Esta propiedad solo es aplicable en la versión de la oferta V1. Establézcalo en S1, S2 o S3 para los tipos de oferta V1. No es válido para los niveles de rendimiento definidos por el usuario o para el modelo basado en rendimiento aprovisionado.
content Obligatorio Contiene información sobre la oferta: para las ofertas V2, este valor contiene el rendimiento de la colección.
resource Obligatorio Al crear una nueva colección, esta propiedad se establece en el auto-vínculo de la colección, por ejemplo, dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Obligatorio Durante la creación de una colección, esta propiedad se asocia automáticamente al identificador de recurso, es decir, _rid de la colección. En el ejemplo anterior, el _rid de la colección es pLJdAOlEdgA=.
id Obligatorio Es una propiedad generada por el sistema. El identificador del recurso de oferta se genera automáticamente cuando se crea. Tiene el mismo valor que el _rid de la oferta.
_Librar Obligatorio Es una propiedad generada por el sistema. El identificador de recurso (_rid) es un identificador único que también es jerárquico por la pila de recursos en el modelo de recursos. Se usa internamente para la colocación y desplazamiento de la oferta. 
{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": 4000   
  },   
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",   
  "offerResourceId": "rgkVAMHcJww=",   
  "id": "uT2L",   
  "_rid": "uT2L",   
}

Response

Devuelve el recurso de oferta actualizado.

encabezados

Consulte Encabezados de respuesta REST comunes de Azure Cosmos DB para ver los encabezados devueltos por todas las respuestas de Cosmos DB.

Códigos de estado

La tabla siguiente muestra los códigos de estado comunes que devuelve esta operación. Para obtener una lista completa de los códigos de estado, consulte Códigos de estado HTTP.

Código de estado HTTP Descripción
200 OK La operación de reemplazo se realizó correctamente.
400 - Solicitud incorrecta El cuerpo JSON no es válido. Compruebe si faltan llaves o comillas.
401 No autorizado El encabezado Authorization o x-ms-date no está configurado. También se devuelve 401 cuando el encabezado Authorization está definido en un token de autorización no válido.
404 No encontrado La oferta ya no es un recurso, es decir, se eliminó el recurso.
429 Demasiadas solicitudes La oferta de reemplazo se limita porque la operación de reducción vertical de la oferta se intenta dentro del período de tiempo de espera de inactividad, es decir, 4 horas. Consulte el encabezado "x-ms-retry-after-ms response" para ver cuánto tiempo debe esperar antes de volver a intentar esta operación.

Body

Propiedad Descripción
offerVersion Este valor puede ser V1 para los niveles de rendimiento predefinidos y V2 para los niveles de rendimiento definidos por el usuario.
offerType Niveles de rendimiento predefinidos S1, S2 o S3 para ofertas V1. Se establece en No válido para los niveles de rendimiento definidos por el usuario.
content Contiene información sobre la oferta. En el caso de las ofertas V2, contiene el rendimiento de la colección.
resource Al crear una nueva colección, esta propiedad se establece en el auto-vínculo de la colección, por ejemplo, dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Durante la creación de una colección, esta propiedad se asocia automáticamente al identificador de recurso, es decir, _rid de la colección. En el ejemplo anterior, el _rid de la colección es pLJdAOlEdgA=.
id Es una propiedad generada por el sistema. El identificador del recurso de oferta se genera automáticamente cuando se crea. Tiene el mismo valor que el _rid de la oferta.
_Librar Es una propiedad generada por el sistema. El identificador de recurso (_rid) es un identificador único que también es jerárquico por la pila de recursos en el modelo de recursos. Se usa internamente para la colocación y desplazamiento de la oferta.
_Ts Es una propiedad generada por el sistema. Especifica la última marca de tiempo actualizada del recurso. El valor es una marca de tiempo.
_propio Es una propiedad generada por el sistema. Es el URI direccionable único para el recurso.
_Etag Se trata de una propiedad generada por el sistema que especifica la etiqueta electrónica de recursos necesaria para el control de simultaneidad optimista. 
{  
  "offerVersion": "V2",  
  "_rid": "uT2L",
   "content": {  
    "offerThroughput": 4000
  }, 
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/"
}

Ejemplo 1

En este ejemplo se muestra cómo cambiar el rendimiento manual (RU/s) de una colección a 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="  
}

A continuación se muestra una respuesta de ejemplo.

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  
}

Ejemplo 2

En este ejemplo se muestra cómo cambiar el rendimiento máximo (RU/s) de una oferta con rendimiento de escalabilidad automática a 8000 RU/s (escala entre 800 y 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"
}

Ejemplo 3

En este ejemplo se muestra cómo migrar una oferta con rendimiento manual al rendimiento de escalabilidad automática. El encabezado x-ms-cosmos-migrate-offer-to-autopilot con valor true es obligatorio.

Al migrar, Azure Cosmos DB determina automáticamente las nuevas RU/s máximas de escalabilidad automática en función de la configuración actual del recurso. La maxThroughput propiedad del objeto de respuesta representa el número máximo de RU/s de escalado automático predeterminado establecido por el sistema.

En el cuerpo, se requiere la content propiedad con un definido offerThroughput , pero el servicio omitirá el valor. En el ejemplo siguiente se usa -1.

Una vez completado el cambio, puede seguir el ejemplo 2 para cambiar el número máximo de RU/s de escalabilidad automática a un valor personalizado.

Obtenga más información sobre la migración a escalabilidad automática.

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

A continuación se muestra un cuerpo de respuesta de ejemplo.

La propiedad maxThroughput representa el número máximo de RU/s de escalado automático establecido por el sistema. La propiedad offerThroughput representa las RU/s a las que se escala actualmente el sistema.

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

Ejemplo 4

En este ejemplo se muestra cómo migrar una oferta con rendimiento de escalabilidad automática al rendimiento manual. El encabezado x-ms-cosmos-migrate-offer-to-manual-throughput con valor true es obligatorio.

Al migrar, Azure Cosmos DB determina automáticamente el nuevo rendimiento manual (RU/s) en función de la configuración actual de los recursos. Una vez completado el cambio, puede seguir el ejemplo 1 para cambiar las RU/s manuales a un valor personalizado.

En el cuerpo, la content propiedad con un definido offerAutopilotSettings y maxThroughput es necesaria, pero el servicio omitirá el valor. A continuación pasamos -1.

Obtenga más información sobre la migración al rendimiento manual.

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

A continuación se muestra un cuerpo de respuesta de ejemplo. La propiedad offerThroughput representa el rendimiento manual (RU/s) establecido en el recurso.

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

Comentarios

Al cambiar el rendimiento manual o de escalabilidad automática en una base de datos o contenedor, el sistema aplica restricciones en las RU/s que se pueden establecer en el recurso. Para más información sobre el rendimiento aprovisionado mínimo y máximo (RU/s) que se pueden establecer con rendimiento manual, consulte el artículo Aprovisionamiento del rendimiento en contenedores y bases de datos . Para obtener información sobre el número mínimo de RU/s de escalado automático que puede establecer, consulte las preguntas más frecuentes sobre el escalado automático.

Para recuperar el rendimiento mínimo que se puede establecer en la base de datos o el contenedor, realice GET en el recurso de la oferta. El encabezado x-ms-cosmos-min-throughput de respuesta denota el rendimiento mínimo determinado por el sistema. Esto representa el valor mínimo que puede establecer para las RU/s en un recurso con rendimiento manual o el valor mínimo que puede establecer para el máximo de RU/s de escalado automático en un recurso con rendimiento de escalabilidad automática.

Consulte también