Listafogantyúk

Cikk
02/22/2025

A List Handles művelet egy könyvtár vagy fájl megnyitott fogópontjainak listáját adja vissza. Opcionálisan rekurzívan számba tudja adni a megnyitott leírókat a könyvtárakon és fájlokon. Ez az API a 2018-11-09-es verziótól érhető el.

Protokoll rendelkezésre állása

Engedélyezett fájlmegosztási protokoll	Beszerezhető
SMB
NFS

Kérés

A List Handles kérés a következőképpen jön létre. Javasoljuk, hogy HTTPS-t használjon.

Módszer	URI kérése	HTTP-verzió
KAP	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

Cserélje le a kérelem URI-jában látható elérésiút-összetevőket a sajátjára az alábbiak szerint:

Elérésiút-összetevő	Leírás
`myaccount`	A tárfiók neve.
`myshare`	A fájlmegosztás neve.
`mydirectorypath`	Szabadon választható. A könyvtár elérési útja.
`myfileordirectory`	A fájl vagy könyvtár neve.

Az útvonalelnevezési korlátozásokról további információt Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.

URI-paraméterek

Az URI-n a következő további paramétereket adhatja meg.

Paraméter	Leírás
`marker`	Szabadon választható. Sztringérték, amely a következő `List Handles` művelettel azonosítja a visszaadni kívánt listarészt. A művelet egy jelölőértéket ad vissza a válasz törzsében, ha a visszaadott lista nem fejeződött be. Ezt követően egy későbbi hívásban a jelölőérték használatával kérheti le a listaelemek következő készletét. A jelölő értéke átlátszatlan az ügyfél számára.
`maxresults`	Szabadon választható. Megadja a visszaadni kívánt fájlokon vagy könyvtárakon alkalmazott leírók maximális számát. Ha a `maxresults` nullánál kisebb vagy egyenlő értékre állítja, a 400-ás hibaválaszkód (hibás kérelem) jelenik meg.
`timeout`	Szabadon választható. A `timeout` paraméter másodpercben van kifejezve. További információ: Azure Files-műveletek időtúllépéseinek beállítása.
`sharesnapshot`	Szabadon választható. A `sharesnapshot` paraméter egy átlátszatlan `DateTime` érték, amely jelen esetben megadja a leírók listájához lekérdezendő megosztási pillanatképet.

Kérelemfejlécek

Az alábbi táblázat a szükséges és választható kérelemfejléceket ismerteti.

Kérelem fejléce	Leírás
`Authorization`	Szükséges. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérelmek engedélyezése az Azure Storage-.
`Date` vagy `x-ms-date`	Szükséges. A kérelem koordinált egyetemes idejét (UTC) adja meg. További információ: Kérelmek engedélyezése az Azure Storage-.
`x-ms-version`	Az összes engedélyezett kéréshez kötelező, a névtelen kérésekhez nem kötelező. A kérelemhez használni kívánt művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`x-ms-client-request-id`	Szabadon választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kibibyte (KiB) karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel. További információ: Monitor Azure Files.
`x-ms-recursive`	Szabadon választható. Logikai érték, amely meghatározza, hogy a műveletet az URI-ban megadott könyvtár fájljaira és alkönyvtáraira is alkalmazni kell-e.
`x-ms-file-request-intent`	Kötelező, ha `Authorization` fejléc OAuth-jogkivonatot ad meg. Az elfogadható érték `backup`. Ez a fejléc azt határozza meg, hogy a `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` vagy `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` meg kell adni, ha azok szerepelnek a `Authorization` fejléc használatával engedélyezett identitáshoz rendelt RBAC-szabályzatban. A 2022-11-02-es és újabb verziókhoz érhető el.
`x-ms-allow-trailing-dot: { <Boolean> }`	Szabadon választható. 2022-11-02-es és újabb verzió. A logikai érték azt határozza meg, hogy a kérelem URL-címében található záró pont levágható-e vagy sem. További információ: Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.

Kérelem törzse

Egyik sem.

Válasz

A válasz tartalmaz egy HTTP-állapotkódot, egy válaszfejléceket és egy XML formátumú választörzset.

Állapotkód

A sikeres művelet a 200-ra (OK) vonatkozó állapotkódot adja vissza. Az állapotkódokkal kapcsolatos információkért lásd állapot- és hibakódokat.

Válaszfejlécek

A műveletre adott válasz az alábbi táblázatban szereplő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmazhat. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának .

Gyakori fejlécek

Válaszfejléc	Leírás
`Content-Type`	Azt a formátumot adja meg, amelyben az eredmények vissza lesznek adva. Ez az érték jelenleg `application/xml`.
`x-ms-request-id`	Ez a fejléc egyedileg azonosítja a végrehajtott kérést, és a kérés hibaelhárításához használható. További információ: API-műveletek hibaelhárítása.
`x-ms-version`	A kérés futtatásához használt Azure Files-verziót jelzi.
`Date`	UTC dátum/idő érték, amely a válasz indításának időpontját jelzi. A szolgáltatás létrehozza ezt az értéket.
`x-ms-client-request-id`	Ezzel a fejlécmel elháríthatja a kéréseket és a megfelelő válaszokat. Ennek az élőfejnek az értéke megegyezik a `x-ms-client-request-id` fejléc értékével, ha az szerepel a kérelemben. Az érték legfeljebb 1024 látható ASCII-karakter lehet. Ha a `x-ms-client-request-id` fejléc nem szerepel a kérelemben, akkor ez a fejléc nem jelenik meg a válaszban.

