次の方法で共有

範囲を一覧表示する

  • [アーティクル]

List Ranges 操作は、ファイルの有効な範囲の一覧を返します。 この操作は、NFS プロトコルが有効になっているファイル共有のバージョン 2025-05-05 以降でサポートされています。

プロトコルの可用性

有効なファイル共有プロトコル 利用できる
SMB はい
NFS はい

依頼

List Ranges 要求は次のように構成されます。 HTTPS を使用することをお勧めします。

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

次のように、要求 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 すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 この操作は、NFS プロトコルが有効になっているファイル共有のバージョン 2025-05-05 以降でサポートされています。

詳細については、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 (前提条件に失敗) で失敗します。

このヘッダーは、ファイルが NFS プロトコルが有効になっているファイル共有上にあり、ファイル リースをサポートしていない場合は無視されます。
x-ms-client-request-id 随意。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。 詳細については、「Monitor Azure Files」を参照してください。
x-ms-file-request-intent ヘッダー Authorization OAuth トークンを指定する場合は必須です。 許容される値は backupです。 このヘッダーは、Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action または Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action が、Authorization ヘッダーを使用して承認された ID に割り当てられた RBAC ポリシーに含まれている場合に付与されるように指定します。 バージョン 2022-11-02 以降で使用できます。
x-ms-allow-trailing-dot: { <Boolean> } 随意。 バージョン 2022-11-02 以降。 ブール値は、要求 URL に存在する末尾のドットをトリミングするかどうかを指定します。

ターゲットが NFS プロトコルが有効なファイル共有上にある場合、このヘッダーは無視され、既定では末尾のドットがサポートされます。

詳細については、「共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。
x-ms-file-support-rename: { <Boolean> } 随意。 バージョン 2024-05-04 以降でサポートされています。 このヘッダーは、クエリ パラメーター prevsharesnapshot 存在する場合にのみ使用できます。 ブール値は、前のスナップショット内のファイルの場所が要求 URI の場所と異なる場合に、名前の変更または移動操作の結果として、ファイルの変更された範囲を一覧表示するかどうかを決定します。 値が true の場合、ファイルの有効な変更された範囲が返されます。 値が false の場合、操作は 409 (競合) 応答で失敗します。 既定値は false です。

SMB のみの要求ヘッダー

何一つ。

NFS 要求ヘッダーのみ

何一つ。

要求本文

何一つ。

応答

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

状態コード

操作が成功すると、状態コード 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 ヘッダーが要求に存在しない場合、このヘッダーは応答に存在しません。

SMB のみの応答ヘッダー

何一つ。

NFS のみの応答ヘッダー

何一つ。

応答本文

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

<?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 で指定されたスナップショットが作成された後。

関連項目

ファイル に対する 操作