ページ範囲の取得

[アーティクル]
04/14/2023

ページ範囲の取得操作は、ページ BLOB またはページ BLOB のスナップショットの有効なページ範囲の一覧を返します。

要求

ページ範囲の取得要求は、次のように構築できます。 HTTPS を使用することをお勧めします。 myaccount をストレージアカウントの名前に置き換えます。

GET メソッド要求 URI	HTTP バージョン
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>` `https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=pagelist&snapshot=<DateTime>&prevsnapshot=<DateTime>`	HTTP/1.1

エミュレートされたストレージサービス URI

エミュレートされたストレージサービスに対して要求を行う場合は、エミュレーターのホスト名とAzure Blob Storage ポートを 127.0.0.1:10000 として指定し、その後にエミュレートされたストレージアカウント名を指定します。

GET メソッド要求 URI	HTTP バージョン
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=pagelist`	HTTP/1.1

詳細については、「開発とテストのための Azure のストレージエミュレーター使用」を参照してください。

URI パラメーター

要求 URI には、次の追加パラメーターを指定できます。

パラメーター	説明
`marker`	オプション、バージョン 2020-10-02 以降。次の GetPageRanges 操作で返される範囲の部分を識別します。返された範囲が不完全な場合、操作は応答本文内のマーカー値を返します。その後、マーカー値を後続の呼び出しで使用して、次の範囲セットを要求できます。マーカー値はクライアントに対して非透過的です。
`maxresults`	オプション、バージョン 2020-10-02 以降。返すページ範囲の最大数を指定します。要求で 10,000 を超える値が指定されている場合、サーバーは最大 10,000 個のアイテムを返します。返される追加の結果がある場合、サービスは NextMarker 応答要素で継続トークンを返します。 0 以下の値に設定 `maxresults` すると、エラー応答コード 400 (無効な要求) が発生します。
`snapshot`	省略可能。存在する場合は、情報を取得する BLOB スナップショットを指定する不透明な DateTime 値。 BLOB スナップショットの操作の詳細については、「BLOB のスナップショットを作成する」を参照してください。
`timeout`	省略可能。秒単位で表されます。詳細については、「 Blob Storage 操作のタイムアウトを設定する」を参照してください。
`prevsnapshot`	オプション、バージョン 2015-07-08 以降。ターゲット BLOB と前のスナップショットの間で変更されたページのみが応答に含まれることを指定する DateTime 値。変更されたページには、更新されたページとクリアされたページの両方が含まれます。で指定された`prevsnapshot`スナップショットが 2 つのうち古い場合、ターゲット BLOB はスナップショットである可能性があります。注: 増分スナップショットは現在、2016 年 1 月 1 日以降に作成された BLOB でのみサポートされています。

要求ヘッダー

必須要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。

