次の方法で共有

リスト ハンドル

  • [アーティクル]

操作は List Handles 、ディレクトリまたはファイルで開いているハンドルの一覧を返します。 必要に応じて、ディレクトリとファイルで開かれたハンドルを再帰的に列挙できます。 この API は、バージョン 2018-11-09 以降で使用できます。

プロトコルの可用性

有効なファイル共有プロトコル 利用可能
SMB はい
NFS いいえ

要求

要求は List Handles 次のように構築できます。 HTTPS が推奨されます。

Method 要求 URI HTTP バージョン
GET https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles HTTP/1.1

次のように、要求 URI に示されたパス コンポーネントを独自の URI に置き換えます。

パス コンポーネント 説明
myaccount ご利用のストレージ アカウントの名前。
myshare ファイル共有の名前。
mydirectorypath 省略可能。 ディレクトリへのパス。
myfileordirectory ファイルまたはディレクトリの名前。

パスの名前付けの制限の詳細については、「 共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

URI パラメーター

URI には、次の追加パラメーターを指定できます。

パラメーター 説明
marker 省略可能。 次 List Handles の操作で返されるリストの部分を識別する文字列値。 返されたリストが完了していない場合、操作は応答本文内のマーカー値を返します。 その後、後続の呼び出しでマーカー値を使用して、リスト アイテムの次のセットを要求できます。

マーカー値はクライアントに対して非透過的です。
maxresults 省略可能。 返されるファイルまたはディレクトリに対して取得されるハンドルの最大数を指定します。

maxresults をゼロ以下の値に設定すると、エラー応答コード 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) 文字制限を使用して、クライアントによって生成された不透明な値を提供します。 このヘッダーを使用して、クライアント側のアクティビティとサーバーが受信する要求を関連付けるよう強くお勧めします。 詳細については、「Azure Filesの監視」を参照してください。
x-ms-recursive 省略可能。 URI で指定されたディレクトリのファイルとサブディレクトリにも操作を適用するかどうかを指定するブール値。
x-ms-file-request-intent ヘッダーが OAuth トークンを指定する場合 Authorization は必須です。 許容される値は です backup。 このヘッダーは、 ヘッダーをMicrosoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action使用してAuthorization承認された ID に割り当てられた RBAC ポリシーに 含まれている場合に、 または Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action を許可するように指定します。 バージョン 2022-11-02 以降で使用できます。
x-ms-allow-trailing-dot: { <Boolean> } 省略可能。 バージョン 2022-11-02 以降。 ブール値は、要求 URL に存在する末尾のドットをトリミングするかどうかを指定します。 詳細については、「共有、 ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

要求本文

[なし] :

Response

応答には 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 、リストの結果が完全でない場合にのみ値があります。

<?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>

次の表では、応答本文のフィールドについて説明します。

フィールド 説明 目的
HandleId XSMB サービス ハンドル ID、UINT64。 ハンドルを識別するために使用されます。
Path 共有ルートから始まるファイル名 (完全パスを含む)。 文字列。 ハンドルが開いているオブジェクトの名前を識別するために使用されます。
ClientIp ハンドルを開いたクライアント IP。 文字列。 ハンドルがリークされた可能性があるかどうかを判断するために使用されます。
OpenTime タイム ハンドルが開かれた (UTC)。 DateTime を String として指定します。 ハンドルがリークされた可能性があるかどうかを判断するために使用されます。 リークしたハンドルは、通常、長い間開いています。
LastReconnectTime タイム ハンドルが開かれた (UTC)。 DateTime を String として指定します。 ネットワークまたはその他の障害が原因で、クライアント/サーバーの切断後にハンドルが再度開かれたかどうかを判断するために使用されます。 フィールドは、切断イベントが発生し、ハンドルが再度開かれた場合にのみ、応答本文に含まれます。
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 残りの Path 要素ではなく、XML で無効な文字を含む要素値に対してのみ発生することに注意してください。

承認

この操作を呼び出すことができるのは、アカウント所有者だけです。

解説

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

関連項目