List Ranges

[アーティクル]
03/29/2023

List Ranges操作は、ファイルの有効な範囲の一覧を返します。

プロトコルの可用性

有効なファイル共有プロトコル	利用可能
SMB
NFS

Request

要求は List Ranges 次のように構築できます。 HTTPS が推奨されます。

Method	要求 URI	HTTP バージョン
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	HTTP/1.1

次のように、要求 URI に示されたパスコンポーネントを独自の URI に置き換えます。

パスコンポーネント	説明
`myaccount`	ご利用のストレージアカウントの名前。
`myshare`	ファイル共有の名前。
`mydirectorypath`	省略可能。親ディレクトリへのパス。
`myfile`	ファイルの名前です。

パスの名前付け制限の詳細については、「共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

URI パラメーター

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

パラメーター	説明
`sharesnapshot`	省略可能。バージョン 2017-04-17 以降。パラメーターは`sharesnapshot`不透明`DateTime`な値であり、存在する場合は、ファイルに対してクエリを実行する共有スナップショットを指定します。
`timeout`	省略可能。 `timeout` パラメーターは、秒単位で表されます。詳細については、「Azure Files操作のタイムアウトの設定」を参照してください。
`prevsharesnapshot`	バージョン 2020-02-10 以降では省略可能。パラメーターは`prevsharesnapshot`不透明`DateTime`な値であり、存在する場合は前のスナップショットを指定します。このパラメーターと `sharesnapshot` が両方とも存在する場合、応答には 2 つのスナップショット間で変更されたページ範囲のみが含まれます。のみ`prevsharesnapshot`がある場合、応答には、このスナップショットとライブ共有の間で変更されたページ範囲のみが含まれます。変更されたページには、更新されたページとクリアされたページの両方が含まれます。

要求ヘッダー

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

要求ヘッダー	説明
`Authorization`	必須。承認スキーム、アカウント名、署名を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`Date` または `x-ms-date`	必須。要求に対して協定世界時 (UTC) を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`x-ms-version`	すべての承認された要求に必要です。この要求に使用する操作のバージョンを指定します。詳細については、「Azure Storage サービスのバージョン管理」を参照してください。
`Range`	省略可能。範囲を一覧表示するバイトの範囲を指定します。省略した場合は、ファイルのすべての範囲が返されます。
`x-ms-range`	省略可能。範囲を一覧表示するバイトの範囲を指定します。 `Range` ヘッダーと `x-ms-range` ヘッダーの両方が指定されている場合、サービスは `x-ms-range` の値を使用します。詳細については、「Azure Files操作の範囲ヘッダーの指定」を参照してください。
`x-ms-lease-id:<ID>`	省略可能。バージョン 2019-02-02 以降。ヘッダーを指定すると、ファイルのリースが現在アクティブであり、要求で指定されたリース ID がファイルのリース ID と一致する場合にのみ、操作が実行されます。それ以外の場合、操作は状態コード 412 (前提条件に失敗) で失敗します。
`x-ms-client-request-id`	省略可能。ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。詳細については、「Azure Filesの監視」を参照してください。
`x-ms-file-request-intent`	ヘッダーが OAuth トークンを指定する場合 `Authorization` は必須。許容される値はです `backup`。このヘッダーは、ヘッダーを`Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`使用して`Authorization`承認された ID に割り当てられた RBAC ポリシーに含まれている場合に、または `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` を許可するように指定します。バージョン 2022-11-02 以降で使用できます。
`x-ms-allow-trailing-dot: { <Boolean> }`	省略可能。バージョン 2022-11-02 以降。ブール値は、要求 URL に存在する末尾のドットをトリミングするかどうかを指定します。詳細については、「共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

要求本文

[なし] :

Response

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

status code

操作に成功すると、状態コード 200 (OK) が返されます。状態コードの詳細については、「状態とエラーコード」を参照してください。

応答ヘッダー

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

応答ヘッダー	説明
`Last-Modified`	ファイルが最後に更新された日時。ファイルを変更する操作 (ファイルのメタデータまたはプロパティの更新など) は、ファイルの最終変更時刻を変更します。
`ETag`	には `ETag` 、ファイルのバージョンを引用符で囲んで表す値が含まれています。
`x-ms-content-length`	ファイルのサイズ (バイト単位)。が存在する場合 `prevsharesnapshot` 、値はでファイルのサイズを `sharesnapshot` 表します (クエリパラメーターが存在する `sharesnapshot` 場合)。それ以外の場合は、ライブファイルのサイズが記述されます。
`x-ms-request-id`	このヘッダーは、行われた要求を一意に識別し、要求のトラブルシューティングに使用できます。詳細については、「 API 操作のトラブルシューティング」を参照してください。
`x-ms-version`	要求の実行に使用Azure Filesのバージョンを示します。
`Date` または `x-ms-date`	応答が開始された時刻を示す UTC 日付/時刻値。サービスによってこの値が生成されます。
`x-ms-client-request-id`	このヘッダーを使用して、要求と対応する応答のトラブルシューティングを行うことができます。このヘッダーの値は、要求に存在する `x-ms-client-request-id` 場合、ヘッダーの値と同じです。この値は、最大 1024 文字の ASCII 文字で表示されます。ヘッダーが `x-ms-client-request-id` 要求に存在しない場合、このヘッダーは応答に存在しません。

応答本文

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

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

ファイルの範囲のセット全体がクリアされている場合、応答本文には範囲は含まれません。

が指定されている場合prevsharesnapshot、応答には、ターゲットスナップショット (またはライブファイル) と前のスナップショットの間で異なるページのみが含まれます。返される範囲には、更新された範囲とクリアされた範囲の両方が含まれます。この応答の形式は次のとおりです。

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

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

承認

この操作を呼び出すことができるのは、アカウント所有者だけです。

解説

各範囲の開始と終了のバイトオフセットには、その開始値と終了値が含まれます。 Put Range の範囲更新操作と範囲クリア操作の例を参照してください。これらの例では、ファイルから 512 の非アラインバイト範囲を書き込むかクリアした場合に返される範囲を示します。

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

バージョン 2020-02-10 以降では、パラメーターを使用してをprevsharesnapshot呼び出List Rangesすことができます。これにより、ライブファイルとスナップショット間、またはスナップショット上のファイルの 2 つのスナップショット間で異なる範囲が返されます。これらの範囲の違いを使用すると、ファイルの増分スナップショットを取得できます。増分スナップショットは、独自のバックアップソリューションを実装する場合に、ファイルをバックアップするためのコスト効率の高い方法です。

増分スナップショットを取得するために呼び出されると、ファイルList Rangesに対する特定の操作が失敗します。サービスは次を返します。

404 (見つかりません) いずれかのスナップショットに存在しないファイルを呼び出す場合 (指定されていない場合 sharesnapshot はライブ)。
409 (競合) : によって指定された、スナップショットの後に上書きコピーの対象となったファイルをprevsharesnapshot呼び出す場合。
409 (競合) で指定されたスナップショットが取得された後に、同じ名前と場所で削除され、再作成されたファイルに対して prevsharesnapshot を呼び出した場合。