次の方法で共有

リスト ハンドル

  • [アーティクル]

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 を 0 以下の値に設定すると、エラー応答コード 400 (Bad Request) が発生します。
timeout 随意。 timeout パラメーターは秒単位で表されます。 詳細については、「Azure Files 操作のタイムアウトの設定」を参照してください。
sharesnapshot 随意。 sharesnapshot パラメーターは不透明な DateTime 値であり、存在する場合は、ハンドルの一覧を照会する共有スナップショットを指定します。

要求ヘッダー

次の表では、必須の要求ヘッダーと省略可能な要求ヘッダーについて説明します。

要求ヘッダー 形容
Authorization 必須。 承認スキーム、アカウント名、署名を指定します。 詳細については、「Azure Storageへの要求を承認する」を参照してください。
Date または x-ms-date 必須。 要求の世界協定時刻 (UTC) を指定します。 詳細については、「Azure Storageへの要求を承認する」を参照してください。
x-ms-version すべての承認された要求に必要です。匿名要求の場合は省略可能です。 この要求に使用する操作のバージョンを指定します。 詳細については、Azure Storage サービス のバージョン管理のに関するページを参照してください。
x-ms-client-request-id 随意。 ログ記録の構成時にログに記録される 1 kibibyte (KiB) 文字制限を持つクライアント生成の不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティと、サーバーが受信する要求を関連付けすることを強くお勧めします。 詳細については、「Monitor Azure Files」を参照してください。
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 ヘッダーを使用して承認された ID に割り当てられた RBAC ポリシーに含まれている場合に付与されるように指定します。 バージョン 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 Files のバージョンを示します。
Date 応答が開始された時刻を示す UTC 日付/時刻値。 サービスによってこの値が生成されます。
x-ms-client-request-id このヘッダーを使用して、要求と対応する応答のトラブルシューティングを行うことができます。 このヘッダーの値は、要求に存在する場合、x-ms-client-request-id ヘッダーの値と同じです。 値は最大 1024 文字の ASCII 文字です。 x-ms-client-request-id ヘッダーが要求に存在しない場合、このヘッダーは応答に存在しません。

応答本文

XML 応答の形式は次のとおりです。 Marker、ShareSnapshot、および MaxResults 要素は、要求 URI で指定した場合にのみ存在します。 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 サービス ハンドル ID、UINT64。 ハンドルを識別するために使用されます。
Path 共有ルートから始まるファイル名 (完全なパスを含む)。 糸。 ハンドルが開いているオブジェクトの名前を識別するために使用されます。
ClientIp ハンドルを開いたクライアント IP。 糸。 ハンドルがリークされた可能性があるかどうかを判断するために使用されます。
ClientName 省略可能なフィールド。 2024-02-04 以降でサポートされます。 ハンドルを開いたクライアント名 (ワークステーションまたは OS ユーザー名)。 糸。 ハンドルがリークされた可能性があるかどうかを判断するために使用されます。
OpenTime タイム ハンドルが開かれました (UTC)。 文字列として DateTime します。 ハンドルがリークされた可能性があるかどうかを判断するために使用されます。 リークしたハンドルは、通常、長い間開いています。
LastReconnectTime タイム ハンドルが開かれました (UTC)。 文字列として DateTime します。 ネットワークまたはその他の障害が原因で、クライアント/サーバーの切断後にハンドルが再度開かれたかどうかを判断するために使用されます。 フィールドは、切断イベントが発生し、ハンドルが再度開かれた場合にのみ、応答本文に含まれます。
FileId ファイル ID、UINT64。 FileId ファイルを一意に識別します。 FileId は変更されないため、名前の変更時に便利です。
ParentId 親ファイル ID、UINT64。 ParentId ディレクトリを一意に識別します。 これは、ParentId が変更されないため、名前の変更時に役立ちます。
SessionId ファイル ハンドルが開かれたコンテキストを指定する SMB セッション ID。 UINT64。 セッションが強制的に切断された場合、SessionId はイベント ビューアー ログに含まれます。 これにより、リークしたハンドルの特定のバッチを特定のネットワーク インシデントに関連付けることができます。
AccessRightList ファイルまたはディレクトリの開いているハンドルに付与されるアクセス許可。 サービス バージョン 2023-01-03 以降で使用できます。

さまざまな開いているハンドルによってファイルまたはディレクトリに保持されているアクセス許可を照会するために使用されます。 指定できる値は、READ、WRITE、DELETE、またはこれらの値の組み合わせです。
NextMarker 一覧表示する次のハンドルを記述する文字列。 要求を完了するためにさらにハンドルを一覧表示する必要がある場合に返されます。 この文字列は、後続の要求で残りのハンドルを一覧表示するために使用されます。 NextMarker が存在しない場合は、関連するすべてのハンドルが一覧表示されたことを示します。

バージョン 2021-12-02 以降では、List Handles は XML (具体的には U+FFFE または U+FFFF) で無効な文字を含むすべての Path 要素値をパーセントエンコードします (RFC 2396)。 エンコードされた場合、Path 要素には Encoded=true 属性が含まれます。 これは、応答の残りの Path 要素ではなく、XML で無効な文字を含む Path 要素の値に対してのみ発生することに注意してください。

ClientName は、バージョン 2024-02-04 以降でサポートされています。

認可

アカウント所有者のみがこの操作を呼び出すことができます。

備考

HandleId はサービス側ハンドル ID であり、クライアント ハンドル ID とは異なります。 2 つの間のマッピングは、クライアントで可能です。

関連項目