次の方法で共有

ページ範囲の取得

  • [アーティクル]

ページ範囲の取得操作は、ページ 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 (Bad Request) が発生します。
snapshot 省略可能。 存在する場合は、情報を取得する BLOB スナップショットを指定する不透明な DateTime 値。 BLOB スナップショットの操作の詳細については、「BLOB のスナップショットをCreateする」を参照してください。
timeout 省略可能。 秒単位で表されます。 詳細については、「 Blob Storage 操作のタイムアウトを設定する」を参照してください。
prevsnapshot オプション、バージョン 2015-07-08 以降。 ターゲット BLOB と前のスナップショットの間で変更されたページのみが応答に含まれることを指定する DateTime 値。 変更されたページには、更新されたページとクリアされたページの両方が含まれます。 ターゲット BLOB は、指定されたprevsnapshotスナップショットが 2 つのうち古い場合に限り、スナップショットにすることができます。

注: 増分スナップショットは現在、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、指定された URI にあるターゲット BLOB とスナップショットの間で変更されたページのみが応答に含まれることを指定します。 変更されたページには、更新されたページとクリアされたページの両方が含まれます。 ターゲット BLOB は、このヘッダーで指定されたスナップショットが 2 つのうち古い場合に限り、スナップショットにすることができます。

注: 増分スナップショットは現在、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 要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値 x-ms-client-request-id は、要求に存在し、値に 1,024 文字以下の ASCII 文字が含まれている場合、ヘッダーの値と同じです。 ヘッダーが 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 説明するように承認できます。

重要

Microsoft では、マネージド ID でMicrosoft Entra IDを使用して、Azure Storage への要求を承認することをお勧めします。 Microsoft Entra IDは、共有キーの承認と比較して優れたセキュリティと使いやすさを提供します。

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ユーザー、グループ、マネージド ID、またはサービス プリンシパルが操作を呼び出Get Page Rangesすために必要な RBAC アクションと、このアクションを含む最小特権の組み込み Azure RBAC ロールを次に示します。

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

注釈

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

多数の書き込みによって断片化が進んでいるページ 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 (Conflict) でprevsnapshot失敗します。 操作のGet Page Rangesターゲット自体がスナップショットの場合、 でprevsnapshot指定されたスナップショットが古く、2 つのスナップショット間の間隔で または Copy Blob 操作が呼び出されていない限り、呼び出しPut Blobは成功します。

注意

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

こちらもご覧ください

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