URL から範囲を配置する

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

この操作により Put Range From URL 、URL から内容が読み取られるファイルの一部としてコミットされる新しい範囲が作成されます。この API は、バージョン 2019-02-02 以降で使用できます。

プロトコルの可用性

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

Request

Put Range From URL 要求の構成は次のとおりです。 HTTPS を使用することをお勧めします。 myaccount をストレージアカウントの名前に置き換えます。

Method	要求 URI	HTTP バージョン
`PUT`	`https://myaccount.file.core.windows.net/myshare/myfile?comp=range`	HTTP/1.1

URI パラメーター

パラメーター	説明
`timeout`	省略可能。 `timeout` パラメーターは、秒単位で表されます。詳細については、「Azure Files操作のタイムアウトを設定する」を参照してください。

要求ヘッダー

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

要求ヘッダー	説明
`Authorization`	必須。承認スキーム、アカウント名、署名を指定します。詳細については、「 Azure Storage への要求を承認する」を参照してください。
`Date` または `x-ms-date`	必須。要求に対して協定世界時 (UTC) を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。
`x-ms-version`	すべての承認された要求に必要です。この要求に使用する操作のバージョンを指定します。詳細については、「Azure Storage サービスのバージョン管理」を参照してください。の場合 `Put Range From URL`、バージョンは 2019-02-02 以降である必要があります。
`x-ms-copy-source:name`	必須。ソースファイルの URL を指定します。値には、ファイルを指定する最大 2 KiB の URL を指定できます。この値は要求 URI に含まれるため、URL でエンコードされる必要があります。ソースファイルはパブリックであるか、共有アクセス署名を介して承認されている必要があります。ソースファイルがパブリックの場合、操作を実行するために承認は必要ありません。ソースオブジェクト URL の例を次に示します。 `https://myaccount.file.core.windows.net/myshare/mydir/myfile` `https://myaccount.file.core.windows.net/myshare/mydir/myfile?<sastoken>`
`x-ms-copy-source-authorization: <scheme> <signature>`	省略可能。コピーソースの承認スキームと署名を指定します。詳細については、「Azure Storage への要求を承認する」をご覧ください。 Azure Active Directory では、スキームベアラーのみがサポートされています。このヘッダーは、バージョン 2020-10-02 以降でサポートされています。
`x-ms-write: { update }`	必須。のみを指定 `update`する必要があります。で呼び出 `clear`された場合、要求は失敗します。値は `update` 、要求本文で指定されたバイトを指定された範囲に書き込みます。
`Range` または `x-ms-range`	必須。 `Range` または `x-ms-range` が必須です。書き込まれるバイトの範囲を指定します。範囲の開始値と終了値の両方を指定する必要があります。このヘッダーは、 HTTP/1.1 プロトコル仕様によって定義されます。更新操作の場合、範囲のサイズは最大 4 MiB です。 Azure Files では、ヘッダーと `x-ms-range` ヘッダーに対`Range`して 1 つのバイト範囲のみを受け入れ、バイト範囲は次の形式で指定する必要があります。 `bytes=startByte-endByte` `Range` と `x-ms-range` の両方が指定されている場合、サービスは `x-ms-range` の値を使用します。詳細については、「Azure Files操作の範囲ヘッダーを指定する」を参照してください。
`x-ms-source-range`	必須。ソースから読み取るバイトの範囲を指定します。範囲の開始値と終了値の両方を指定する必要があります。 Azure Files では、ヘッダーと `x-ms-range` ヘッダーに対`Range`して 1 つのバイト範囲のみを受け入れ、バイト範囲は次の形式で指定する必要があります。 `bytes=startByte-endByte` ソース範囲のサイズは最大 4 MiB です。ソース範囲のサイズが 4 MiB を超える場合、Azure Filesは状態コード 413 (要求エンティティが大きすぎます) を返します。ソース範囲のサイズが範囲 (ターゲット範囲) のサイズと一致しない場合、サービスは状態コード 400 (無効な要求) を返します。
`Content-Length`	必須。要求本文で送信されるバイト数を指定します。このヘッダーの値は `0` に設定する必要があります。長さがでない `0`場合、操作は状態コード 400 (無効な要求) で失敗します。
`x-ms-client-request-id`	省略可能。ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。詳細については、「Azure Filesの監視」を参照してください。
`x-ms-source-content-crc64`	省略可能。 URI から指定された範囲の CRC64 ハッシュ。このハッシュは、URI からのデータの転送中に範囲の整合性を確認するために使用されます。このヘッダーを指定すると、Azure Filesはコピー元から到着したコンテンツのハッシュをこのヘッダー値と比較します。注: この CRC64 ハッシュは、ファイルと共に格納されません。 2 つのハッシュが一致しない場合、エラーコード 400 (無効な要求) で操作が失敗します。
`x-ms-source-if-match-crc64`	省略可能。 CRC64 チェックサム値。ソースから読み取られた指定された範囲のチェックサムが指定されたチェックサムと一致する場合にのみ、このヘッダーを指定して操作を実行します。指定した条件が満たされていない場合、Azure Filesは状態コード 412 (前提条件に失敗しました) を返します。
`x-ms-source-if-none-match-crc64`	省略可能。 CRC64 チェックサム値。ソースから読み取られた指定された範囲のチェックサムが指定されたチェックサムと異なる場合にのみ、このヘッダーを指定して操作を実行します。指定した条件が満たされていない場合、Azure Filesは状態コード 412 (前提条件に失敗しました) を返します。
`x-ms-lease-id:<ID>`	ファイルにアクティブなリースがある場合は必須です。アクティブなリースを持つファイルに対してこの操作を実行するには、このヘッダーの有効なリース ID を指定します。
`x-ms-client-request-id`	省略可能。 Azure Storage Analytics ログが有効になっているときに分析ログに記録される、1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。クライアント側のアクティビティをサーバーが受信した要求と関連付ける場合は、このヘッダーを使用することを強くお勧めします。詳細については、「 Blob Storage の監視」を参照してください。
`x-ms-file-last-write-time: { now ¦ preserve }`	省略可能。バージョン 2021-06-08 以降。次のオプションのいずれかを指定できます。 `now`: 既定値。最後の書き込み時刻タイムスタンプを要求の時刻に更新します。 `preserve`: 既存の最後の書き込みタイムスタンプは変更しません。
`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 に存在する末尾のドットをトリミングするかどうかを指定します。詳細については、「共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。
`x-ms-source-allow-trailing-dot: { <Boolean> }`	省略可能。バージョン 2022-11-02 以降。ブール値は、ソース URL に存在する末尾のドットをトリミングするかどうかを指定します。このヘッダーは、コピーソースが Azure ファイルの場合にのみ指定する必要があります。このヘッダーは、他のコピーソースの種類ではサポートされていません。詳細については、「共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

要求本文

要求本文がありません。

要求のサンプル

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/mydir/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-copy-source: http://myaccount2.file.core.windows.net/myshare2/mydirectory2/myfile2?sv=2018-11-09&sp=r&sr=s&se=2018-08-22T09%3A59%3A28.2185790Z&sig=Qn6QEET3Gn%2FhCEVcXuwG7ssatIYiYRM5pNIy4Q3N0cQ%3D 
x-ms-date: Fri, 22 Aug 2018 01:15:50 GMT  
x-ms-version: 2019-02-02 
x-ms-range: bytes=100-1023  
x-ms-source-range: bytes=200-1123  
x-ms-source-content-crc64: 3bedb8b3730fc205 
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 0

Response

応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。

status code

操作が正常に終了すると、状態コード 201 (Created) が返されます。

状態コードの詳細については、「状態とエラーコード」を参照してください。

応答ヘッダー

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

応答ヘッダー	説明
`ETag`	条件付きで操作を実行するために使用できる値が含まれます。値は引用符で囲まれています。
`Last-Modified`	ファイルが最後に変更された日時。日付形式は RFC 1123 に従います。詳細については、「ヘッダー内の日付/時刻値の表現」を参照してください。ファイルに対する書き込み操作 (ファイルのメタデータまたはプロパティの更新を含む) は、ファイルの最終変更時刻を変更します。
`x-ms-request-id`	行われた要求を一意に識別し、それを使用して要求のトラブルシューティングを行うことができます。詳細については、「 API 操作のトラブルシューティング」を参照してください。
`x-ms-version`	要求の実行に使用された FileREST API バージョンを示します。
`Date`	サービスによって生成される UTC 日付/時刻値。応答が開始された時刻を示します。
`x-ms-content-crc64`	クライアントがメッセージコンテンツの整合性をチェックできるように返されます。このヘッダーの値は、Azure Filesによって計算されます。要求ヘッダーで指定された値と必ずしも同じとは限りません。
`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:
Date: Sun, 22 Aug 2020 01:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Wed, 22 Aug 2020 01:13:31 GMT  
x-ms-version: 2019-02-02
x-ms-content-crc64: 3bedb8b3730fc205 
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

