清單控點

  • 發行項

作業 List Handles 會傳回目錄或檔案上開啟控制碼的清單。 您可以選擇性地列舉目錄和檔案上開啟的控制碼。 此 API 從 2018-11-09 版開始提供。

通訊協定可用性

已啟用檔案共用通訊協定 可用
SMB 是
NFS 否

要求

您可以依照下列方式建構 List Handles 要求。 建議使用 HTTPS。

方法 要求 URI HTTP 版本
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles HTTP/1.1

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

路徑元件 Description
myaccount 儲存體帳戶的名稱。
myshare 檔案共用的名稱。
mydirectorypath 選擇性。 目錄的路徑。
myfileordirectory 檔案或目錄的名稱。

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

URI 參數

您可以在 URI 上指定下列其他參數。

參數 描述
marker 選擇性。 字串值，識別要以下一個 List Handles 作業傳回的清單部分。 如果傳回的清單未完成，此作業會在回應本文內傳回標記值。 然後，您可以在後續呼叫中使用標記值來要求下一組清單專案。

此標記值對於用戶端為不透明。
maxresults 選擇性。 指定要傳回之檔案或目錄的控制碼數目上限。

若將 maxresults 設為小於或等於零的值，將會產生錯誤回應碼 400 (不正確的要求)。
timeout 選擇性。 timeout 參數以秒為單位。 如需詳細資訊，請參閱設定Azure 檔案儲存體作業的逾時。
sharesnapshot 選擇性。 參數 sharesnapshot 是不透明的 DateTime 值，當存在時，會指定要查詢控制碼清單的共用快照集。

要求標頭

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

要求標頭 描述
Authorization 必要。 指定授權配置、帳戶名稱和簽章。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
Date 或 x-ms-date 必要。 指定要求的「國際標準時間」(UTC)。 如需詳細資訊，請參閱授權對 Azure 儲存體提出要求。
x-ms-version 所有授權要求都需要 ，匿名要求則為選擇性。 指定用於這個要求的作業版本。 如需詳細資訊，請參閱 Azure 儲存體服務的版本。
x-ms-client-request-id 選擇性。 提供用戶端產生的不透明值，其中包含 1-kibibyte (KiB) 設定記錄時記錄在記錄中的字元限制。 強烈建議您使用此標頭，將用戶端活動與伺服器收到的要求相互關聯。 如需詳細資訊，請參閱監視Azure 檔案儲存體。
x-ms-recursive 選擇性。 布林值，指定作業是否也應該套用至 URI 中所指定目錄的檔案和子目錄。
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 狀態碼、一組回應標頭和 XML 格式的回應主體。

狀態碼

成功的作業會傳回狀態碼 200 (OK)。 如需狀態碼的相關資訊，請參閱 狀態和錯誤碼。

回應標頭

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

回應標頭 描述
Content-Type 指定傳回結果的格式。 目前此值為 application/xml。
x-ms-request-id 此標頭可唯一識別已提出的要求，並可用於對要求進行疑難排解。 如需詳細資訊，請參閱 針對 API 作業進行疑難排解。
x-ms-version 指出用來執行要求的Azure 檔案儲存體版本。
Date UTC 日期/時間值，指出起始回應的時間。 服務會產生此值。
x-ms-client-request-id 您可以使用此標頭來針對要求和對應的回應進行疑難排解。 如果此標頭存在於要求中，這個標頭的值會等於標頭的值 x-ms-client-request-id 。 此值最多為 1024 個可見的 ASCII 字元。 x-ms-client-request-id如果要求中沒有標頭，則此標頭不會出現在回應中。

回應本文

XML 回應的格式如下。 請注意， Marker 只有在您在要求 URI 上指定 、 ShareSnapshot 和 MaxResults 元素時，才會存在。 只有在清單結果未完成時，專案 NextMarker 才會有值。

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults>
    <HandleList>
        <Handle>
            <HandleId>handle-id</HandleId>
            <Path>file-or-directory-name-including-full-path</Path>
            <FileId>file-id</FileId>
            <ParentId>parent-file-id</ParentId>
            <SessionId>session-id</SessionId>
            <ClientIp>client-ip</ClientIp>
            <OpenTime>opened-time</OpenTime>
            <LastReconnectTime>lastreconnect-time</LastReconnectTime>
            <AccessRightList>
                <AccessRight>Read</AccessRight>
                <AccessRight>Write</AccessRight>
                <AccessRight>Delete</AccessRight>
            </AccessRightList>
        </Handle>
        ...
    </HandleList>
    <NextMarker>next-marker</NextMarker>
</EnumerationResults>

下表描述回應本文的欄位：

欄位 Description 目的
HandleId XSMB 服務控制碼識別碼 UINT64。 用來識別控制碼。
Path 檔案名，包括從共用根目錄開始的完整路徑。 字串。 用來識別開啟控制碼的物件名稱。
ClientIp 開啟控制碼的用戶端 IP。 字串。 用來判斷控制碼是否可能已外泄。
OpenTime 時間控制碼已開啟 (UTC) 。 DateTime 做為字串。 用來判斷控制碼是否可能外泄。 外泄的控制碼通常已開啟很長一段時間。
LastReconnectTime 時間控制碼已開啟 (UTC) 。 DateTime 做為字串。 用來決定因為網路或其他錯誤，在用戶端/伺服器中斷連線之後是否重新開啟控制碼。 只有在發生中斷線上活動並重新開啟控制碼時，回應本文才會包含欄位。
FileId 檔案識別碼 UINT64。 FileId 可唯一識別檔案。 在重新命名期間很有用，因為 FileId 不會變更。
ParentId 父檔案識別碼 UINT64。 ParentId 可唯一識別目錄。 這在重新命名期間很有用，因為 ParentId 不會變更。
SessionId SMB 會話識別碼，指定開啟檔案控制代碼的內容。 UINT64。 SessionId 當會話強制中斷連線時，事件檢視器記錄中會包含此記錄檔。 它可讓您將特定批次外泄的控制碼與特定網路事件產生關聯。
AccessRightList 授與檔案或目錄上開啟控制碼的存取權限。 可在服務 2023-01-03 版和更新版本中取得。

用來透過各種開啟控制碼查詢檔案或目錄上保留的存取權限。 可能的值為 READ、WRITE 和 DELETE，或這些值的組合。
NextMarker 字串，描述要列出的下一個控制碼。 當需要列出更多控制碼才能完成要求時，就會傳回它。 字串會用於後續的要求中，以列出剩餘的控制碼。 缺少 NextMarker 表示已列出所有相關控制碼。

在 2021-12-02 版和更新版本中， List Handles 每個 RFC 2396 () 所有 Path 包含 (字元不正確專案值，特別是 U+FFFE 或 U+FFFF) 。 如果編碼，專案 Path 將包含 Encoded=true 屬性。 請注意，這只會針對 Path XML 中含有無效字元的專案值進行，而不是回應中的其餘 Path 元素。

授權

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

備註

HandleId是與用戶端控制碼識別碼不同的服務端控制碼識別碼。 兩者之間的對應可以在用戶端進行。

另請參閱