Remplacement d'une offre
Pour remplacer une ressource d’offre entière, effectuez une opération PUT sur la ressource d’offre spécifique. Pour en savoir plus sur le débit provisionné maximal et minimal qui peut être défini sur un conteneur ou une base de données, consultez l’article Provisionner le débit sur des conteneurs et des bases de données .
Requête
| Méthode | URI de demande | Description |
|---|---|---|
| PUT | https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} |
{databaseaccount} est le nom du compte Azure Cosmos DB que vous avez créé sous votre abonnement. La valeur {_rid-offer} est l’ID de ressource généré par le système de l’offre. |
Conseil
Pour trouver le _rid de l’offre associée à une base de données ou à une collection, commencez par OBTENIR la base de données ou GET la collection et notez la propriété _rid de la ressource. Ensuite, interrogez les offres pour rechercher l’offre _rid qui correspond à la _rid de la base de données ou de la collection. En règle générale, une _rid de base de données est de longueur 8, une collection _rid une longueur 12 et une offre _rid longueur 4.
En-têtes
Consultez En-têtes de requête REST Azure Cosmos DB communs pour les en-têtes utilisés par toutes les requêtes Cosmos DB.
body
| Propriété | Obligatoire | Description |
|---|---|---|
| offerVersion | Obligatoire | Il peut s’agir de V1 pour les niveaux S1, S2 et S3 hérités et V2 pour les niveaux de débit définis par l’utilisateur (recommandé). |
| offerType | Facultatif | Cette propriété s’applique uniquement dans la version de l’offre V1. Définissez-le sur S1, S2 ou S3 pour les types d’offres V1. Elle n’est pas valide pour les niveaux de performances définis par l’utilisateur ou le modèle basé sur le débit provisionné. |
| content | Obligatoire | Contient des informations sur l’offre : pour les offres V2, cette valeur contient le débit de la collection. |
| resource | Obligatoire | Lors de la création d’une collection, cette propriété est définie sur l’auto-liaison de la collection, par exemple, dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Obligatoire | Lors de la création d’une collection, cette propriété est automatiquement associée à l’ID de ressource, c’est-à-dire _rid de la collection. Dans l’exemple ci-dessus, le _rid de la collection est pLJdAOlEdgA=. |
| id | Obligatoire | Il s’agit d’une propriété générée par le système. L’ID de la ressource d’offre est généré automatiquement lors de sa création. Elle a la même valeur que la _rid de l’offre. |
| _Débarrasser | Obligatoire | Il s’agit d’une propriété générée par le système. L’ID de ressource (_rid) est un identificateur unique qui est également hiérarchique en fonction de la pile de ressources sur le modèle de ressource. Il est utilisé en interne pour le positionnement et la navigation dans l'offre. |
{
"offerVersion": "V2",
"offerType": "Invalid",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_rid": "uT2L",
}
response
Retourne la ressource d’offre mise à jour.
En-têtes
Consultez En-têtes de réponse REST Azure Cosmos DB communs pour les en-têtes retournés par toutes les réponses Cosmos DB.
Codes d’état
Le tableau suivant répertorie les codes d'état courants renvoyés par cette opération. Pour obtenir la liste complète des codes status, consultez Codes d’état HTTP.
| Code d'état HTTP | Description |
|---|---|
| 200 OK | L'opération de remplacement a réussi. |
| 400 Demande incorrecte | Le corps au format JSON n'est pas valide. Vérifiez qu'il ne manque pas d'accolades ou de guillemets. |
| 401 Non autorisé | L'en-tête Autorization ou x-ms-date n'est pas défini. 401 est également renvoyé quand la valeur définie pour l'en-tête Autorization est un jeton d'autorisation non valide. |
| 404 Introuvable | L’offre n’est plus une ressource, c’est-à-dire que la ressource a été supprimée. |
| 429 Trop de demandes | L’offre de remplacement est limitée, car l’opération de scale-down de l’offre est tentée dans le délai d’inactivité, c’est-à-dire 4 heures. Reportez-vous à l’en-tête « x-ms-retry-after-ms response » pour savoir combien de temps vous devez attendre avant de réessayer cette opération. |
body
| Propriété | Description |
|---|---|
| offerVersion | Cette valeur peut être V1 pour les niveaux de débit prédéfinis et V2 pour les niveaux de débit définis par l’utilisateur. |
| offerType | Niveaux de performances prédéfinis S1, S2 ou S3 pour les offres V1. Est défini sur Non valide pour les niveaux de performances définis par l’utilisateur. |
| content | Il contient des informations sur l’offre. Pour les offres V2, elle contient le débit de la collection. |
| resource | Lors de la création d’une collection, cette propriété est définie sur l’auto-liaison de la collection, par exemple, dbs/pLJdAA==/colls/pLJdAOlEdgA=/. |
| offerResourceId | Lors de la création d’une collection, cette propriété est automatiquement associée à l’ID de ressource, c’est-à-dire _rid de la collection. Dans l’exemple ci-dessus, le _rid de la collection est pLJdAOlEdgA=. |
| id | Il s’agit d’une propriété générée par le système. L’ID de la ressource d’offre est généré automatiquement lors de sa création. Elle a la même valeur que la _rid de l’offre. |
| _Débarrasser | Il s’agit d’une propriété générée par le système. L’ID de ressource (_rid) est un identificateur unique qui est également hiérarchique en fonction de la pile de ressources sur le modèle de ressource. Il est utilisé en interne pour le positionnement et la navigation dans l'offre. |
| _Ts | Il s’agit d’une propriété générée par le système. Elle spécifie l'horodateur de la dernière mise à jour de la ressource. La valeur est un horodateur. |
| _self | Il s’agit d’une propriété générée par le système. Il s'agit de l'URI adressable unique pour la ressource. |
| _Etag | Il s’agit d’une propriété générée par le système qui spécifie l’etag de ressources requis pour le contrôle d’accès concurrentiel optimiste. |
{
"offerVersion": "V2",
"_rid": "uT2L",
"content": {
"offerThroughput": 4000
},
"resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",
"offerResourceId": "rgkVAMHcJww=",
"id": "uT2L",
"_self": "offers/uT2L/"
}
Exemple 1
Cet exemple montre comment modifier le débit manuel (RU/s) d’une collection à 1 000 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="
}
Vous trouverez ci-dessous un exemple de réponse.
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
}
Exemple 2
Cet exemple montre comment modifier le débit maximal (RU/s) d’une offre avec débit de mise à l’échelle automatique à 8 000 RU/s (échelles comprises entre 800 et 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"
}
Exemple 3
Cet exemple montre comment migrer une offre avec un débit manuel vers un débit de mise à l’échelle automatique. L’en-tête x-ms-cosmos-migrate-offer-to-autopilot avec la valeur true est obligatoire.
Lors de la migration, Azure Cosmos DB détermine automatiquement le nouveau nombre maximal de RU/s à la mise à l’échelle automatique en fonction des paramètres de ressource actuels. La maxThroughput propriété dans l’objet de réponse représente la mise à l’échelle automatique par défaut max RU/s définie par le système.
Dans le corps, la content propriété avec un défini offerThroughput est obligatoire, mais la valeur est ignorée par le service. L’exemple suivant utilise -1.
Une fois la modification terminée, vous pouvez suivre l’exemple 2 pour modifier la mise à l’échelle automatique max RU/s en une valeur personnalisée.
En savoir plus sur la migration vers la mise à l’échelle automatique.
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"
}
Vous trouverez ci-dessous un exemple de corps de réponse.
La propriété maxThroughput représente le nombre maximal de RU/s de mise à l’échelle automatique défini par le système. La propriété offerThroughput représente les RU/s que le système est actuellement mis à l’échelle.
{
"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
}
Exemple 4
Cet exemple montre comment migrer une offre avec un débit de mise à l’échelle automatique vers un débit manuel. L’en-tête x-ms-cosmos-migrate-offer-to-manual-throughput avec la valeur true est obligatoire.
Lors de la migration, Azure Cosmos DB détermine automatiquement le nouveau débit manuel (RU/s) en fonction des paramètres de ressource actuels. Une fois la modification terminée, vous pouvez suivre l’exemple 1 pour remplacer les RU/s manuelles par une valeur personnalisée.
Dans le corps, la content propriété avec un et maxThroughput défini offerAutopilotSettings est obligatoire, mais la valeur est ignorée par le service. Ci-dessous, nous passons -1.
En savoir plus sur la migration vers le débit manuel.
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"
}
Vous trouverez ci-dessous un exemple de corps de réponse. La propriété offerThroughput représente le débit manuel (RU/s) défini sur la ressource.
{
"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
}
Notes
Lorsque vous modifiez le débit manuel ou de mise à l’échelle automatique sur une base de données ou un conteneur, le système applique des contraintes sur les RU/s qui peuvent être définies sur la ressource. Pour en savoir plus sur le débit provisionné minimal et maximal (RU/s) qui peut être défini avec le débit manuel, consultez l’article Provisionner le débit sur les conteneurs et les bases de données . Pour en savoir plus sur le nombre minimal de RU/s de mise à l’échelle automatique que vous pouvez définir, consultez le FAQ sur la mise à l’échelle automatique.
Pour récupérer le débit minimal qui peut être défini sur la base de données ou le conteneur, effectuez GET sur la ressource de l’offre. L’en-tête x-ms-cosmos-min-throughput de réponse indique le débit minimal déterminé par le système. Cela représente la valeur minimale que vous pouvez définir pour les RU/s sur une ressource avec un débit manuel, ou la valeur minimale que vous pouvez définir pour la mise à l’échelle automatique max RU/s sur une ressource avec débit de mise à l’échelle automatique.