承認

この操作は、アカウント所有者と、このファイルまたは Azure ファイル共有に書き込むアクセス許可を持つ共有アクセス署名を持つすべてのユーザーが呼び出すことができます。

解説

操作は Put Range From URL 、データの範囲をファイルに書き込みます。ターゲット上の存在しないファイルで API が呼び出された場合、API は HTTP 状態コード 404 (Not Found) を返します。

バージョン 2020-10-02 以降では、コピー操作のソースに対して Azure Active Directory 承認がサポートされています。

新しいファイルを作成するには、Create File を呼び出します。

Put Range From URL 指定した範囲がファイルに書き込まれた場合にのみ、operation は成功 201 (Created) を返します。

ファイル読み取り操作
Put Range From URL を使用 Get File して、ソースからデータとメタデータ、属性、ACL を読み取ります。

ファイルの更新操作
"update" オプションを指定してを呼び出すと Put Range From URL 、指定したファイルに対してインプレース書き込みが実行されます。指定したファイル内のすべてのコンテンツは、更新プログラムで上書きされます。  

更新操作の操作の Put Range From URL 範囲サイズは、最大 4 MiB のサイズにすることができます。 4 MiB を超える範囲をアップロードしようとすると、Azure Files状態コード 413 (RequestEntityTooLarge) が返されます。