Substituir uma Oferta

  • Artigo

Para substituir um recurso de oferta completo, execute uma operação PUT no recurso de oferta específico. Para saber mais sobre o débito máximo e mínimo aprovisionado que pode ser definido num contentor ou numa base de dados, veja o artigo Aprovisionar débito em contentores e bases de dados .

Pedir

Método URI do pedido Description
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount} é o nome da conta do Azure Cosmos DB que criou na sua subscrição. O valor {_rid-offer} é o ID de recurso gerado pelo sistema da oferta.

Dica

Para encontrar a _rid da oferta associada a uma base de dados ou coleção, obtenha primeiro a base de dados ou OBTENHA a coleção e anote a propriedade _rid do recurso. Em seguida, consulte as ofertas para encontrar a oferta de _rid que corresponde ao _rid da base de dados ou da coleção. Normalmente, uma base de dados _rid tem o comprimento 8, uma coleção _rid tem o comprimento 12 e uma oferta _rid tem o comprimento 4.

Cabeçalhos

Veja Common Azure Cosmos DB REST request headers for headers that are used by all Cosmos DB requests (Cabeçalhos de pedido REST do Azure Cosmos DB comuns para cabeçalhos que são utilizados por todos os pedidos do Cosmos DB)

Corpo

Propriedade Necessário Descrição
offerVersion Necessário Pode ser V1 para os níveis S1, S2 e S3 legados e V2 para níveis de débito definidos pelo utilizador (recomendado).
offerType Opcional Esta propriedade só é aplicável na versão de oferta V1. Defina-o como S1, S2 ou S3 para tipos de oferta V1. É inválido para níveis de desempenho definidos pelo utilizador ou modelo baseado em débito aprovisionado.
conteúdo Necessário Contém informações sobre a oferta – para ofertas V2, este valor contém o débito da coleção.
recurso Necessário Ao criar uma nova coleção, esta propriedade é definida para a autoligação da coleção, por exemplo, dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Necessário Durante a criação de uma coleção, esta propriedade é associada automaticamente ao ID do recurso, ou seja, _rid da coleção. No exemplo acima, o _rid da coleção é pLJdAOlEdgA=.
id Necessário É uma propriedade gerada pelo sistema. O ID do recurso de oferta é gerado automaticamente quando é criado. Tem o mesmo valor que o _rid para a oferta.
_rid Necessário É uma propriedade gerada pelo sistema. O ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recursos. É utilizado internamente para colocação e navegação da oferta. 
{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": 4000   
  },   
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",   
  "offerResourceId": "rgkVAMHcJww=",   
  "id": "uT2L",   
  "_rid": "uT2L",   
}

Resposta

Devolve o recurso de oferta atualizado.

Cabeçalhos

Veja Common Azure Cosmos DB REST response headers for headers that are returned by all Cosmos DB responses (Cabeçalhos de resposta REST do Azure Cosmos DB comuns para cabeçalhos devolvidos por todas as respostas do Cosmos DB).

Códigos de estado

A tabela seguinte lista os códigos de estado comuns devolvidos por esta operação. Para obter uma lista completa dos códigos de estado, veja Códigos de Estado HTTP.

Código de estado de HTTP Descrição
200 OK A operação de substituição foi efetuada com êxito.
400 Pedido Incorreto O corpo JSON é inválido. Verifique se existem parênteses ou aspas curvas em falta.
401 Não Autorizado O cabeçalho Autorização ou x-ms-date não está definido. O erro 401 também é devolvido quando o cabeçalho Autorização está definido como um token de autorização inválido.
404 Não Encontrado A oferta já não é um recurso, ou seja, o recurso foi eliminado.
Demasiados Pedidos 429 A oferta de substituição é limitada porque a operação de redução vertical da oferta é tentada dentro do período de tempo limite de inatividade, ou seja, 4 horas. Veja o cabeçalho "x-ms-retry-after-ms response" para ver quanto tempo deve esperar antes de repetir esta operação.

Corpo

