Listafogantyúk

Cikk
06/01/2023

A List Handles művelet egy könyvtárban vagy fájlban lévő nyitott leírók listáját adja vissza. Igény szerint rekurzív módon számba vehet megnyitott leírókat a címtá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	Elérhető
SMB
NFS

Kérés

A kérést a List Handles következőképpen hozhatja létre. A HTTPS használata ajánlott.

Metódus	Kérés URI-ja	HTTP-verzió
`GET`	`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ő	Description
`myaccount`	A tárfiók neve.
`myshare`	A fájlmegosztás neve.
`mydirectorypath`	Választható. A könyvtár elérési útja.
`myfileordirectory`	A fájl vagy könyvtár neve.

Az elérésiút-elnevezési korlátozások részleteiért lásd: 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`	Választható. Sztringérték, amely a lista következő `List Handles` művelettel visszaadandó részét azonosítja. A művelet egy jelölőértéket ad vissza a választörzsben, 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`	Választható. Megadja a visszaadni kívánt fájlok vagy könyvtárak leíróinak maximális számát. Ha nullánál kisebb vagy egyenlő értékre állítja `maxresults` be a hibát, a 400-ra (hibás kérelem) vonatkozó hibaválasz-kód jelenik meg.
`timeout`	Választható. A `timeout` paraméter másodpercben van kifejezve. További információ: Időtúllépések beállítása Azure Files műveletekhez.
`sharesnapshot`	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érésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti.

Kérelem fejléce	Leírás
`Authorization`	Kötelező. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérések engedélyezése az Azure Storage-ba.
`Date` vagy `x-ms-date`	Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérések engedélyezése az Azure Storage-ba.
`x-ms-version`	Az összes engedélyezett kérelemhez 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`	Választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kib-os (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ó: Monitorozási Azure Files.
`x-ms-recursive`	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` a fejléc OAuth-jogkivonatot ad meg. 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 szerepelnek a fejléc használatával `Authorization` 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> }`	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 legyen-e levágva vagy sem. További információ: Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.

A kérés törzse

Nincsenek.

Reagálás

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ódok.

Válaszfejlécek

A műveletre adott válasz a következő 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.

Válaszfejléc	Description
`Content-Type`	Azt a formátumot adja meg, amelyben a rendszer visszaadja az eredményeket. Ez az érték jelenleg a .`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ójá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. A fejléc értéke megegyezik a fejléc értékével `x-ms-client-request-id` , 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álasztörzs

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

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

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`	Fájlnév, beleértve a teljes elérési utat is, a megosztás gyökerétől kezdve. Sztring.	Annak az objektumnak a nevének azonosítására szolgál, amelyhez a leíró meg van nyitva.
`ClientIp`	Ügyfél IP-címe, amely megnyitotta a leírót. Sztring.	Annak eldöntésére szolgál, hogy kiszivárgott-e a fogópont.
`OpenTime`	Az időleíró meg lett nyitva (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 már régóta nyitva vannak.
`LastReconnectTime`	Az időleíró meg lett nyitva (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 hálózati vagy egyéb hibák miatti megszakadása után. A mező csak akkor szerepel a válasz törzsében, ha a kapcsolatbontá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 meghatározza a fájlleíró megnyitásának környezetét. UINT64.	`SessionId` akkor szerepel az eseménynaplókban, ha a munkamenetek kényszerített módon vannak leválasztva. Lehetővé teszi a kiszivárgott leírók 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-es és újabb verzióban érhető el. A különböző nyitott leírók által egy fájlon vagy könyvtáron tárolt hozzáférési engedélyek lekérdezésére szolgál. Lehetséges értékek: READ, WRITE és DELETE, vagy ezek kombinációja.
`NextMarker`	A listázandó következő leírót leíró sztring. A rendszer akkor adja vissza, ha több leírót kell listázni a kérés teljesítéséhez.	A sztringet a rendszer a további kérelmekben használja a fennmaradó leírók listázására. A hiánya `NextMarker` azt jelzi, hogy az összes releváns leíró szerepel a listában.

A 2021-12-02-es és újabb List Handles verziókban a százalékkódolás (RFC 2396 szerint) minden Path olyan elemérték, amely xml-ben érvénytelen karaktereket tartalmaz (konkrétan U+FFFE vagy U+FFFF). Ha kódolva van, az Path elem tartalmazni fog egy attribútumot Encoded=true . Vegye figyelembe, hogy ez csak az Path XML-ben érvénytelen karaktereket tartalmazó elemértékek esetében fordul elő, a válasz többi Path eleme nem.

Engedélyezé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élleíró azonosítójától. A kettő közötti megfeleltetés az ügyfélnél lehetséges.