取得檔案
Get File 作業可從系統讀取或下載檔案，包括其中繼資料和屬性。
通訊協定可用性
| 已啟用檔案共用通訊協定 | 可用 |
|---|---|
| SMB |
|
| NFS |
|
要求
Get File 要求的建構如下。 建議您使用 HTTPS。
| 方法 | 要求 URI | HTTP 版本 |
|---|---|---|
GET |
https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile |
HTTP/1.1 |
以您自己的方式取代要求 URI 中顯示的路徑元件，如下所示：
| 路徑元件 | Description |
|---|---|
myaccount |
儲存體帳戶的名稱。 |
myshare |
檔案共用的名稱。 |
mydirectorypath |
選擇性。 目錄的路徑。 |
myfile |
檔案的名稱。 |
如需路徑命名限制的相關資訊，請參閱 名稱和參考共用、目錄、檔案和中繼資料。
URI 參數
您可以在要求 URI 上指定下列其他參數：
| 參數 | 描述 |
|---|---|
timeout |
選擇性。
timeout 參數以秒為單位。 如需詳細資訊，請參閱設定Azure 檔案儲存體作業的逾時。 |
要求標頭
下表說明必要的和選擇性要求標頭：
| 要求標頭 | 描述 |
|---|---|
Authorization |
必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。 |
Date 或 x-ms-date |
必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。 |
x-ms-version |
所有已授權要求都需要。 指定用於這個要求的作業版本。 如需詳細資訊，請參閱 Azure 儲存體服務的版本。 |
Range |
選擇性。 只從指定的位元組範圍傳回檔案資料。 |
x-ms-range |
選擇性。 只從指定的位元組範圍傳回檔案資料。 如果同時指定 Range 與 x-ms-range，服務會使用 x-ms-range 的值。 如果兩者都未指定，則會傳回整個檔案內容。 如需詳細資訊，請參閱指定Azure 檔案儲存體作業的範圍標頭。 |
x-ms-range-get-content-md5: true |
選擇性。 當此標頭設定為 true 且與 標頭一 Range 起指定時，只要範圍小於或等於 4 個位元組，服務就會傳回範圍的 MD5 雜湊，只要範圍小於或等於 4 個位元組， (MiB 大小) 。如果指定此標頭但未指定 Range 標頭，服務會傳回狀態碼 400 (不正確的要求)。如果此標頭設定 true 為 當範圍超過 4 MiB 大小時，服務會傳回狀態碼 400 (不正確的要求) 。 |
x-ms-lease-id:<ID> |
選擇性。 版本 2019-02-02 和更新版本。 如果指定標頭，則只有在檔案的租用目前為使用中，且要求中指定的租用識別碼符合檔案的租用識別碼時，才會執行作業。 否則，作業會失敗，狀態碼為 412 (前置條件失敗) 。 |
x-ms-client-request-id |
選擇性。 提供用戶端產生的不透明值，其中包含設定記錄時記錄的 1 kibibyte (KiB) 字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。 如需詳細資訊，請參閱監視Azure 檔案儲存體。 |
x-ms-file-request-intent |
如果 Authorization 標頭指定 OAuth 權杖，則為必要專案。 可接受的值為 backup 。 此標頭會 Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action 指定 ，如果在指派給使用 Authorization 標頭授權的身分識別的 RBAC 原則中包含 ，則應該授與 或 Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action 。 適用于 2022-11-02 版和更新版本。 |
x-ms-allow-trailing-dot: { <Boolean> } |
選擇性。 版本 2022-11-02 和更新版本。 布林值會指定是否應該修剪要求 URL 中的尾端點。 如需詳細資訊，請參閱 命名和參考共用、目錄、檔案和中繼資料。 |
要求本文
無。
回應
回應包括 HTTP 狀態碼、一組回應標頭，以及含有檔案內容的回應內文。
狀態碼
成功的作業會傳回狀態碼 200 (OK)。
如需狀態碼的相關資訊，請參閱 狀態和錯誤碼。
回應標頭
這項作業的回應包括下列標頭。 回應也可能包含額外的標準 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 (不正確的要求) 。如果 x-ms-range-get-content-md5 設定 true 為 當範圍超過 4 MiB 時，服務會傳回狀態碼 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-permission-key |
檔案許可權的索引鍵。 |
x-ms-file-attributes |
檔案上的檔案系統屬性。 如需詳細資訊，請參閱 可用屬性的清單。 |
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 |
可用來針對要求及其對應的回應進行疑難排解。 如果此標頭存在於要求中，且值包含不超過 1，024 個可見的 ASCII 字元，則此標頭的值等於 標頭的值 x-ms-client-request-id 。
x-ms-client-request-id如果標頭不存在於要求中，則它不會出現在回應中。 |
回應本文
回應本文包含檔案的內容。
範例回應
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
授權
只有帳戶擁有者可呼叫這項作業。
備註
在尚未包含內容或已清除這些位元組傳回 0 的範圍上呼叫 Get File 。
如果您在未指定範圍的情況下呼叫 Get File ，則服務會傳回位元組範圍，最多傳回為 x-ms-content-length 標頭指定的值。 對於缺少內容的任何範圍，服務會針對這些位元組傳 0 回。
Get File每個 MiB 都允許兩分鐘完成作業。 平均每 MiB 花費兩分鐘以上的作業將會逾時。