要求ヘッダー	説明
`Authorization`	必須。承認スキーム、アカウント名、署名を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`Date` または `x-ms-date`	必須。要求に対して協定世界時 (UTC) を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`x-ms-version`	すべての承認された要求に必要です。匿名要求の場合は省略可能です。この要求に使用する操作のバージョンを指定します。詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
`Range`	省略可能。範囲を一覧表示するバイトの範囲を指定します。 `Range`を省略すると、BLOB のすべての範囲が返されます。
`x-ms-range`	省略可能。範囲を一覧表示するバイトの範囲を指定します。 `Range` と `x-ms-range` の両方が指定されている場合、サービスは `x-ms-range` の値を使用します。詳細については、「 Blob Storage 操作の範囲ヘッダーを指定する」を参照してください。
`x-ms-lease-id:<ID>`	省略可能。このヘッダーを指定すると、次の両方の条件が満たされた場合にのみ操作が実行されます。 - BLOB のリースは現在アクティブです。 - 要求で指定されたリース ID は、BLOB のリース ID と一致します。このヘッダーが指定されていて、いずれかの条件が満たされていない場合、要求は失敗し、状態コード 412 (前提条件が失敗) で操作が失敗します。
`x-ms-previous-snapshot-url`	オプション、バージョン 2019-07-07 以降。では`previous-snapshot-url`、ターゲット BLOB と指定した URI にあるスナップショットの間で変更されたページのみが応答に含まれることを指定します。変更されたページには、更新されたページとクリアされたページの両方が含まれます。このヘッダーで指定されたスナップショットが 2 つのうち古い場合、ターゲット BLOB はスナップショットである可能性があります。注: 増分スナップショットは現在、2016 年 1 月 1 日以降に作成された BLOB でのみサポートされており、このヘッダーはマネージドディスクのシナリオでのみ使用する必要があります。それ以外の場合は、パラメーターを `prevsnapshot` 使用します。
`x-ms-client-request-id`	省略可能。 Azure Storage Analytics ログが有効になっているときに分析ログに記録される、1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。サーバーが受信した要求とクライアント側のアクティビティを関連付けるとき、このヘッダーを使用することを強くお勧めします。詳細については、「Storage Analyticsログ記録について」と「Azure ログ: ログを使用して Azure Storage 要求を追跡する」を参照してください。

この操作では、条件ヘッダーを使用して、指定した条件を満たした場合にのみページ範囲を取得することもできます。詳細については、「 Blob Storage 操作の条件付きヘッダーを指定する」を参照してください。

要求本文

[なし] :

Response

応答には HTTP ステータスコード、一連の応答ヘッダー、および応答の本文が含まれます。

status code

操作に成功すると、状態コード 200 (OK) が返されます。

状態コードの詳細については、「状態とエラーコード」を参照してください。

応答ヘッダー

この操作の応答には、次のヘッダーが含まれています。応答に追加の標準 HTTP ヘッダーが含まれる場合もあります。すべての標準ヘッダーは、HTTP/1.1 プロトコル仕様に準拠しています。

構文	説明
`Last-Modified`	BLOB が最後に更新された日時。日付形式は RFC 1123 に従います。 BLOB を変更する操作 (BLOB のメタデータまたはプロパティの更新など) を行うと、BLOB の最終更新時刻が変更されます。
`ETag`	条件付きで操作を実行するためにクライアントが使用できる値を格納します。要求バージョンが 2011-08-18 以降の場合、ETag 値は引用符で囲まれます。
`x-ms-blob-content-length`	BLOB のサイズ (単位: バイト)。
`x-ms-request-id`	行われた要求を一意に識別し、要求のトラブルシューティングに使用できます。詳細については、「 API 操作のトラブルシューティング」を参照してください。
`x-ms-version`	要求の実行に使用された Blob Storage のバージョンを示します。このヘッダーは、バージョン 2009-09-19 以降に対して行われた要求に対して返されます。 Blob Storage バージョン 2009-09-19 を使用してコンテナーがパブリックアクセス用にマークされている場合、このヘッダーは、指定されたバージョンのない匿名要求にも返されます。
`Date`	サービスによって生成される UTC 日付/時刻値。応答が開始された時刻を示します。
`x-ms-client-request-id`	要求と対応する応答のトラブルシューティングに使用できます。このヘッダーの値は、要求に存在し、その値に 1,024 文字以下の ASCII 文字が含まれている場合、ヘッダーの値 `x-ms-client-request-id` と等しくなります。ヘッダーが `x-ms-client-request-id` 要求に存在しない場合、応答には存在しません。

応答本文

応答本文には、重複しない有効なページ範囲の一覧が含まれ、アドレスページ範囲を増やして並べ替えられます。応答本文の形式は次のとおりです。

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>

BLOB のページのセット全体がクリアされている場合、応答本文にはページ範囲は含まれません。

パラメーターがprevsnapshot指定されている場合、応答には、ターゲットスナップショットまたは BLOB と前のスナップショットの間で異なるページのみが含まれます。返されるページには、更新またはクリアされた両方のページが含まれます。この応答本文の形式は次のとおりです。

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
</PageList>

