提供物の置換

  • [アーティクル]

オファー リソース全体を置き換えるには、特定のオファー リソースに対して PUT 操作を実行します。 コンテナーまたはデータベースで設定できるプロビジョニング済みの最大スループットと最小スループットの詳細については、「コンテナー とデータベースでのスループットのプロビジョニング 」の記事を参照してください。

Request

Method 要求 URI 説明
PUT https://{databaseaccount}.documents.azure.com/offers/{_rid-offer} {databaseaccount} は、サブスクリプションで作成した Azure Cosmos DB アカウントの名前です。 {_rid-offer} の値は、オファーのシステムによって生成されるリソース ID です。

ヒント

データベースまたはコレクションに関連付けられているオファーの_ridを見つけるには、まず データベースを取得 するか、 コレクションを取得 して、リソースの _rid プロパティをメモします。 次 に、オファーにクエリを実行 して、データベースまたはコレクションの_ridに対応する_ridオファーを見つけます。 通常、データベース _ridは長さ 8、コレクション _ridは長さ 12、オファー _ridは長さ 4 です。

ヘッダー

すべての Cosmos DB 要求 で使用されるヘッダーについては、「共通の Azure Cosmos DB REST 要求ヘッダー」を参照してください

Body

プロパティ 必須 Description
offerVersion 必須 従来の S1、S2、S3 レベルの場合は V1、ユーザー定義のスループット レベルの場合は V2 にすることができます (推奨)。
offerType 省略可能 このプロパティは、V1 オファー バージョンでのみ適用されます。 V1 オファーの種類については、S1、S2、または S3 に設定します。 これは、ユーザー定義のパフォーマンス レベルまたはプロビジョニングされたスループット ベースのモデルでは無効です。
content 必須 オファーに関する情報が含まれます。V2 オファーの場合、この値にはコレクションのスループットが含まれます。
resource 必須 新しいコレクションを作成する場合、このプロパティはコレクションのセルフリンクに設定されます (例: dbs/pLJdAA==/colls/pLJdAOlEdgA=/)。
offerResourceId 必須 コレクションの作成時に、このプロパティはリソース ID (つまりコレクションの _rid ) に自動的に関連付けられます。 上記の例では、コレクションの _rid は pLJdAOlEdgA= です。
id 必須 これは、システムによって生成されるプロパティです。 オファー リソースの ID は、作成時に自動的に生成されます。 オファーの _rid と同じ値を持ちます。
_解消 必須 これは、システムによって生成されるプロパティです。 リソース ID (_rid) は、リソース モデルのリソース スタックごとに階層化される一意識別子です。 プランの配置とナビゲーションのために内部的に使用されます。 
{   
  "offerVersion": "V2",   
  "offerType": "Invalid",   
  "content": {   
    "offerThroughput": 4000   
  },   
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",   
  "offerResourceId": "rgkVAMHcJww=",   
  "id": "uT2L",   
  "_rid": "uT2L",   
}

[応答]

更新されたオファー リソースを返します。

ヘッダー

すべての Cosmos DB 応答によって返されるヘッダーについては、「 共通の Azure Cosmos DB REST 応答ヘッダー 」を参照してください。

状態コード

次の表に、この操作で返される一般的なステータス コードを示します。 状態コードの完全な一覧については、「 HTTP 状態コード」を参照してください。

HTTP 状態コード 説明
200 OK 置換操作は成功しました。
400 Bad Request JSON の本文が無効です。 中かっこや引用符の不足がないか確認してください。
401 権限がありません Authorization または x-ms-date ヘッダーが設定されていません。 401 は、Authorization ヘッダーが無効な認証トークンに設定されている場合にも返されます。
404 見つかりません オファーはリソースではなく、つまりリソースが削除されました。
429 Too Many Requests オファーのスケール ダウン操作はアイドル タイムアウト期間内 (4 時間) 以内に試行されるため、オファーの置換は調整されます。 この操作を再試行する前に待機する必要がある時間については、"x-ms-retry-after-ms response" ヘッダーを参照してください。

Body

