Listafogantyúk
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.