ファイルのコピー
この操作により Copy File 、BLOB またはファイルがストレージ アカウント内のコピー先ファイルにコピーされます。
バージョン 2015-02-21 以降で使用できます。
プロトコルの可用性
| 有効なファイル共有プロトコル | 利用可能 |
|---|---|
| SMB |  |
| NFS |  |
Request
要求は Copy File 次のように構築できます。 HTTPS をお勧めします。
バージョン 2013-08-15 以降では、コピー先ファイルがソース ファイルと同じアカウントにある場合は、共有アクセス署名を指定できます。 バージョン 2015-04-05 以降では、宛先ファイルが別のストレージ アカウントにある場合は、共有アクセス署名を指定することもできます。
| Method | 要求 URI | HTTP バージョン |
|---|---|---|
PUT |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
次のように、要求 URI に示されたパス コンポーネントを独自の URI に置き換えます。
| パス コンポーネント | 説明 |
|---|---|
myaccount |
ご利用のストレージ アカウントの名前。 |
myshare |
ファイル共有の名前。 |
mydirectorypath |
省略可能。 親ディレクトリへのパス。 |
myfile |
ファイルの名前です。 |
パスの名前付けの制限の詳細については、「 共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。
URI パラメーター
次の追加パラメーターを要求 URI に指定できます。
| パラメーター | 説明 |
|---|---|
timeout |
省略可能。 timeout パラメーターは、秒単位で表されます。 詳細については、「Azure Files操作のタイムアウトを設定する」を参照してください。 |
要求ヘッダー
次の表では、必須および省略可能な要求ヘッダーについて説明します。
| 要求ヘッダー | 説明 |
|---|---|
Authorization |
必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。 |
Date または x-ms-date |
必須。 要求に対して協定世界時 (UTC) を指定します。 詳細については、「Azure Storage への要求を承認する」をご覧ください。 |
x-ms-version |
すべての承認された要求に必要です。 この要求に使用する操作のバージョンを指定します。 この操作は、バージョン 2015-02-21 以降でのみ使用できます。 詳細については、「Azure Storage サービスのバージョン管理」を参照してください。 |
x-ms-meta-name:value |
省略可能。 ファイルに関連付けられている名前と値のペアをメタデータとして指定します。 名前と値のペアが指定されていない場合、操作はメタデータをソース BLOB またはファイルからコピー先ファイルにコピーします。 1 つ以上の名前と値のペアを指定すると、指定したメタデータを使用してコピー先ファイルが作成され、メタデータはソース BLOB またはファイルからコピーされません。 メタデータ名は 、C# 識別子の名前付け規則に従う必要があります。 Azure Filesを介して指定されたファイル メタデータには、SMB クライアントからアクセスできません。 |
x-ms-copy-source:name |
必須。 ソース ファイルまたは BLOB の URL を指定します。最大 2 kibibytes (KiB) の長さです。 同じストレージ アカウント内の別のファイルにファイルをコピーするには、共有キーを使用してソース ファイルを承認できます。 別のストレージ アカウントからファイルをコピーする場合、または同じストレージ アカウントまたは別のストレージ アカウントから BLOB をコピーする場合は、共有アクセス署名を使用してソース ファイルまたは BLOB を承認する必要があります。 ソースがパブリック BLOB の場合、コピー操作を実行するための承認は必要ありません。 共有スナップショット内のファイルをコピー ソースとして指定することもできます。 ソース オブジェクト URL の例を次に示します。
|
x-ms-lease-id:<ID> |
コピー先ファイルにアクティブなリースがある場合は必須です。 バージョン 2019-02-02 以降で使用できます。 このヘッダーに指定するリース ID は、宛先ファイルのリース ID と一致している必要があります。 要求にリース ID が含まれていない場合、または ID が有効でない場合、操作は状態コード 412 (前提条件に失敗) で失敗します。 このヘッダーが指定されていて、宛先ファイルに現在アクティブなリースがない場合、操作は状態コード 412 (前提条件に失敗) で失敗します。 |
x-ms-file-permission-copy-mode: { source ¦ override } |
省略可能。 バージョン 2019-07-07 以降で使用できます。 ファイルのセキュリティ記述子のコピー動作を決定します。
|
x-ms-file-permission |
が としてoverridex-ms-file-permission-key指定され、 が指定されていない場合x-ms-file-permission-copy-modeは必須です。 バージョン 2019-07-07 以降で使用できます。 このアクセス許可は、 セキュリティ記述子定義言語 (SDDL) で指定されたファイルのセキュリティ記述子です。 このヘッダーは、アクセス許可のサイズが 8 kibibytes (KiB) 以下の場合に使用できます。 それ以外の場合は、 を使用 x-ms-file-permission-keyできます。 指定する場合は、所有者、グループ、随 意アクセス制御リスト (DACL) が必要です。 または x-ms-file-permission-key の x-ms-file-permission 1 つだけを指定できることに注意してください。 |
x-ms-file-permission-key |
が としてoverridex-ms-file-permission指定され、 が指定されていない場合x-ms-file-permission-copy-modeは必須です。 バージョン 2019-07-07 以降で使用できます。 このヘッダーは、ファイルに設定するアクセス許可のキーを指定します。 このキーは、 操作を使用 Create Permission して作成できます。または x-ms-file-permission-key の x-ms-file-permission 1 つだけを指定できることに注意してください。 |
x-ms-file-copy-ignore-readonly |
省略可能。 バージョン 2019-07-07 以降で使用できます。 このブール値は、既存の ReadOnly 変換先ファイルの属性を尊重するかどうかを指定します。 の true場合、コピー操作は成功します。 それ以外の場合、属性が設定されたコピー先の前の ReadOnly ファイルでは、コピー操作が失敗します。 |
x-ms-file-attributes |
省略可能。 バージョン 2019-07-07 以降で使用できます。 このヘッダーは、変換先ファイルに設定するファイル システム属性を指定します。 使用可能な属性の一覧を参照してください。 の source 値を使用して、ソース ファイルからコピー先ファイルに属性をコピーできます。 の値 none を使用して、変換先ファイルのすべての属性をクリアできます。 |
x-ms-file-creation-time |
省略可能。 バージョン 2019-07-07 以降で使用できます。 このヘッダーは、変換先ファイルに設定する作成時刻のプロパティを UTC で指定します。 の source 値を使用して、作成時刻をソース ファイルからコピー先ファイルにコピーできます。 |
x-ms-file-last-write-time |
省略可能。 バージョン 2019-07-07 以降で使用できます。 このヘッダーは、最終書き込み時刻のプロパティを UTC で指定して、変換先ファイルに設定します。 の値 source を使用して、ソース ファイルからコピー先ファイルに最後の書き込み時刻をコピーできます。 |
x-ms-file-copy-set-archive |
省略可能。 バージョン 2019-07-07 以降で使用できます。 このブール値は、ヘッダー値に Archive 関係なく x-ms-file-attributes 、属性を設定する必要があるかどうかを指定します。 |
x-ms-client-request-id |
省略可能。 ログ記録の構成時にログに記録される 1 KiB 文字の制限を持つ、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Blob Storageの監視」を参照してください。 |
x-ms-file-change-time: { <DateTime> ¦ source } |
省略可能。 バージョン 2021-06-08 以降。 ISO 8601 形式で書式設定されたファイルの UTC 変更時刻プロパティ。 の値 source を使用して、ソース ファイルから変換先ファイルに変更時刻をコピーできます。 既定のタイム スタンプは、要求の時刻です。 |
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 ファイルの場合にのみ指定する必要があります。 このヘッダーは、他のコピー ソースの種類ではサポートされていません。 詳細については、「共有、 ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。 |
要求本文
なし。
[応答]
応答には、HTTP 状態コードおよび一連の応答ヘッダーが含まれています。
状態コード
操作が正常に終了すると、ステータス コード 202 (Accepted) が返されます。
状態コードの詳細については、「 状態とエラー コード」を参照してください。
応答ヘッダー
この操作の応答には、次のヘッダーが含まれています。 応答には追加の標準 HTTP ヘッダーも含まれます。 すべての標準ヘッダーは 、HTTP/1.1 プロトコル仕様に準拠しています。
| 応答ヘッダー | 説明 |
|---|---|
ETag |
コピー操作が完了した場合は、コピー先ファイルの ETag 値が格納されます。 コピー操作が完了していない場合は、操作の開始時に ETag 作成された空のファイルの値が格納されます。 |
Last-Modified |
コピー先ファイルへのコピー操作が完了した日付/時刻を返します。 |
x-ms-request-id |
行われた要求を一意に識別します。 このヘッダーを使用して、要求のトラブルシューティングを行うことができます。 詳細については、「 API 操作のトラブルシューティング」を参照してください。 |
x-ms-version |
要求の実行に使用されるAzure Filesのバージョンを示します。 |
Date |
サービスが応答を送信した時刻を示す UTC 日付/時刻値。 |
x-ms-copy-id: <id> |
このコピー操作の文字列識別子を提供します。 または Get File Properties を使用Get Fileして、このコピー操作の状態をチェックするか、 を にAbort Copy File渡して保留中のコピー操作を取り消します。 |
x-ms-copy-status: <success ¦ pending> |
コピー操作の状態を次の値で示します。 - success: コピー操作が正常に完了しました。- pending: コピー操作はまだ進行中です。 |
x-ms-client-request-id |
要求と対応する応答のトラブルシューティングに使用できます。 このヘッダーの値は、要求に存在し、その値が最大 1,024 文字の ASCII 文字で表示される場合、ヘッダーの値 x-ms-client-request-id と等しくなります。 ヘッダーが x-ms-client-request-id 要求に存在しない場合、このヘッダーは応答に存在しません。 |
応答本文
なし
応答のサンプル
Response Status:
HTTP/1.1 202 Accepted
Response Headers:
Last-Modified: <date>
ETag: "0x8CEB669D794AFE2"
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402
x-ms-version: 2015-02-21
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5
x-ms-copy-status: pending
Date: <date>
承認
この操作は、アカウント所有者、または宛先ファイルまたはその共有に書き込むアクセス許可を持つ共有アクセス署名を持つクライアントによって呼び出すことができます。 要求で指定された共有アクセス署名は、宛先ファイルにのみ適用されることに注意してください。
ソース ファイルまたは BLOB へのアクセスは、要求ヘッダー の詳細で説明されているように、個別に承認されます x-ms-copy-source。
次の表は、操作の宛先オブジェクトとソース オブジェクトを承認する方法を Copy File 示しています。
| ファイル | 共有キーまたは共有キー Lite を使用した承認 | Shared Access Signature を使用した承認 | 承認を必要としないパブリック オブジェクト |
|---|---|---|---|
| [送信先ファイル] | はい | はい | 適用なし |
| 同じアカウント内のソース ファイル | はい | はい | 適用なし |
| 別のアカウントのソース ファイル | いいえ | はい | 適用なし |
| 同じアカウントまたは別のアカウント内のソース BLOB | いいえ | はい | はい |
ファイル システム属性
| 属性 | Win32 ファイル属性 | 定義 |
|---|---|---|
ReadOnly |
FILE_ATTRIBUTE_READONLY |
ファイルが読み取り専用です。 アプリケーションはファイルを読み取ることができますが、ファイルに書き込んだり削除したりすることはできません。 |
Hidden |
FILE_ATTRIBUTE_HIDDEN |
ファイルが非表示になっています。 通常のディレクトリ一覧には含まれません。 |
System |
FILE_ATTRIBUTE_SYSTEM |
オペレーティング システムはファイルの一部を使用するか、ファイルを排他的に使用します。 |
None |
FILE_ATTRIBUTE_NORMAL |
ファイルに他の属性が設定されていません。 この属性は、単独で使用される場合にのみ有効です。 |
Archive |
FILE_ATTRIBUTE_ARCHIVE |
ファイルはアーカイブ ファイルです。 通常、アプリケーションでは、この属性を使用して、バックアップまたは削除のためにファイルをマークします。 |
Temporary |
FILE_ATTRIBUTE_TEMPORARY |
ファイルは一時ストレージに使用されています。 |
Offline |
FILE_ATTRIBUTE_OFFLINE |
ファイルのデータはすぐには使用できません。 このファイル システム属性は、主に Windows との互換性を提供します。 Azure Filesでは、オフライン ストレージ オプションではサポートされていません。 |
NotContentIndexed |
FILE_ATTRIBUTE_NOT_CONTENT_INDEXED |
コンテンツ インデックス作成サービスは、ファイルのインデックスを作成しません。 |
NoScrubData |
FILE_ATTRIBUTE_NO_SCRUB_DATA |
バックグラウンド データ整合性スキャナーは、ユーザー データ ストリームを読み取りません。 このファイル システム属性は、主に Windows との互換性を提供します。 |
解説
操作は Copy File 非同期的に完了できます。 応答ヘッダーから返されるx-ms-copy-idコピー ID を使用して、コピー操作の状態をチェックしたり、取り消したりできます。 Azure Filesは、ベスト エフォートベースでファイルをコピーします。
コピー先ファイルが存在する場合は、上書きされます。 コピー操作の進行中は、コピー先ファイルを変更できません。
操作では Copy File 、常にソース BLOB またはファイル全体がコピーされます。 バイト範囲またはブロックのセットのコピーはサポートされていません。
操作のソースには、Copy File共有スナップショットに存在するファイルを指定できます。 操作の宛先をCopy File共有スナップショットに存在するファイルにすることはできません。
コピー操作のソースが値を提供 ETag するとき、操作の進行中にソースに変更がある場合は失敗します。 コピー操作の進行中にコピー先ファイルを変更しようとすると、状態コード 409 (競合) で失敗します。
ETag操作の開始時に変換先ファイルの値がCopy File変更されます。 コピー操作中も頻繁に変更されます。
プロパティとメタデータのコピー
BLOB またはファイルをコピーすると、次のシステム プロパティが同じ値でコピー先ファイルにコピーされます。
Content-TypeContent-EncodingContent-LanguageContent-LengthCache-ControlContent-MD5Content-Disposition
コピー先ファイルは、常にソース BLOB またはファイルと同じサイズです。 コピー先ファイルのヘッダーの Content-Length 値は、ソース BLOB またはファイルのヘッダーの値と一致します。
リースされた BLOB またはファイルをファイルにコピーする
操作は Copy File ソース BLOB またはファイルからのみ読み取るので、ソース オブジェクトのリースは操作に影響しません。 操作の Copy File 開始時に ETag 、ソース BLOB またはファイルの値が保存されます。 コピー操作が ETag 完了する前に値が変更された場合、操作は失敗します。 コピー操作中にファイルをリースすることで、ファイルのソース BLOB の変更を防ぐことができます。
転送先ファイルにアクティブな無限リースがある場合は、操作の呼び出しでリース ID を指定する Copy File 必要があります。 コピー操作が保留中の間、コピー先ファイルのリース操作は状態コード 409 (競合) で失敗します。 コピー操作中に、コピー元と異なる名前のコピー先ファイルにコピーする場合でも、ソースと同じ名前のコピー先ファイルにコピーする場合でも、コピー先ファイルの無限リースはこのようにロックされます。 クライアントがまだ存在しないファイルのリース ID を指定した場合、Azure Filesは状態コード 412 (前提条件に失敗しました) を返します。
保留中のコピー操作の操作
操作は Copy File 、ファイルの非同期コピーを完了する場合があります。 次の表を使用して、返される状態コードに基づいて次の手順を Copy File 決定します。
| 状態コード | 意味 |
|---|---|
| 202 (Accepted), x-ms-copy-status: success | コピー操作が正常に完了しました。 |
| 202 (Accepted), x-ms-copy-status: pending | コピー操作が完了していません。 を使用 Get File Properties してコピー先 BLOB をポーリングし、コピー操作が完了するか失敗するまで調べます x-ms-copy-status 。 |
| 4xx、500、または 503 | コピー操作に失敗しました。 |
操作中および操作後 Copy File 、コピー先ファイルのプロパティには、操作の Copy File コピー ID と、ソース BLOB またはファイルの URL が含まれます。 操作が完了すると、Azure Filesは時刻と結果の値 (success、、failedまたは aborted) をコピー先ファイルのプロパティに書き込みます。 操作に結果がある failed 場合、 x-ms-copy-status-description ヘッダーにはエラー詳細文字列が含まれます。
保留中 Copy File の操作には、2 週間のタイムアウトがあります。 コピー試行が 2 週間経過しても完了せず、空のファイルにフィールドが設定failedされ、x-ms-status-descriptionフィールドが 500 (OperationCancelled) に設定されたままになりますx-ms-copy-status。 コピー操作中に発生する可能性のある致命的でない断続的なエラーは、操作の進行状況を妨げる可能性がありますが、失敗の原因にならない可能性があります。 このような場合は、x-ms-copy-status-description によって断続的なエラーが記述されます。
コピー操作中にコピー先ファイルを変更しようとすると、状態コード 409 (競合)、"進行中のファイルのコピー" で失敗します。
操作を Abort Copy File 呼び出すと、ヘッダーが x-ms-copy-status:aborted 表示されます。 コピー先ファイルには、そのままのメタデータと 0 バイトのファイル長が含まれます。 に対して元の呼び出しを Copy File 繰り返して、操作をもう一度試すことができます。
課金
操作の Copy File 宛先アカウントは、1 つのトランザクションが操作を開始するために課金されます。 コピー先アカウントでは、コピー操作の状態を取り消すか要求する要求ごとに 1 つのトランザクションも発生します。
ソース ファイルまたは BLOB が別のアカウントにある場合、ソース アカウントにはトランザクション コストが発生します。 さらに、送信元アカウントと移行先アカウントが異なるリージョン (米国北部や米国南部など) に存在する場合、要求の転送に使用する帯域幅は、エグレスとしてソース アカウントに課金されます。 同じ地域内のアカウント間の送信は無料です。