Compartilhar via

Substituir uma oferta

  • Artigo

Para substituir um recurso de oferta inteiro, execute uma operação PUT no recurso de oferta específico. Para saber mais sobre a taxa de transferência provisionada máxima e mínima que pode ser definida em um contêiner ou um banco de dados, consulte o artigo Provisionar taxa de transferência em contêineres e bancos de dados .

Solicitação

Método URI da solicitação Descrição
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount} é o nome da conta do Azure Cosmos DB que você criou em sua assinatura. O valor {_rid-offer} é a ID de recurso gerada pelo sistema da oferta.

Dica

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

Cabeçalhos

Confira Cabeçalhos comuns de solicitação REST do Azure Cosmos DB para cabeçalhos usados por todas as solicitações do Cosmos DB

Corpo

Propriedade Obrigatório Descrição
offerVersion Obrigatório Pode ser V1 para os níveis herdados de S1, S2 e S3 e V2 para níveis de taxa de transferência definidos pelo usuário (recomendado).
offerType Opcional Essa propriedade só é aplicável na versão da oferta V1. Defina-o como S1, S2 ou S3 para tipos de oferta V1. Ele é inválido para níveis de desempenho definidos pelo usuário ou modelo baseado em taxa de transferência provisionada.
content Obrigatório Contém informações sobre a oferta – para ofertas V2, esse valor contém a taxa de transferência da coleção.
recurso Obrigatório Ao criar uma nova coleção, essa propriedade é definida como o auto-link da coleção, por exemplo, dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Obrigatório Durante a criação de uma coleção, essa propriedade é automaticamente associada à ID do recurso, ou seja, _rid da coleção. No exemplo acima, o _rid da coleção é pLJdAOlEdgA=.
id Obrigatório É uma propriedade gerada pelo sistema. A ID do recurso de oferta é gerada automaticamente quando ele é criado. Ele tem o mesmo valor que o _rid para a oferta.
_Livrar Obrigatório É uma propriedade gerada pelo sistema. A ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recurso. Ela é usada internamente para posicionamento e navegação da oferta. 
{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": 4000   
  },   
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",   
  "offerResourceId": "rgkVAMHcJww=",   
  "id": "uT2L",   
  "_rid": "uT2L",   
}

Resposta

Retorna o recurso de oferta atualizado.

Cabeçalhos

Consulte Cabeçalhos comuns de resposta REST do Azure Cosmos DB para obter cabeçalhos retornados por todas as respostas do Cosmos DB.

Códigos de status

A tabela a seguir lista os códigos de status comuns retornados por esta operação. Para obter uma lista completa de códigos de status, consulte Códigos de status HTTP.

Código de status HTTP Descrição
200 OK A operação de substituição foi bem-sucedida.
400 Solicitação Inválida O corpo JSON é inválido. Verifique por colchetes ou aspas ausentes.
401 Não Autorizado O cabeçalho de Autorização ou x-ms-date não está definido. 401 também é retornado quando o cabeçalho de Autorização for definido como um token de autorização inválido.
404 Não Encontrado A oferta não é mais um recurso, ou seja, o recurso foi excluído.
429 Número excessivo de solicitações A oferta de substituição é limitada porque a operação de redução da oferta é tentada dentro do período de tempo limite ocioso, ou seja, 4 horas. Consulte o cabeçalho "x-ms-retry-after-ms response" para ver quanto tempo você deve esperar antes de repetir essa operação.

Corpo

Propriedade Descrição
offerVersion Esse valor pode ser V1 para níveis de taxa de transferência predefinidos e V2 para níveis de taxa de transferência definidos pelo usuário.
offerType Níveis de desempenho predefinidos S1, S2 ou S3 para ofertas V1. Seu conjunto como Inválido para níveis de desempenho definidos pelo usuário.
content Ele contém informações sobre a oferta. Para ofertas V2, ela contém a taxa de transferência da coleção.
recurso Ao criar uma nova coleção, essa propriedade é definida como o auto-link da coleção, por exemplo, dbs/pLJdAA==/colls/pLJdAOlEdgA=/.
offerResourceId Durante a criação de uma coleção, essa propriedade é automaticamente associada à ID do recurso, ou seja, _rid da coleção. No exemplo acima, o _rid da coleção é pLJdAOlEdgA=.
id É uma propriedade gerada pelo sistema. A ID do recurso de oferta é gerada automaticamente quando ele é criado. Ele tem o mesmo valor que o _rid para a oferta.
_Livrar É uma propriedade gerada pelo sistema. A ID do recurso (_rid) é um identificador exclusivo que também é hierárquico de acordo com a pilha de recursos no modelo de recurso. Ela é usada internamente para posicionamento 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.
_Auto É uma propriedade gerada pelo sistema. É o URI endereçável exclusivo do recurso.
_Etag É uma propriedade gerada pelo sistema que especifica a etag de recurso necessária para o controle 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 a taxa de transferência 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="  
}

Veja abaixo 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 a taxa de transferência máxima (RU/s) de uma oferta com taxa de transferência de dimensionamento automático para 8.000 RU/s (escalas entre 800 e 8.000 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 taxa de transferência manual para a taxa de transferência de dimensionamento automático. O cabeçalho x-ms-cosmos-migrate-offer-to-autopilot com valor true é necessário.

Ao migrar, o Azure Cosmos DB determina automaticamente o novo dimensionamento automático máximo de RU/s com base nas configurações de recurso atuais. A maxThroughput propriedade no objeto de resposta representa o máximo de RU/s de dimensionamento automático padrão definido pelo sistema.

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

Depois que a alteração for concluída, você poderá seguir o Exemplo 2 para alterar o máximo de RU/s 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"
}

Abaixo está um corpo de resposta de exemplo.

A propriedade maxThroughput representa o máximo de RU/s de dimensionamento automático definido pelo sistema. A propriedade offerThroughput representa as RU/s para as qual o sistema está escalado no momento.

{
    "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 taxa de transferência de dimensionamento automático para taxa de transferência manual. O cabeçalho x-ms-cosmos-migrate-offer-to-manual-throughput com valor true é necessário.

Ao migrar, o Azure Cosmos DB determina automaticamente a nova taxa de transferência manual (RU/s) com base nas configurações de recurso atuais. Depois que a alteração for concluída, você poderá 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 -1.

Saiba mais sobre como migrar para a taxa de transferência 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"
}

Abaixo está um corpo de resposta de exemplo. A propriedade offerThroughput representa a taxa de transferência manual (RU/s) definida 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
}

Comentários

Quando você está alterando a taxa de transferência manual ou de dimensionamento automático em um banco de dados ou contêiner, o sistema impõe restrições nas RU/s que podem ser definidas no recurso. Para saber mais sobre a taxa de transferência provisionada mínima e máxima (RU/s) que pode ser definida com taxa de transferência manual, consulte o artigo Provisionar taxa de transferência em contêineres e bancos de dados . Para saber mais sobre o máximo mínimo de RU/s de dimensionamento automático que você pode definir, consulte as Perguntas frequentes sobre o dimensionamento automático.

Para recuperar a taxa de transferência mínima que pode ser definida no banco de dados ou contêiner, execute GET no recurso de oferta. O cabeçalho x-ms-cosmos-min-throughput de resposta indica a taxa de transferência mínima determinada pelo sistema. Isso representa o valor mínimo que você pode definir para as RU/s em um recurso com taxa de transferência manual ou o valor mínimo que você pode definir para o máximo de RU/s de dimensionamento automático em um recurso com taxa de transferência de dimensionamento automático.

Consulte Também