Substituir uma oferta

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 banco de dados, consulte o artigo Provisionar taxa de transferência em contêineres e bancos de dados .

Request

Método	Solicitar URI	Descrição
INSERIR	`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} é o ID de recurso gerado pelo sistema da oferta.

Sugestão

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

Cabeçalhos

Consulte Cabeçalhos de solicitação REST comuns 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 S1, S2 e S3 herdados e V2 para níveis de taxa de transferência definidos pelo usuário (recomendado).
offerType	Opcional	Esta propriedade só é aplicável na versão de oferta V1. Defina-o como S1, S2 ou S3 para os tipos de oferta V1. É inválido para níveis de desempenho definidos pelo usuário ou modelo baseado em taxa de transferência provisionada.
Conteúdo	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 autolink 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 anterior, o _rid para a coleção é pLJdAOlEdgA=.
ID	Obrigatório	É uma propriedade gerada pelo sistema. O ID do recurso de oferta é gerado automaticamente quando ele é criado. Tem o mesmo valor que o _rid para a oferta.
_rid	Obrigatório	É uma propriedade gerada pelo sistema. O ID do recurso (_rid) é um identificador exclusivo que também é hierárquico pela 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

Retorna o recurso de oferta atualizado.

Cabeçalhos

Consulte Cabeçalhos de resposta REST comuns do Azure Cosmos DB para 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 essa operação. Para obter uma lista completa de códigos de status, consulte Códigos de status HTTP.

Código de estado de HTTP	Descrição
200 OK	A operação de substituição foi bem-sucedida.
400 Pedido Inválido	O corpo JSON é inválido. Verifique se faltam parênteses ou cotações.
401 Não autorizado	O cabeçalho Authorization ou x-ms-date não está definido. 401 também é retornado quando o cabeçalho Authorization é 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.
Demasiados Pedidos 429	A oferta de substituição é limitada porque a operação de redução de escala da oferta é tentada dentro do período de tempo limite ocioso que é de 4 horas. Consulte o cabeçalho "x-ms-retry-after-ms response" para ver quanto tempo você deve esperar antes de tentar novamente esta 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. É definido como Inválido para níveis de desempenho definidos pelo usuário.
Conteúdo	Contém informações sobre a oferta. Para ofertas V2, ele contém a taxa de transferência da coleção.
recurso	Ao criar uma nova coleção, essa propriedade é definida como o autolink 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 anterior, o _rid para a coleção é pLJdAOlEdgA=.
ID	É uma propriedade gerada pelo sistema. O ID do recurso de oferta é gerado automaticamente quando ele é 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 pela pilha de recursos no modelo de recursos. É utilizado internamente para colocação e navegação da oferta.
_ts	É uma propriedade gerada pelo sistema. Ele 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 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="  
}

Aqui está um exemplo de resposta.

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 8000 RU/s (escala entre 800 - 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 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 é obrigatório.

Ao migrar, o Azure Cosmos DB determina automaticamente o novo RU/s máximo de escala automática com base nas configurações de recursos atuais. A maxThroughput propriedade no objeto response representa o padrão autoscale max RU/s 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 a escala automática max RU/s 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"
}

Aqui está um corpo de resposta de exemplo.

A propriedade maxThroughput representa o autoscale max RU/s definido pelo sistema. A propriedade offerThroughput representa o RU/s para o 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 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 é obrigatório.

Ao migrar, o Azure Cosmos DB determina automaticamente a nova taxa de transferência manual (RU/s) com base nas configurações de recursos atuais. Após a conclusão da alteração, você pode seguir o Exemplo 1 para alterar o RU/s manual 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. Aqui passamos em -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"
}

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

Observações

Quando você altera 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 no 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 a taxa de transferência manual, consulte o artigo Taxa de transferência de provisionamento em contêineres e bancos de dados . Para saber mais sobre o máximo de RU/s mínimo de escala automática que você pode definir, consulte as Perguntas frequentes sobre 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 o RU/s em um recurso com taxa de transferência manual ou o valor mínimo que você pode definir para o RU/s máximo de escala automática em um recurso com taxa de transferência de dimensionamento automático.

Ver também

Azure Cosmos DB
da API SQL do Azure Cosmos DB
SDK da API SQL do Azure Cosmos DB
REST da de exemplo .NET

Last updated on 2025-08-15

Partilhar via

Substituir uma oferta

Request

Cabeçalhos

Corpo

Resposta

Cabeçalhos

Códigos de status

Corpo

Exemplo 1

Exemplo 2

Exemplo 3

Exemplo 4

Observações

Ver também

Recursos adicionais