Válasz törzse

Az XML-válasz formátuma a következő. Vegye figyelembe, hogy a Marker, ShareSnapshotés MaxResults elemek csak akkor jelennek meg, ha a kérelem URI-ján megadta őket. A NextMarker elem csak akkor rendelkezik értékkel, ha a lista eredményei nem fejeződnek be.

ClientName válaszmező nem kötelező, és csak akkor adja vissza, ha elérhető a szolgáltatás számára.

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

Az alábbi táblázat a válasz törzsének mezőit ismerteti:

Mező	Leírás	Cél
`HandleId`	XSMB szolgáltatás leíróazonosítója, UINT64.	A leíró azonosítására szolgál.
`Path`	A fájlnév, beleértve a teljes elérési utat is, a megosztás gyökerétől kezdve. Húr.	Annak az objektumnak a nevének azonosítására szolgál, amelynek a leírója meg van nyitva.
`ClientIp`	Ügyfél IP-címe, amely megnyitotta a leírót. Húr.	Annak eldöntésére szolgál, hogy kiszivároghatott-e a fogópont.
`ClientName`	Nem kötelező mező. 2024-02-04-ben és újabb verziókban támogatott. A leírót megnyitó ügyfélnév (munkaállomás vagy operációsrendszer-felhasználónév). Húr.	Annak eldöntésére szolgál, hogy kiszivároghatott-e a fogópont.
`OpenTime`	Megnyílt az időfogantyú (UTC). `DateTime` sztringként.	Annak eldöntésére szolgál, hogy kiszivároghatott-e a fogópont. A kiszivárgott fogópontok általában hosszú ideig nyitva voltak.
`LastReconnectTime`	Megnyílt az időfogantyú (UTC). `DateTime` sztringként.	Annak eldöntésére szolgál, hogy a leíró újra meg lett-e nyitva az ügyfél/kiszolgáló kapcsolatának megszakadása után, hálózati vagy egyéb hibák miatt. A mező csak akkor szerepel a válasz törzsében, ha a leválasztási esemény történt, és a leíró újra meg lett nyitva.
`FileId`	Fájlazonosító, UINT64.	`FileId` egyedileg azonosítja a fájlt. Az átnevezések során hasznos, mert a `FileId` nem változik.
`ParentId`	Szülőfájl azonosítója, UINT64.	`ParentId` egyedileg azonosítja a könyvtárat. Ez az átnevezések során hasznos, mert a `ParentId` nem változik.
`SessionId`	SMB-munkamenet-azonosító, amely megadja a fájlleíró megnyitásának környezetét. UINT64.	`SessionId` akkor szerepel az eseménynaplókban, ha a munkamenetek kényszerítve vannak leválasztva. Lehetővé teszi a kiszivárgott fogópontok adott kötegének társítását egy adott hálózati incidenshez.
`AccessRightList`	A fájl vagy könyvtár megnyitott leírójának megadott hozzáférési engedélyek.	A 2023-01-03-s és újabb verzióban érhető el. Egy fájlon vagy könyvtáron tárolt hozzáférési engedélyek lekérdezésére szolgál különböző nyitott leírók segítségével. A lehetséges értékek a READ, a WRITE és a DELETE, vagy ezeknek az értékeknek a kombinációja.
`NextMarker`	A következő listajelet leíró sztring. A rendszer akkor adja vissza, ha több leírót kell felsorolni a kérés teljesítéséhez.	A sztringet a rendszer a további kérelmekben a fennmaradó leírók listázására használja. A `NextMarker` hiánya azt jelzi, hogy az összes releváns leíró szerepel a listán.

A 2021-12-02-es és újabb verziókban a List Handles százalékban kódolja (RFC 2396-ra vetítve) az összes olyan Path elemértéket, amely az XML-ben érvénytelen karaktereket tartalmaz (különösen az U+FFFE vagy az U+FFFF). Kódolás esetén a Path elem tartalmaz egy Encoded=true attribútumot. Vegye figyelembe, hogy ez csak az XML-ben érvénytelen karaktereket tartalmazó Path elemértékek esetében fordul elő, a válasz többi Path eleme nem.

ClientName a 2024-02-04-es és újabb verziók támogatják.

Felhatalmazás

Ezt a műveletet csak a fióktulajdonos hívhatja meg.

Megjegyzések

A HandleId egy szolgáltatásoldali leíróazonosító, amely különbözik az ügyfél leíróazonosítójától. A kettő közötti megfeleltetés az ügyfélnél lehetséges.

Megosztás a következőn keresztül: