取得檔案
Get File 作業會從系統讀取或下載檔案，包括其元數據和屬性。 啟用 NFS 通訊協定的檔案共用版本 2025-05-05 和更新版本支援這項作業。
通訊協定可用性
| 已啟用檔案共享通訊協定 | 可用 |
|---|---|
| SMB |
|
| NFS |
|
請求
Get File 要求建構方式如下。 建議您使用 HTTPS。
| 方法 | 要求 URI | HTTP 版本 |
|---|---|---|
| 獲取 | https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
將要求 URI 中顯示的路徑元件取代為您自己的路徑元件，如下所示：
| 路徑元件 | 描述 |
|---|---|
myaccount |
記憶體帳戶的名稱。 |
myshare |
檔案共享的名稱。 |
mydirectorypath |
自選。 目錄的路徑。 |
myfile |
檔名。 |
如需路徑命名限制的相關信息，請參閱 名稱和參考共用、目錄、檔案和元數據。
URI 參數
您可以在要求 URI 上指定下列其他參數：
| 參數 | 描述 |
|---|---|
timeout |
自選。
timeout 參數是以秒為單位來表示。 如需詳細資訊，請參閱 設定 Azure 檔案服務的逾時。 |
要求標頭
下表說明必要和選擇性的要求標頭：
常見的要求標頭
| 要求標頭 | 描述 |
|---|---|
Authorization |
必填。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱 授權對 Azure 記憶體的要求。 |
Date 或 x-ms-date |
必填。 指定要求的國際標準時間（UTC）。 如需詳細資訊，請參閱 授權對 Azure 記憶體的要求。 |
x-ms-version |
所有已授權要求的必要專案。 指定要用於此要求的作業版本。 啟用 NFS 通訊協定的檔案共用版本 2025-05-05 和更新版本支援這項作業。 如需詳細資訊，請參閱 Azure 記憶體服務的版本設定。 |
Range |
自選。 僅從指定的位元組範圍傳回檔案數據。 |
x-ms-range |
自選。 僅從指定的位元組範圍傳回檔案數據。 如果同時指定 Range 和 x-ms-range，服務會使用 x-ms-range的值。 如果未指定兩者，則會傳回整個檔案內容。 如需詳細資訊，請參閱 指定 Azure 檔案服務作業的範圍標頭。 |
x-ms-range-get-content-md5: true |
自選。 當此標頭設定為 true，且它與 Range 標頭一起指定時，服務會傳回範圍的 MD5 哈希，只要範圍小於或等於大小為 4 個 mebibytes （MiB）。如果未指定此標頭，但未指定 Range 標頭，服務會傳回狀態代碼 400 （不正確的要求）。如果此標頭設定為 true 範圍超過大小 4 MiB 時，服務會傳回狀態代碼 400 （不正確的要求）。 |
x-ms-lease-id:<ID> |
自選。 版本 2019-02-02 和更新版本。 如果指定標頭，則只有在檔案的租用目前為使用中，且要求中指定的租用標識符符合檔案的租用標識符時，才會執行作業。 否則，作業會失敗，狀態代碼為 412（前置條件失敗）。 如果檔案位於已啟用 NFS 通訊協定的檔案共用上，則不支援檔案租用，則會忽略此標頭。 |
x-ms-client-request-id |
自選。 提供客戶端產生的不透明值，其中包含設定記錄時記錄的 1-kibibyte （KiB） 字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊，請參閱 監視 Azure 檔案服務。 |
x-ms-file-request-intent |
如果 Authorization 標頭指定 OAuth 令牌，則為必要項。 可接受的值為 backup。 此標頭指定，如果 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 包含在指派給使用 Authorization 標頭授權的身分識別中，則應該授與這些 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action。 適用於 2022-11-02 版和更新版本。 |
x-ms-allow-trailing-dot: { <Boolean> } |
自選。 版本 2022-11-02 和更新版本。 布爾值會指定是否應該修剪要求 URL 中的尾端點。 如果目標位於已啟用 NFS 通訊協定的檔案共用上，預設支援尾端點，則會忽略此標頭。 如需詳細資訊，請參閱 命名和參考共用、目錄、檔案和元資料。 |
僅限SMB要求標頭
沒有。
僅限 NFS 要求標頭
沒有。
要求本文
沒有。
回應
回應包含 HTTP 狀態代碼、一組響應標頭，以及包含檔案內容的響應主體。
狀態代碼
成功的作業會傳回狀態代碼 200 （確定）。 如您需狀態代碼的相關資訊，請參閱 狀態和錯誤碼。
回應標頭
此作業的回應包含下表中的標頭。 回應也可以包含額外的標準 HTTP 標頭。 所有標準標頭都符合 HTTP/1.1 通訊協定規格，。
常見的響應標頭
| 回應標頭 | 描述 |
|---|---|
Last-Modified |
傳回上次修改檔案的日期和時間。 日期格式遵循 RFC 1123。 如需詳細資訊，請參閱 代表標頭中的日期/時間值。 修改檔案或其屬性的任何作業會更新上次修改的時間。 |
x-ms-meta-name:value |
與這個檔案相關聯的一組名稱/值組做為使用者定義元數據。 |
Content-Length |
響應主體中存在的位元組數目。 |
Content-Type |
為檔案指定的內容類型。 預設內容類型為 application/octet-stream。 |
Content-Range |
如果客戶端藉由設定 Range 要求標頭來要求檔案子集，則傳回的位元組範圍。 |
ETag |
包含值，可用來有條件地執行作業。 值會以引弧括住。 |
Content-MD5 |
如果檔案具有 MD5 哈希，而且要求是讀取完整檔案，則會傳回此回應標頭，讓用戶端可以檢查訊息內容完整性。 如果要求是讀取指定的範圍，且 x-ms-range-get-content-md5 設定為 true，則要求會傳回該範圍的 MD5 哈希，只要範圍大小小於或等於 4 MiB。如果這兩組條件都沒有 true，則不會傳回 Content-MD5 標頭的值。如果未指定 x-ms-range-get-content-md5 範圍標頭，服務會傳回狀態代碼 400 （不正確的要求）。如果當範圍超過 4 MiB 時， x-ms-range-get-content-md5 設定為 true，服務會傳回狀態代碼 400 （不正確的要求）。 |
Content-Encoding |
傳回為 Content-Encoding 要求標頭指定的值。 |
Content-Language |
傳回為 Content-Language 要求標頭指定的值。 |
Cache-Control |
如果先前已為檔案指定，則會傳回 。 |
Content-Disposition |
傳回為 x-ms-content-disposition 標頭指定的值，並指定如何處理回應。Content-Disposition 回應標頭字段會傳達有關如何處理響應承載的其他資訊，也可以用來附加其他元數據。 例如，如果設定為 attachment，Content-Disposition 表示使用者代理程式不應該顯示回應，但應該改為顯示 [另存新檔] 視窗。 |
x-ms-request-id |
可唯一識別提出的要求，並可用來針對要求進行疑難解答。 如需詳細資訊，請參閱 針對 API 作業進行疑難解答。 |
x-ms-version |
用來執行要求的服務版本。 |
Accept-Ranges: bytes |
表示服務支援部分檔案內容的要求。 |
Date |
Date |
x-ms-copy-completion-time:<datetime> |
版本 2015-02-21 和更新版本。 上次嘗試 複製檔案 作業的結束時間，此檔案是目的地檔案。 這個值可以指定完成、中止或失敗複製嘗試的時間。 如果復本擱置中、此檔案從未成為 複製檔案 作業中的目的地，或此檔案在結束 複製檔案 作業之後修改，則不會顯示此標頭，該作業使用 [設定檔案屬性] 或 [建立檔案]。 |
x-ms-copy-status-description: <error string> |
版本 2015-02-21 和更新版本。 只有在 x-ms-copy-status失敗 或 擱置時，才會顯示。 描述嚴重或非嚴重複製作業失敗的原因。 如果這個檔案從未在 複製檔案 作業中成為目的地，或此檔案在結束 複製檔案 作業之後修改，則不會顯示此標頭，該作業使用 [設定檔案屬性] 或 [建立檔案]。 |
x-ms-copy-id: <id> |
版本 2015-02-21 和更新版本。 上次嘗試的字串標識碼，複製檔案 作業，其中這個檔案是目的地檔案。 如果檔案從未在 複製檔案 作業中成為目的地，或是此檔案在結束 複製檔案 作業之後修改，則不會顯示此標頭，該作業使用 [設定檔案屬性] 或 [建立檔案]。 |
x-ms-copy-progress: <bytes copied/bytes total> |
版本 2015-02-21 和更新版本。 包含已複製的位元組數目，以及上次嘗試 複製檔案 作業中來源中的位元組總數，而此檔案是目的地檔案。 可以顯示從 0 到複製 Content-Length 位元組數目。 如果這個檔案從未在 複製檔案 作業中成為目的地，或此檔案在結束 複製檔案 作業之後修改，則不會顯示此標頭，該作業使用 [設定檔案屬性] 或 [建立檔案]。 |
x-ms-copy-source: url |
版本 2015-02-21 和更新版本。 長度高達 2 KB 的 URL，指定上次嘗試 複製檔案 作業中使用的來源檔案，此檔案是目的地檔案。 如果這個檔案從未成為 複製檔案 作業中的目的地，或此檔案在 複製檔案 作業之後修改，則不會顯示此標頭，該作業使用 [設定檔案屬性] 或 [建立檔案]。 |
x-ms-copy-status: <pending ¦ success ¦ aborted ¦ failed> |
版本 2015-02-21 和更新版本。
x-ms-copy-id所識別之複製作業的狀態，具有下列值：- pending：複製正在進行中。 檢查 x-ms-copy-status-description 間歇性、非嚴重錯誤是否妨礙複製進度，但不會造成失敗。- success：複製已順利完成。- aborted：複製已結束 中止複製檔案。- failed：複製失敗。 如需失敗詳細數據，請參閱 x-ms-copy-status-description。如果此檔案從未成為 複製檔案 作業中的目的地，或此檔案在完成 複製檔案 作業之後修改，則不會顯示此標頭，該作業使用 [設定檔案屬性] 或 [建立檔案]。 |
x-ms-content-md5 |
自 2016-05-31 版起，如果檔案具有 MD5 哈希，而且如果要求包含範圍標頭（range 或 x-ms-range），則會傳回此回應標頭，且其值為整個檔案的 MD5 值。 這個值可能或可能不等於 Content-MD5 標頭中傳回的值，此值是從要求的範圍計算而來。 |
x-ms-server-encrypted: true/false |
版本 2017-04-17 和更新版本。 如果檔案數據和應用程式元數據使用指定的演算法完全加密，則此標頭的值會設定為 true。 如果檔案未加密，或只有部分檔案/應用程式元資料已加密，則值會設定為 false。 |
x-ms-file-creation-time |
UTC 日期/時間值，表示檔案的建立時間屬性。 |
x-ms-file-last-write-time |
UTC 日期/時間值，表示檔案的最後一個寫入時間屬性。 |
x-ms-file-change-time |
代表檔案變更時間屬性的UTC日期/時間。 |
x-ms-file-file-id |
檔案的檔案識別碼。 |
x-ms-file-parent-id |
檔案的父檔案標識碼。 |
x-ms-lease-duration:infinite |
版本 2019-02-02 和更新版本。 當檔案租用時，指定租用是無限持續時間。 |
x-ms-lease-state: <available, leased, broken> |
版本 2019-02-02 和更新版本。 當檔案租用時，指定檔案的租用狀態。 |
x-ms-lease-status: <locked, unlocked> |
版本 2019-02-02 和更新版本。 當檔案租用時，指定檔案的租用狀態。 |
x-ms-client-request-id |
可用來針對要求及其對應的回應進行疑難解答。 如果此標頭存在於要求中，則這個標頭的值等於 x-ms-client-request-id 標頭的值，而且值包含不超過 1,024 個可見的 ASCII 字元。 如果要求中沒有 x-ms-client-request-id 標頭，它就不會出現在回應中。 |
僅限SMB回應標頭
| 回應標頭 | 描述 |
|---|---|
x-ms-file-permission-key |
版本 2019-02-02 和更新版本。 檔案許可權的索引鍵。 |
x-ms-file-attributes |
版本 2019-02-02 和更新版本。 檔案的檔案系統屬性。 如需詳細資訊，請參閱 的可用屬性清單。 |
僅限 NFS 回應標頭
| 回應標頭 | 描述 |
|---|---|
x-ms-mode |
版本 2025-05-05 和更新版本。 檔案的模式。 請參閱 POSIX 檔案權限 （mode）。 |
x-ms-owner |
版本 2025-05-05 和更新版本。 檔案擁有者的使用者識別碼 （UID）。 |
x-ms-group |
版本 2025-05-05 和更新版本。 檔案擁有者的群組標識碼 （GID）。 |
x-ms-link-count |
版本 2025-05-05 和更新版本。 檔案的連結計數。 |
回應本文
回應本文包含檔案的內容。
範例回應
Response Status:
HTTP/1.1 200 OK
Response Headers:
x-ms-type: File
x-ms-meta-m1: v1
x-ms-meta-m2: v2
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Date: <date>
ETag: "0x8CB171DBEAD6A6B"
Last-Modified: <date>
x-ms-version: 2019-02-02
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0
x-ms-copy-id: 36650d67-05c9-4a24-9a7d-a2213e53caf6
x-ms-copy-source: <url>
x-ms-copy-status: success
x-ms-copy-progress: 11/11
x-ms-copy-completion-time: <date>
x-ms-lease-duration: infinite
x-ms-lease-state: leased
x-ms-lease-status: locked
授權
只有帳戶擁有者可以呼叫這項作業。
檔案系統屬性
| 屬性 | Win32 檔案屬性 | 定義 |
|---|---|---|
| ReadOnly | FILE_ATTRIBUTE_READONLY | 唯讀的檔案。 應用程式可以讀取檔案，但無法寫入或刪除檔案。 |
| 隱藏 | FILE_ATTRIBUTE_HIDDEN | 檔案已隱藏。 它不包含在一般目錄清單中。 |
| 系統 | FILE_ATTRIBUTE_SYSTEM | 作系統使用 部分或獨佔使用的檔案。 |
| 沒有 | FILE_ATTRIBUTE_NORMAL | 未設定其他屬性的檔案。 此屬性只有在單獨使用時才有效。 |
| 檔案 | FILE_ATTRIBUTE_ARCHIVE | 檔案是封存盤案。 應用程式通常會使用這個屬性來標記檔案以進行備份或移除。 |
| 臨時 | FILE_ATTRIBUTE_TEMPORARY | 用於暫存記憶體的檔案。 |
| 離線 | FILE_ATTRIBUTE_OFFLINE | 檔案的數據無法立即取得。 此文件系統屬性主要是為了提供與 Windows 的相容性。 Azure 檔案記憶體不支援離線記憶體選項。 |
| NotContentIndexed | FILE_ATTRIBUTE_NOT_CONTENT_INDEXED | 檔案不會由內容索引服務編製索引。 |
| NoScrubData | FILE_ATTRIBUTE_NO_SCRUB_DATA | 背景數據完整性掃描器不會讀取用戶數據流。 此文件系統屬性主要是為了提供與 Windows 的相容性。 |
POSIX 檔案權限 （模式）
POSIX 檔案許可權可以用 12 位數值八進位格式或符號 “rwx” 格式來指定。 例子：
- “0644” 或 “rw-r--r--”： 使用者 （檔案擁有者） 具有讀取、寫入許可權。 群組具有讀取許可權。 其他人具有讀取許可權。
- “0755” 或 “rwxr-xr-x”：使用者（檔案擁有者）具有讀取、寫入和執行許可權。 群組具有讀取和執行許可權。 其他人具有讀取和執行許可權。
數值八進位格式
三個最低順序八進位數位代表擁有者/使用者、群組和其他使用者的許可權，並使用八進位數位（0-7）來表示，其格式為 '4' （Read）、'2' （Write）、'1' （Execute）。 最高順序八進位數 （0-7） 用來表示 '4' （SetUID）、'2' （SetGID）、'1' （StickyBit） 許可權的組合。
| 格式 | 許可 |
|---|---|
| 0700 | 使用者 （檔案擁有者） 具有讀取、寫入和執行許可權。 |
| 0400 | 使用者具有讀取許可權。 |
| 0200 | 使用者具有寫入許可權。 |
| 0100 | 使用者具有執行許可權。 |
| 0070 | 群組具有讀取、寫入和執行許可權。 |
| 0040 | 群組具有讀取許可權。 |
| 0020 | 群組具有寫入許可權。 |
| 0010 | 群組具有執行許可權。 |
| 0007 | 其他人具有讀取、寫入和執行許可權。 |
| 0004 | 其他人具有讀取許可權。 |
| 0002 | 其他人具有寫入許可權。 |
| 0001 | 其他人有執行許可權。 |
| 4000 | 在檔案上設定有效的使用者標識碼。 |
| 2000 | 在檔案上設定有效的群組標識碼。 |
| 1000 | 設定為 ，表示檔案只能由檔案擁有者、目錄擁有者或根使用者刪除或重新命名。 |
符號 “rwx” 格式
擁有者/使用者、群組和其他使用者的許可權會使用 'r' （Read）、'w' 和 'x' （Execute） 字元的組合來表示。
| 格式 | 許可 |
|---|---|
| rwx------ | 使用者 （檔案擁有者） 具有讀取、寫入和執行許可權。 |
| r-------- | 使用者具有讀取許可權。 |
| -w------- | 使用者具有寫入許可權。 |
| --x------ | 使用者具有執行許可權。 |
| ---rwx--- | 群組具有讀取、寫入和執行許可權。 |
| ---r----- | 群組具有讀取許可權。 |
| ----w---- | 群組具有寫入許可權。 |
| -----x--- | 群組具有執行許可權。 |
| ------rwx | 其他人具有讀取、寫入和執行許可權。 |
| ------r-- | 其他人具有讀取許可權。 |
| -------w- | 其他人具有寫入許可權。 |
| --------x | 其他人有執行許可權。 |
言論
針對尚未包含內容或已清除的範圍呼叫 Get File 會針對這些位元組傳回 0。
如果您呼叫 Get File 但未指定範圍，服務會傳回位元組範圍，最多傳回為 x-ms-content-length 標頭指定的值。 對於任何缺少內容的範圍，服務會針對這些位元組傳回 0。
每個MiB允許兩分鐘完成 Get File 作業。 平均每MiB花費超過兩分鐘的作業逾時。
另請參閱
檔案 上的 作業