次の方法で共有

範囲の配置

Put Range 操作は、バイト範囲をファイルに書き込みます。 この操作は、NFS プロトコルが有効になっているファイル共有のバージョン 2025-05-05 以降でサポートされています。

プロトコルの可用性

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

依頼

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

方式 要求 URI HTTP バージョン
置く https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range HTTP/1.1

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

パス コンポーネント 形容
myaccount ストレージ アカウントの名前。
myshare ファイル共有の名前。
mydirectorypath 随意。 親ディレクトリへのパス。
myfile ファイルの名前。

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

URI パラメーター

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

パラメーター 形容
timeout 随意。 timeout パラメーターは秒単位で表されます。 詳細については、「ファイル サービス操作のタイムアウトを設定する」を参照してください。

要求ヘッダー

必須および省略可能な要求ヘッダーについては、次の表で説明します。

一般的な要求ヘッダー

要求ヘッダー 形容
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 が必要です。

書き込むバイトの範囲を指定します。 範囲の開始と終了の両方を指定する必要があります。 このヘッダーは、HTTP/1.1 プロトコル仕様によって定義されます。

更新操作の場合、範囲のサイズは最大 4 MiB です。 明確な操作の場合、範囲はファイルのフル サイズの値まで指定できます。

File サービスは、Range ヘッダーと x-ms-range ヘッダーの 1 バイト範囲のみを受け入れ、バイト範囲は次の形式で指定する必要があります: bytes=startByte-endByte。

Range と x-ms-range の両方が指定されている場合、サービスは x-ms-rangeの値を使用します。 詳細については、「ファイル サービス操作の範囲ヘッダーを指定する」を参照してください。
Content-Length 必須。 要求本文で送信されるバイト数を指定します。 x-ms-write ヘッダーが clearに設定されている場合は、このヘッダーの値を 0に設定する必要があります。
Content-MD5 随意。 コンテンツの MD5 ハッシュ。 このハッシュは、トランスポート中にデータの整合性を検証するために使用されます。 Content-MD5 ヘッダーを指定すると、Azure Files は、到着したコンテンツのハッシュと送信されたヘッダー値を比較します。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (無効な要求) で失敗します。

x-ms-write ヘッダーが clearに設定されている場合、Content-MD5 ヘッダーは許可されません。 要求に含まれている場合、File サービスは状態コード 400 (無効な要求) を返します。
x-ms-write: { update ¦ clear } 必須。 次のいずれかのオプションを指定する必要があります。
  • update: 要求本文で指定されたバイトを指定された範囲に書き込みます。 更新を実行するには、Range ヘッダーと Content-Length ヘッダーが一致している必要があります。
  • clear: 指定した範囲をクリアし、その範囲の記憶域で使用されている領域を解放します。 範囲をクリアするには、Content-Length ヘッダーを 0に設定し、Range ヘッダーをクリアする範囲を示す値 (最大ファイル サイズまで) に設定します。
x-ms-lease-id:<ID> ファイルにアクティブなリースがある場合に必要です。 バージョン 2019-02-02 以降で使用できます。

このヘッダーは、ファイルが NFS プロトコルが有効になっているファイル共有上にあり、ファイル リースをサポートしていない場合は無視されます。
x-ms-client-request-id 随意。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。 詳細については、「Monitor Azure Files」を参照してください。
x-ms-file-last-write-time: { now ¦ preserve } 随意。 バージョン 2021-06-08 以降。 次のいずれかのオプションを指定できます。
  • now: 既定値。 最後の書き込み時刻のタイムスタンプを要求の時刻に更新します。
  • preserve: 既存の最後の書き込みタイムスタンプを変更せずに保持します。
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 プロトコルが有効なファイル共有上にある場合、このヘッダーは無視され、既定では末尾のドットがサポートされます。

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

SMB のみの要求ヘッダー

何一つ。

NFS 要求ヘッダーのみ

何一つ。

要求本文

アップロードする範囲を表すデータ。

要求のサンプル: バイト範囲を更新する

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-write: update  
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT  
x-ms-version: 2014-02-14  
x-ms-range: bytes=0-65535  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536

要求のサンプル: バイト範囲をクリアする

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-write: clear  
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT  
x-ms-version: 2014-02-14  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

応答

応答には、HTTP 状態コードと一連の応答ヘッダーが含まれます。

状態コード

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

応答ヘッダー

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

一般的な応答ヘッダー

応答ヘッダー 形容
ETag ETag には、ファイルのバージョンを表す値が含まれています。 値は引用符で囲まれています。
Last-Modified ディレクトリが最後に変更された日時を返します。 日付形式は RFC 1123 に従います。 詳細については、「ヘッダーの日付/時刻値を表す」を参照してください。 共有またはそのプロパティまたはメタデータを変更する操作は、最後に変更された時刻を更新します。 ファイルに対する操作は、共有の最終変更時刻には影響しません。
Content-MD5 このヘッダーは、クライアントがメッセージ コンテンツの整合性を確認できるように返されます。 このヘッダーの値は、File サービスによって計算されます。 要求ヘッダーで指定されている値と必ずしも同じではありません。
x-ms-request-id 作成された要求を一意に識別し、要求のトラブルシューティングに使用できます。 詳細については、「API 操作のトラブルシューティング」を参照してください。
x-ms-version 要求の実行に使用されたファイル サービスのバージョンを示します。
Date サービスによって生成される UTC 日付/時刻値。応答が開始された時刻を示します。
x-ms-request-server-encrypted: { true ¦ false } バージョン 2017-04-17 以降。 このヘッダーの値は、指定したアルゴリズムを使用して要求の内容が正常に暗号化された場合に true に設定されます。 それ以外の場合、値は falseに設定されます。
x-ms-client-request-id このヘッダーは、要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、1,024 文字以下の ASCII 文字が含まれている場合、x-ms-client-request-id ヘッダーの値と同じです。 x-ms-client-request-id ヘッダーが要求に存在しない場合、応答には存在しません。
x-ms-file-last-write-time バージョン 2021-06-08 以降。 ISO 8601 形式のファイルの最後の書き込み時刻。 例: 2017-05-10T17:52:33.9551861Z.

