Snapshot Share (FileREST API) - Azure 檔案儲存體

發行項
02/07/2024

從 2017-04-17 版開始， Snapshot Share 作業會建立共用的唯讀快照集。

通訊協定可用性

已啟用檔案共享通訊協定	可用	狀態
SMB		GA
NFS		GA

要求

您可以建構 Snapshot Share 要求，如下所示。建議使用 HTTPS。

方法	要求 URI	HTTP 版本
`PUT`	`https://myaccount.file.core.windows.net/myshare?restype=share&comp=snapshot`	HTTP/1.1

將要求 URI 中的路徑元件取代為您自己的路徑元件，如下所示：

路徑元件	Description
`myaccount`	儲存體帳戶的名稱。
`myshare`	檔案共用的名稱。

如需路徑命名限制的詳細資訊，請參閱命名和參考共用、目錄、檔案和元數據。

URI 參數

您可以在要求 URI 上指定下列額外參數。

參數	描述
`timeout`	選擇性。 `timeout` 參數以秒為單位。如需詳細資訊，請參閱設定 Azure 檔案儲存體作業的逾時。

要求標頭

下表描述必要的和選用的要求標頭。

要求標頭	描述
`Authorization`	必要。指定授權配置、帳戶名稱和簽章。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`Date` 或 `x-ms-date`	必要。指定要求的國際標準時間 (UTC)。如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
`x-ms-version`	所有已授權要求都需要。指定用於這個要求的作業版本。如需詳細資訊，請參閱 Azure 儲存體服務的版本。
`x-ms-meta-name:value`	選擇性。指定與共用快照集相關聯的用戶定義名稱/值組。如果您未指定任何名稱/值組，作業會將基底共用元數據複製到快照集。如果您指定一或多個名稱/值組，則會使用指定的元數據來建立共用快照集。在此情況下，元數據不會從基底共享複製。元數據名稱必須遵守 C# 識別碼的命名規則。
`x-ms-client-request-id`	選擇性。提供客戶端產生的不透明值，其中包含 1 kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。強烈建議您使用此標頭，將用戶端活動與伺服器接收的要求相互關聯。如需詳細資訊，請參閱監視 Azure Blob 儲存體。

要求本文

無。

範例要求

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare?restype=share&comp=snapshot HTTP/1.1

Request Headers:
x-ms-version: 2017-04-17
x-ms-date: Mon, 10 May 2017 22:50:32 GMT
x-ms-meta-Name: StorageSample
Authorization: SharedKey myaccount:Z5043vY9MesKNh0PNtksNc9nbXSSqGHueE00JdjidOQ=

回應

回應包括 HTTP 狀態碼和一組回應標頭。

狀態碼

成功的作業會傳回狀態碼「201 (已建立)」。如需狀態代碼的相關信息，請參閱狀態和錯誤碼。

回應標頭

這項作業的回應包括下列標頭。回應也可以包含額外的標準 HTTP 標頭。所有標準標頭都符合 HTTP/1.1 通訊協議規格。

回應標頭	描述
`ETag`	包含值，以引號表示共用快照集的版本。無法修改共用快照集，因此 `ETag` 特定共用快照集的永遠不會變更。不過，如果您使用要求提供新的元數據 `Snapshot Share` ，則 `ETag` 共用快照集的與基底共用的元數據不同。如果您未使用要求指定任何元數據， `ETag` 則共用快照集的與基底共用的相同，在建立共用快照集時。
`Last-Modified`	傳回上次修改共用的日期和時間。如需詳細資訊，請參閱標頭中的日期時間值表示。無法修改共用快照集，因此特定共用快照集的最後一次修改時間永遠不會變更。不過，如果您使用要求提供新的元數據 `Snapshot Share` ，則共用快照集的上次修改時間與基底共用的時間不同。如果您未使用要求指定任何元數據，共用快照集的上次修改時間會與建立共用快照集時的共用快照集相同。
`x-ms-request-id`	可唯一識別提出的要求，並可用於對要求進行疑難解答。如需詳細資訊，請參閱針對 API 作業進行疑難解答。
`x-ms-version`	指出用來執行要求的 Azure 檔案儲存體版本。
`Date` 或 `x-ms-date`	UTC 日期/時間值，指出起始響應的時間。服務會產生此值。
`x-ms-snapshot`	可唯一 `DateTime` 識別共用快照集的值。您可以在後續要求中使用此標頭的值來存取共用快照集。這個值不透明。
`x-ms-client-request-id`	可用來針對要求和對應的回應進行疑難解答。如果此標頭存在於要求中，則此標頭的值等於標頭的值 `x-ms-client-request-id` 。此值最多為 1,024 個可見的 ASCII 字元。 `x-ms-client-request-id`如果要求中沒有標頭，它就不會出現在回應中。

回應本文

無。

範例回應

Response Status:
HTTP/1.1 201 Created

Response Headers:
Content-Length: 0
Date: Mon, 10 May 2017 23:00:12 GMT
ETag: "0x8CB14C3E29B7E82"
Last-Modified: Mon, 10 May 2017 23:00:06 GMT
x-ms-version: 2017-04-17
x-ms-snapshot: 2017-05-10T17:52:33.9551861Z
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0

授權

只有帳戶擁有者可以呼叫這項作業。

備註

共用快照集提供共用的唯讀版本。建立共用快照集之後，就無法加以修改。共用快照集提供方便的方式，可在共用上建立所有檔案的一致備份。

每次呼叫 Snapshot Share 作業時，都會建立新的共用快照集，並具有唯 DateTime 一值，可識別與其基底共用相對的共用快照集。您可以使用此值 DateTime 對共用快照集及其內容執行進一步的作業。您應該將此值 DateTime 視為不透明。

值 DateTime 會識別要求 URI 上的共用快照集。例如，基底共用及其快照集上的檔案具有類似下列範例的 URI：

共用上的檔案： http://myaccount.file.core.windows.net/myshare/myfile
共用快照集上的檔案： http://myaccount.file.core.windows.net/myshare/myfile?sharesnapshot=<DateTime>

共用可以支援建立 200 個共用快照集。如果您嘗試建立超過 200 個共用快照集，服務會傳回錯誤碼 409 (衝突) 。如果您在先前 Snapshot Share 的作業正在進行時嘗試建立共用快照集，服務也會傳回錯誤碼 409 (Conflict) 。

永遠不會覆寫現有的共用快照集。必須明確刪除它們。若要明確刪除共用快照集，請呼叫Delete Share並將標頭以及sharesnapshot查詢參數設定x-ms-include-snapshots為適當的值。

快照集共用