Propriedade Descrição
offerVersion Este valor pode ser V1 para níveis de débito predefinidos e V2 para níveis de débito definidos pelo utilizador.
offerType Níveis de desempenho predefinidos S1, S2 ou S3 para Ofertas V1. Está definido como Inválido para níveis de desempenho definidos pelo utilizador.
conteúdo Contém informações sobre a oferta. Para ofertas V2, contém o débito da coleção.
recurso Ao criar uma nova coleção, esta propriedade é definida para a autoligação da coleção, por exemplo, dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Durante a criação de uma coleção, esta propriedade é associada automaticamente ao ID do recurso, ou seja, _rid da coleção. No exemplo acima, o _rid da coleção é pLJdAOlEdgA=.
id É uma propriedade gerada pelo sistema. O ID do recurso de oferta é gerado automaticamente quando é criado. Tem o mesmo valor que o _rid para a oferta.
_rid É uma propriedade gerada pelo sistema. O ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recursos. É utilizado internamente para colocação e navegação da oferta.
_ts É uma propriedade gerada pelo sistema. Especifica o último carimbo de data/hora atualizado do recurso. O valor é um carimbo de data/hora.
_self É uma propriedade gerada pelo sistema. É o URI endereçável exclusivo para o recurso.
_etag É uma propriedade gerada pelo sistema que especifica a etag de recursos necessária para o controlo de simultaneidade otimista. 
{  
  "offerVersion": "V2",  
  "_rid": "uT2L",
   "content": {  
    "offerThroughput": 4000
  }, 
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/"
}

Exemplo 1

Este exemplo mostra como alterar o débito manual (RU/s) de uma coleção para 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="  
}

Segue-se uma resposta de exemplo.

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  
}

Exemplo 2

Este exemplo mostra como alterar o débito máximo (RU/s) de uma oferta com débito de dimensionamento automático para 8000 RU/s (dimensiona entre 800 e 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"
}

Exemplo 3

Este exemplo mostra como migrar uma oferta com débito manual para dimensionar automaticamente o débito. É necessário o cabeçalho x-ms-cosmos-migrate-offer-to-autopilot com valor true .

Ao migrar, o Azure Cosmos DB determina automaticamente as novas RU/s máximas de dimensionamento automático com base nas definições de recursos atuais. A maxThroughput propriedade no objeto de resposta representa as RU/s máximas de dimensionamento automático predefinidas definidas pelo sistema.

No corpo, a content propriedade com um definido offerThroughput é necessária, mas o valor será ignorado pelo serviço. O exemplo seguinte utiliza -1.

Após a conclusão da alteração, pode seguir o Exemplo 2 para alterar a RU/s máxima de dimensionamento automático para um valor personalizado.

Saiba mais sobre como migrar para o dimensionamento automático.

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

Segue-se um corpo de resposta de exemplo.

A propriedade maxThroughput representa a RU/s máxima de dimensionamento automático definida pelo sistema. A propriedade offerThroughput representa as RU/s para as qual o sistema está atualmente dimensionado.

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

Exemplo 4

Este exemplo mostra como migrar uma oferta com débito de dimensionamento automático para débito manual. É necessário o cabeçalho x-ms-cosmos-migrate-offer-to-manual-throughput com valor true .

Ao migrar, o Azure Cosmos DB determina automaticamente o novo débito manual (RU/s) com base nas definições de recursos atuais. Após a conclusão da alteração, pode seguir o Exemplo 1 para alterar as RU/s manuais para um valor personalizado.

No corpo, a content propriedade com um definido offerAutopilotSettings e maxThroughput é necessária, mas o valor será ignorado pelo serviço. Abaixo passamos em -1.

Saiba mais sobre como migrar para o débito 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"
}

Segue-se um corpo de resposta de exemplo. A propriedade offerThroughput representa o débito manual (RU/s) definido no 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
}

Observações

Quando está a alterar o débito manual ou de dimensionamento automático numa base de dados ou num contentor, o sistema impõe restrições nas RU/s que podem ser definidas no recurso. Para saber mais sobre o débito aprovisionado mínimo e máximo (RU/s) que pode ser definido com débito manual, veja o artigo Aprovisionar débito em contentores e bases de dados . Para saber mais sobre o mínimo de RU/s máximas de dimensionamento automático que pode definir, veja as FAQ sobre o dimensionamento automático.

Para obter o débito mínimo que pode ser definido na base de dados ou no contentor, execute GET no recurso da oferta. O cabeçalho x-ms-cosmos-min-throughput de resposta indica o débito mínimo determinado pelo sistema. Isto representa o valor mínimo que pode definir para as RU/s num recurso com débito manual ou o valor mínimo que pode definir para o máximo de RU/s de dimensionamento automático num recurso com débito de dimensionamento automático.

Consulte também