SMB のみの応答ヘッダー

何一つ。

NFS のみの応答ヘッダー

何一つ。

応答本文

何一つ。

応答のサンプル

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==  
Date:Mon, 27 Jan 2014 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT  
x-ms-version: 2014-02-14  
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

認可

アカウント所有者のみがこの操作を呼び出すことができます。

備考

Put Range 操作は、バイト範囲をファイルに書き込みます。 この操作は、既存のファイルでのみ呼び出すことができます。 新しいファイルを作成するために呼び出すことはできません。 現在存在しないファイル名で Put Range を呼び出すと、状態コード 404 (Not Found) が返されます。

新しいファイルを作成するには、ファイルの作成 呼び出します。 ファイルのサイズは最大 4 TiB です。

Put Range 操作は、MiB ごとに 10 分で完了できます。 操作に平均して MiB あたり 10 分を超える時間がかかる場合は、タイムアウトになります。

ファイルにアクティブなリースがある場合、クライアントは範囲を書き込む要求に有効なリース ID を指定する必要があります。

範囲の更新操作

Update オプションを指定して Put Range を呼び出すと、指定したファイルに対してインプレース書き込みが実行されます。 指定した範囲内のすべてのコンテンツは、更新プログラムで上書きされます。 更新操作の Put Range で送信される各範囲のサイズは最大 4 MiB です。 4 MiB を超える範囲をアップロードしようとすると、サービスは状態コード 413 (要求エンティティが大きすぎる) を返します。

範囲クリア操作

Clear オプションを指定して Put Range を呼び出すと、指定した範囲が 512 バイトアラインされている限り、ストレージ内の領域が解放されます。 クリアされた範囲はファイルの一部として追跡されなくなり、リスト範囲 応答では返されません。 指定した範囲が 512 バイトアラインされていない場合、操作は 512 バイトアラインされていない範囲の先頭または末尾にゼロを書き込み、その 512 バイトアライン内の残りの範囲を解放します。

クリアされていない範囲は、リスト範囲 応答で返されます。 例については、次の「整列されていないクリア範囲のサンプル」セクションを参照してください。

ファイル リース

リース ファイル を呼び出して、他の書き込みに対する排他的書き込みロックを無期限に取得できます。

SMB クライアントのバイト範囲ロック を する

SMB プロトコルを使用すると、バイト範囲ロックでファイルの領域への読み取りと書き込みのアクセスを管理できます。 つまり、SMB プロトコルが有効なファイル共有にあるファイルの Put Range は、SMB クライアントが、x-ms-rangeを使用して Put Range 操作で指定された範囲と重複するロックを持っている場合に失敗します。 詳細については、「ファイル ロックの管理」を参照してください。

NFS クライアントのバイト範囲ロック

NFS プロトコル POSIX バイト範囲ロックは本質的にアドバイザリであるため、NFS プロトコルが有効になっているファイル共有上にあるファイルの Put Range は、NFS クライアントによって保持されているバイト範囲ロックが競合していても失敗しません。

SMB クライアント ディレクトリ変更通知 を する

SMB プロトコルは、FindFirstChangeNotification API 関数をサポートしています。これにより、アプリケーションはファイル システムで変更がいつ発生するかを検出できます。 ファイルまたはディレクトリが追加、変更、または削除されたとき、およびファイルのサイズ、属性、またはセキュリティ記述子が変更されたときを検出できます。 この API を使用する SMB クライアントは、Azure Files REST API を介してファイルまたはディレクトリの変更が行われると、通知を受け取りません。 ただし、他の SMB クライアントによって発生した変更は、通知を伝達します。

サンプルの整列されていないクリア範囲

ファイルの作成 を使用してファイルが作成され、次のように 1 つの範囲が Put Rangeで書き込まれるとします。

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  

Request Headers:  
x-ms-write: updte  
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT  
x-ms-version: 2014-02-14  
x-ms-range: bytes=0-65536  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536

ファイルに対して リスト範囲 操作を実行すると、次の応答本文が返されます。

<?xml version="1.0" ecoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>65536</End>  
</Range>  
</Ranges>

次に、アライメントされていないクリア範囲のバイト範囲操作が実行されるとします。

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  

Request Headers:  
Range: bytes=768-2304  
x-ms-write: clear  
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT  
x-ms-version: 2014-02-14  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=

ファイルに対する後続の リスト範囲 操作は、次の応答本文を返します。

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>1024</End>  
</Range>  
<Range>  
<Start>2048</Start>  
<End>65535</End>  
</Range>  
</Ranges>

768-1024 および 2048-2304 からアラインされていないスペースにゼロが書き込まれたことに注意してください。

Put Range は、共有スナップショット (共有の読み取り専用コピー) ではサポートされていません。 共有スナップショットに対してこの操作を実行しようとすると、400 (InvalidQueryParameterValue) で失敗します。

関連項目

ファイル に対する 操作