BLOB のページのセット全体がクリアされ、パラメーターが prevsnapshot 指定されていない場合、応答本文にはページ範囲は含まれません。

パラメーターが maxresults 指定されている場合、応答には、タグに継続トークン NextMarker を含む指定された数の範囲のみが含まれます。保留中の範囲がない場合、または次の要求でパラメーターとして marker 送信する必要がある不透明な値が含まれている場合、継続トークンは空です。この応答本文の形式は次のとおりです。

<?xml version="1.0" encoding="utf-8"?>  
<PageList>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>  
   <ClearRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </ClearRange>  
   <PageRange>  
      <Start>Start Byte</Start>  
      <End>End Byte</End>  
   </PageRange>
   <NextMarker/>
</PageList>

承認

Azure Storage でデータアクセス操作を呼び出す場合は、承認が必要です。以下で説明するように、操作を Get Page Ranges 承認できます。

Azure Storage では、Microsoft Entra IDを使用して BLOB データへの要求を承認することがサポートされています。 Microsoft Entra IDでは、Azure ロールベースのアクセス制御 (Azure RBAC) を使用して、セキュリティプリンシパルにアクセス許可を付与できます。セキュリティプリンシパルには、ユーザー、グループ、アプリケーションサービスプリンシパル、または Azure マネージド ID を指定できます。セキュリティプリンシパルは、OAuth 2.0 トークンを返すためにMicrosoft Entra IDによって認証されます。その後、そのトークンを、Blob service に対する要求を認可するために使用できます。

Microsoft Entra IDを使用した承認の詳細については、「Microsoft Entra IDを使用して BLOB へのアクセスを承認する」を参照してください。

アクセス許可

Microsoft Entraユーザー、グループ、またはサービスプリンシパルが操作を呼び出Get Page Rangesすために必要な RBAC アクションと、このアクションを含む最小限の特権を持つ組み込み Azure RBAC ロールを次に示します。

Azure RBAC アクション:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/read
最小特権の組み込みロール:ストレージ BLOB データ閲覧者

Azure RBAC を使用したロールの割り当ての詳細については、「 BLOB データにアクセスするための Azure ロールの割り当て」を参照してください。

Shared Access Signature (SAS) は、ストレージアカウント内のリソースへのセキュリティで保護された委任されたアクセスを提供します。 SAS を使用すると、クライアントがデータにアクセスする方法をきめ細かく制御できます。クライアントがアクセスできるリソース、それらのリソースに対するアクセス許可、および SAS が有効な期間を指定できます。

この操作では Get Page Ranges 、ユーザー委任 SAS、サービス SAS、アカウント SAS の 3 種類の共有アクセス署名がサポートされています。

セキュリティのベストプラクティスとして、ストレージアカウントキーではなくMicrosoft Entra資格情報を使用することをお勧めします。これは、より簡単に侵害される可能性があります。アプリケーション設計で共有アクセス署名が必要な場合は、可能であれば、Microsoft Entra資格情報を使用してユーザー委任 SAS を作成します。

ストレージアカウントに対して共有キーアクセスが許可されていない場合、サービス SAS トークンまたはアカウント SAS トークンは、Blob Storage への要求では許可されません。詳細については、「共有キーの禁止が SAS トークンにどのように影響するかを理解する」を参照してください。

ユーザー委任 SAS

ユーザー委任 SAS は、Microsoft Entra資格情報と、SAS に対して指定されたアクセス許可によっても保護されます。

Get Page Rangesコンテナーまたは BLOB リソースに委任された SAS トークンを使用して操作を呼び出すには、ユーザー委任 SAS トークンの一部として読み取り (r) アクセス許可が必要です。

ユーザー委任 SAS の詳細については、「ユーザー委任 SAS の作成」を参照してください。

サービス SAS