プロパティ Description
offerVersion この値は、定義済みのスループット レベルの場合は V1、ユーザー定義のスループット レベルの場合は V2 にすることができます。
offerType V1 オファーの定義済みのパフォーマンス レベル S1、S2、または S3。 ユーザー定義のパフォーマンス レベルの場合、その設定は無効です。
content オファーに関する情報が含まれています。 V2 オファーの場合は、コレクションのスループットが含まれます。
resource 新しいコレクションを作成する場合、このプロパティはコレクションのセルフリンクに設定されます (例: dbs/pLJdAA==/colls/pLJdAOlEdgA=/)。
offerResourceId コレクションの作成時に、このプロパティはリソース ID (つまりコレクションの _rid ) に自動的に関連付けられます。 上記の例では、コレクションの _rid は pLJdAOlEdgA= です。
id これは、システムによって生成されるプロパティです。 オファー リソースの ID は、作成時に自動的に生成されます。 オファーの _rid と同じ値を持ちます。
_解消 これは、システムによって生成されるプロパティです。 リソース ID (_rid) は、リソース モデルのリソース スタックごとに階層化される一意識別子です。 プランの配置とナビゲーションのために内部的に使用されます。
_Ts これは、システムによって生成されるプロパティです。 リソースの最終更新タイムスタンプを示します。 値は、タイムスタンプです。
_自己 システムによって生成されるプロパティです。 リソースの一意のアドレス指定が可能な URI です。
_Etag これは、オプティミスティック コンカレンシー制御に必要なリソース etag を指定するシステム生成のプロパティです。 
{  
  "offerVersion": "V2",  
  "_rid": "uT2L",
   "content": {  
    "offerThroughput": 4000
  }, 
  "resource": "dbs/rgkVAA==/colls/rgkVAMHcJww=/",  
  "offerResourceId": "rgkVAMHcJww=",  
  "id": "uT2L",  
  "_self": "offers/uT2L/"
}

例 1

この例では、コレクションの手動スループット (RU/秒) を 1000 RU/秒に変更する方法を示します。

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

応答の例を次に示します。

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  
}

例 2

この例では、自動スケーリング スループットを持つオファーの最大スループット (RU/秒) を 8000 RU/秒 (800 から 8000 RU/秒の間でスケーリング) に変更する方法を示します。

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

例 3

この例では、手動スループットのオファーを自動スケーリング スループットに移行する方法を示します。 値trueを含むヘッダーx-ms-cosmos-migrate-offer-to-autopilotが必要です。

移行時に、Azure Cosmos DB によって、現在のリソース設定に基づいて、新しい自動スケーリングの最大 RU/秒が自動的に決定されます。 応答オブジェクトの プロパティは maxThroughput 、システムによって設定された既定の自動スケーリング最大 RU/秒を表します。

本文では、 が定義offerThroughputされた content プロパティが必要ですが、値はサービスによって無視されます。 次の例では、-1 を使用します。

変更が完了したら、 例 2 に従って、自動スケーリングの最大 RU/秒をカスタム値に変更できます。

自動スケーリングへの移行の詳細については、こちらを参照してください。

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

応答本文の例を次に示します。

プロパティ maxThroughput は、システムによって設定された最大 RU/秒の自動スケーリングを表します。 プロパティ offerThroughput は、システムが現在スケーリングされている RU/秒を表します。

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

例 4

この例では、自動スケーリング スループットを持つオファーを手動スループットに移行する方法を示します。 値trueを含むヘッダーx-ms-cosmos-migrate-offer-to-manual-throughputが必要です。

移行時に、Azure Cosmos DB は現在のリソース設定に基づいて新しい手動スループット (RU/秒) を自動的に決定します。 変更が完了したら、 例 1 に従って手動 RU/秒をカスタム値に変更できます。

本文では、 と がcontent定義offerAutopilotSettingsmaxThroughputされた プロパティが必要ですが、値はサービスによって無視されます。 下に -1 を渡します。

手動スループットへの移行の詳細については、こちらを参照してください。

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

応答本文の例を次に示します。 プロパティ offerThroughput は、リソースに設定された手動スループット (RU/秒) を表します。

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

注釈

データベースまたはコンテナーで手動または自動スケーリングのスループットを変更する場合、システムはリソースに設定できる RU/秒に制約を適用します。 手動スループットで設定できるプロビジョニング済みの最小スループットと最大スループット (RU/秒) の詳細については、 コンテナーとデータベースでのスループットのプロビジョニングに関する 記事を参照してください。 設定できる最小自動スケーリングの最大 RU/秒については、 自動スケーリングに関する FAQ を参照してください。

データベースまたはコンテナーで設定できる最小スループットを取得するには、オファー リソースに対して GET を実行します。 応答ヘッダーは、システムによって決定された最小スループットを示します x-ms-cosmos-min-throughput 。 これは、手動スループットを持つリソースの RU/秒に対して設定できる最小値、または自動スケーリング スループットを持つリソースの自動スケーリング最大 RU/秒に設定できる最小値を表します。

参照