Put Range
Put Range 操作は、ファイルに特定範囲のバイトを書き込みます。
プロトコルの可用性
| 有効なファイル共有プロトコル | 使用可能 |
|---|---|
| SMB |
|
| NFS |
|
要求
Put Range 要求の構成は次のとおりです。 HTTPS を使用することをお勧めします。
| Method | 要求 URI | HTTP バージョン |
|---|---|---|
| PUT | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range |
HTTP/1.1 |
次のように、要求 URI に示されたパス コンポーネントを独自の URI に置き換えます。
| パス コンポーネント | 説明 |
|---|---|
myaccount |
ご利用のストレージ アカウントの名前。 |
myshare |
ファイル共有の名前。 |
mydirectorypath |
省略可能。 親ディレクトリへのパス。 |
myfile |
ファイルの名前です。 |
パスの名前付け制限の詳細については、「 名前と参照共有、ディレクトリ、ファイル、およびメタデータ」を参照してください。
URI パラメーター
次の追加パラメーターを要求の URI で指定できます。
| パラメーター | 説明 |
|---|---|
timeout |
省略可能。
timeout パラメーターは、秒単位で表されます。 詳細については、「 ファイル サービス操作のタイムアウトを設定する」を参照してください。 |
要求ヘッダー
必須の要求ヘッダーと省略可能な要求ヘッダーを次の表に示します。
| 要求ヘッダー | 説明 |
|---|---|
Authorization |
必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。 |
Date または x-ms-date |
必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。 |
x-ms-version |
すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。 |
Range または x-ms-range |
Range または x-ms-range が必須です。書き込まれるバイトの範囲を指定します。 範囲の開始値と終了値の両方を指定する必要があります。 このヘッダーは、 HTTP/1.1 プロトコル仕様によって定義されます。 更新操作の場合、範囲のサイズは最大 4 MiB です。 クリア操作では、範囲の最大サイズはファイル全体のサイズの値です。 File サービスは、 ヘッダーと x-ms-range ヘッダーの 1 バイト範囲Rangeのみを受け入れ、バイト範囲を 次の形式で指定する必要があります。 bytes=startByte-endByteRange と x-ms-range の両方が指定されている場合、サービスは x-ms-range の値を使用します。 詳細については、「 ファイル サービス操作の範囲ヘッダーを指定する」を参照してください。 |
Content-Length |
必須。 要求本文で送信されるバイト数を指定します。 ヘッダーが x-ms-write に clear設定されている場合、このヘッダーの値を に設定する 0必要があります。 |
Content-MD5 |
省略可能。 コンテンツの MD5 ハッシュ。 このハッシュは転送時のデータの整合性を確認するために使用します。 ヘッダーをContent-MD5指定すると、Azure Filesは、到着したコンテンツのハッシュと送信されたヘッダー値を比較します。 2 つのハッシュが一致しない場合、操作はエラー コード 400 (無効な要求) で失敗します。ヘッダーが Content-MD5 にclear設定されている場合、x-ms-writeヘッダーは許可されません。 要求に含まれている場合、ファイル サービスは状態コード 400 (無効な要求) を返します。 |
x-ms-write: { update ¦ clear } |
必須。 次のいずれかのオプションを指定する必要があります。
|
x-ms-lease-id: <ID> |
ファイルにアクティブなリースがある場合は必須です。 バージョン 2019-02-02 以降で使用できます。 |
x-ms-client-request-id |
省略可能。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Filesの監視」を参照してください。 |
x-ms-file-last-write-time: { now ¦ preserve } |
省略可能。 バージョン 2021-06-08 以降。 次のオプションのいずれかを指定できます。
|
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 に存在する末尾のドットをトリミングするかどうかを指定します。 詳細については、「共有、 ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。 |
要求本文
アップロードする範囲を表すデータ。
サンプル要求: バイト範囲を更新する
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. |
応答本文
[なし] :
応答のサンプル
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 (見つかりません) が返されます。
新しいファイルを作成するには、ファイルの作成を呼び出 します。 ファイルのサイズは最大 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 クライアントが を使用してx-ms-range操作で指定された範囲と重複するロックを持っている場合にPut Range失敗することをPut Range意味します。 詳細については、「 ファイル ロックの管理」を参照してください。
SMB クライアント ディレクトリ変更通知
SMB プロトコルは FindFirstChangeNotification API 関数をサポートしています。この API 関数を使用すると、アプリケーションはファイル システムでいつ変更が発生したのを検出できます。 ファイルまたはディレクトリがいつ追加、変更、または削除されたか、およびファイルのサイズ、属性、またはセキュリティ記述子が変更されたときに検出できます。 この API を使用する SMB クライアントは、Azure Files REST API を介してファイルまたはディレクトリの変更が行われると、通知を受け取りません。 ただし、他の SMB クライアントによる変更は通知を伝達します。
整列されていないクリア範囲のサンプル
ファイルが Create File で作成され、次のように 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) で失敗します。