サービス SAS は、ストレージアカウントキーで保護されます。サービス SAS は、BLOB ストレージなどの単一の Azure Storage サービス内のリソースへのアクセスを委任します。

Get Page Rangesコンテナーまたは BLOB リソースに委任された SAS トークンを使用して操作を呼び出すには、サービス SAS トークンの一部として読み取り (r) アクセス許可が必要です。

サービス SAS の詳細については、「サービス SAS の作成」を参照してください。

アカウント SAS

アカウント SAS は、ストレージアカウントキーで保護されます。アカウント SAS は、1 つ以上のストレージサービスのリソースへのアクセスを委任します。サービスまたはユーザー委任 SAS を介して実行できるすべての操作は、アカウント SAS を介しても実行できます。

次の表は、アクセスを委任するときに指定する署名付きリソースの種類と署名付きアクセス許可を示しています。

操作	署名済みサービス	署名されたリソースの種類	署名されたアクセス許可
ページ範囲の取得	BLOB (b)	オブジェクト (o)	読み取り (r)

アカウント SAS の詳細については、「アカウント SAS の作成」を参照してください。

この操作では Get Page Ranges 、共有キーの承認がサポートされています。アカウントキーを使用した承認は、セキュリティが低く、ほとんどのシナリオでは推奨されません。

可能な場合は、ストレージアカウントの共有キーの承認を禁止することをお勧めします。詳細については、「共有キーによる承認の防止」を参照してください。

注釈

各ページ範囲の開始と終了のバイトオフセットには、その開始値と終了値が含まれます。

多数の書き込みによって断片化が進んでいるページ BLOB では、内部サーバーのタイムアウトによって Get Page Ranges 要求が失敗する場合があります。多数の書き込み操作が実行されたページ BLOB の範囲を取得するアプリケーションでは、ページ範囲のサブセットを一度に取得する必要があります。

バージョン 2015-07-08 の時点で、パラメーターを使用してをprevsnapshot呼び出Get Page Rangesして、ベース BLOB とスナップショット間、または BLOB の 2 つのスナップショット間で異なるページを返すことができます。これらのページの相違点を使用すると、ページ BLOB の増分スナップショットを保存できます。増分スナップショットは、独自のバックアップソリューションを実装する場合に、仮想マシンディスクをバックアップするためのコスト効率の高い方法です。

パラメーターを指定してをprevsnapshot呼び出Get Page Rangesすと、でprevsnapshot指定されたスナップショットが取得されてから更新またはクリアされたページが返されます。その後、 Put Page を使用して、別のストレージアカウントのバックアップページ BLOB に返されるページをコピーできます。

バージョン 2019-07-07 以降では、ヘッダーを x-ms-previous-snapshot-url 使用して、増分スナップショットのマネージドディスクアカウントのスナップショットを指定できます。マネージドディスクを使用していない場合は、クエリパラメーターを prevsnapshot 使用します。

BLOB Get Page Ranges に対する特定の操作は、増分スナップショットを返すために呼び出されると失敗します。 Get Pages Rangesによって指定されたスナップショットが取得された後に Put BLOB または Copy BLOB 要求のターゲットであった BLOB で呼び出された場合、エラーコード 409 (競合) でprevsnapshot失敗します。操作のGet Page Rangesターゲットがそれ自体がスナップショットの場合、でprevsnapshot指定されたスナップショットが古く、2 つのスナップショット間で操作Copy Blobが呼び出されなかった限り、呼び出しPut Blobは成功します。

注意

増分スナップショットは現在、2016 年 1 月 1 日以降に作成された BLOB でのみサポートされています。古い BLOB でこの機能を使用しようとすると、エラーが発生 BlobOverwritten します。これは HTTP エラーコード 409 (競合) です。

こちらもご覧ください

Azure Storage への要求を承認する
 状態コードとエラーコード
 Blob Storage 操作のタイムアウトを設定する