List Ranges
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を呼び出した場合。