清單句柄

發行項
02/20/2025

List Handles 作業會傳回目錄或檔案上開啟的句柄清單。或者，它可以遞歸列舉目錄和檔案上開啟的句柄。此 API 從 2018-11-09 版開始提供。

通訊協定可用性

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

請求

List Handles 要求建構方式如下。建議您使用 HTTPS。

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

以您自己的方式取代要求 URI 中顯示的路徑元件，如下所示：

路徑元件	描述
`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` 或 `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` 包含在指派給使用 `Authorization` 標頭授權的身分識別中，則此標頭指定應授與 `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` 或 `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action`。適用於 2022-11-02 版和更新版本。
`x-ms-allow-trailing-dot: { <Boolean> }`	自選。版本 2022-11-02 和更新版本。布爾值會指定是否應該修剪要求 URL 中的尾端點。如需詳細資訊，請參閱命名和參考共用、目錄、檔案和元資料。

要求本文

沒有。

回應

回應包含 HTTP 狀態代碼、一組響應標頭，以及 XML 格式的回應本文。

狀態代碼

成功的作業會傳回狀態代碼 200 （確定）。如您需狀態代碼的相關資訊，請參閱狀態和錯誤碼。

回應標頭

此作業的回應包含下表中的標頭。回應也可能包含額外的標準 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 回應的格式如下所示。請注意，只有在您在要求 URI 上指定 Marker、ShareSnapshot和 MaxResults 元素時，才會存在。只有當清單結果未完成時，NextMarker 元素才會有值。

回應中的 ClientName 字段是選擇性的，只有在服務可以使用時才傳回。

<?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>
            <ClientName>client-name</ClientName>
            <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>

下表描述回應主體的欄位：

田	描述	目的
`HandleId`	XSMB 服務句柄標識碼 UINT64。	用來識別句柄。
`Path`	檔名，包括從共用根目錄開始的完整路徑。字串。	用來識別開啟句柄的物件名稱。
`ClientIp`	開啟句柄的用戶端IP。字串。	用來決定句柄是否可能洩漏。
`ClientName`	選擇性欄位。 2024-02-04 和更新版本支援。開啟句柄的用戶端名稱（工作站或OS用戶名稱）。字串。	用來決定句柄是否可能洩漏。
`OpenTime`	時間句柄已開啟（UTC）。 `DateTime` 為 String。	用來決定句柄是否可能洩漏。洩漏的句柄通常會長時間開啟。
`LastReconnectTime`	時間句柄已開啟（UTC）。 `DateTime` 為 String。	用來決定是否在用戶端/伺服器中斷連線之後重新開啟句柄，因為網路或其他錯誤。只有當中斷連線事件發生且句柄重新開啟時，響應主體才會包含字段。
`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 元素值，其中含有 XML 中無效的字元（特別是 U+FFFE 或 U+FFFF）。如果編碼，Path 專案會包含 Encoded=true 屬性。請注意，這隻會發生在 xml 中含有無效字元的 Path 專案值，而不是回應中的其餘 Path 專案。

2024-02-04 版和更新版本支援 ClientName。

授權

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

言論

HandleId 是與用戶端句柄標識碼不同的服務端句柄標識碼。用戶端可以對應這兩者。

另請參閱

檔案上的作業
目錄上的作業

共用方式為