Címtárak és fájlok listázása

Cikk
03/29/2023

A List Directories and Files művelet a megadott megosztás vagy könyvtár alatt lévő fájlok vagy könyvtárak listáját adja vissza. Csak a címtárhierarchia egyetlen szintjére sorolja fel a tartalmat.

Protokoll rendelkezésre állása

Engedélyezett fájlmegosztási protokoll	Elérhető
SMB
NFS

Kérés

A kérést a List Directories and Files 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?restype=directory&comp=list`	HTTP/1.1
`GET`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath?restype=directory&sharesnapshot=<DateTime>&comp=list`	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`	A könyvtár elérési útja.

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
`prefix`	Választható. 2016-05-31-es és újabb verzió. Az eredményeket úgy szűri, hogy csak azokat a fájlokat és könyvtárakat adja vissza, amelyek neve a megadott előtaggal kezdődik.
`sharesnapshot`	Választható. 2017-04-17-es és újabb verzió. A megosztási pillanatkép paraméter egy átlátszatlan `DateTime` érték, amely jelen esetben meghatározza a fájlok és könyvtárak listájának lekérdezéséhez szükséges megosztási pillanatképet.
`marker`	Választható. A következő listaművelettel visszaadandó listarészt azonosító sztringérték. 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ó. A visszaadandó fájlok vagy könyvtárak maximális számát adja meg. Ha a kérés nem ad meg `maxresults`, vagy 5000-nél nagyobb értéket ad meg, a kiszolgáló legfeljebb 5000 elemet ad vissza. 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.
`include={Timestamps, ETag, Attributes, PermissionKey}`	Opcionálisan elérhető, a 2020-04-08-es verziótól kezdve. Egy vagy több olyan tulajdonságot ad meg, amely szerepel a válaszban: `Timestamps` `ETag` `Attributes` (Win32-fájlattribútumok) `PermissionKey` Ha egynél több beállítást szeretne megadni az URI-n, az egyes beállításokat url-kódolású vesszővel (`%82`) kell elválasztania. A fejléc `x-ms-file-extended-info` implicit módon true (igaz) értéket feltételez a paraméter megadásakor.
`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.

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 kibibájtos (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-file-extended-info: {true}`	Választható. 2020-04-08-es és újabb verzió. Ez a fejléc implicit módon igaznak minősül, ha a `include` lekérdezési paraméter nem üres. Ha igaz, a `Content-Length` tulajdonság naprakész lesz. A 2020-04-08, 2020-06-12 és 2020-08-04 verziókban a rendszer csak akkor ad vissza fájlokat és könyvtárakat, `FileId` ha ez a fejléc igaz. A 2020-10-02-s és újabb `FileId` verziókban a rendszer mindig visszaadja a fájlokat és könyvtárakat.
`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	Leírás
`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` vagy `x-ms-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 elem csak akkor jelenik meg, ha megadja őket a kérelem URI-jában. Az NextMarker elem csak akkor rendelkezik értékkel, ha a listaeredmények nem fejeződnek be.

<?xml version="1.0" encoding="utf-8"?>  
<EnumerationResults ServiceEndpoint="https://myaccount.file.core.windows.net/" ShareName="myshare" ShareSnapshot="date-time" DirectoryPath="directory-path">  
  <Marker>string-value</Marker>
  <Prefix>string-value</Prefix>
  <MaxResults>int-value</MaxResults>
  <DirectoryId>directory-id</DirectoryId>
  <Entries>
    <File>
      <FileId>file-id</FileId>
      <Name>file-name</Name>  
      <Properties>  
        <Content-Length>size-in-bytes</Content-Length>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive | Hidden | Offline | ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </File>  
    <Directory>
      <FileId>file-id</FileId>
      <Name>directory-name</Name>  
      <Properties>
        <CreationTime>datetime</CreationTime>
        <LastAccessTime>datetime</LastAccessTime>
        <LastWriteTime>datetime</LastWriteTime>
        <ChangeTime>datetime</ChangeTime>
        <Last-Modified>datetime</Last-Modified>
        <Etag>etag</Etag>
      </Properties>
      <Attributes>Archive | Hidden | Offline | ReadOnly</Attributes>
      <PermissionKey>4066528134148476695*1</PermissionKey>
    </Directory>  
  </Entries>  
  <NextMarker />  
</EnumerationResults>

Vegye figyelembe, hogy az Content-Length elem a listaelemben lesz visszaadva. Előfordulhat azonban, hogy ez az érték nem naprakész, mert egy SMB-ügyfél helyileg módosította a fájlt. Előfordulhat, hogy az Content-Length érték nem tükrözi ezt a tényt, amíg a fogópont be nem záródik, vagy az op-lock megszakad. Az aktuális tulajdonságértékek lekéréséhez használja a parancsot x-ms-file-extended-info: true, vagy hívja meg a Fájltulajdonságok lekérése parancsot.

A 2020-04-08,2020-06-12 és 2020-08-04 verziókban a rendszer visszaadja a fájlokat és könyvtárakat, FileId ha a fejléc x-ms-file-extended-info igaz. A 2020-10-02-es és újabb FileId verziókban a rendszer mindig visszaadja a fájlokat és könyvtárakat.

A 2020-04-08-es include={timestamps} verzióban a következő időbélyeg-tulajdonságokat adja vissza: CreationTime, LastAccessTime, és LastWriteTime. A verzióban és az újabb verziókban 2020-06-12 a következő időbélyeg-tulajdonságokat adja vissza: CreationTime, LastAccessTime, LastWriteTime, , ChangeTimeés Last-Modified. include={timestamps}

A 2020-10-02-es és újabb DirectoryId verzióban a rendszer visszaadja a választ. Meghatározza annak a könyvtárnak a FileId nevét, amelyen az API-t meghívja.

A 2021-12-02-es és újabb List Directory and Files verziókban a százalékkódolás (RFC 2396-ra vetítve) minden FileName, DirectoryName, Prefix vagy DirectoryPath elemérték, amely érvénytelen karaktereket tartalmaz XML-ben (konkrétan U+FFFE vagy U+FFFF). Kódolás esetén a Name, Prefix vagy EnumerationResults elem tartalmaz egy Encoded=true attribútumot. Vegye figyelembe, hogy ez csak az Name XML-ben érvénytelen karaktereket tartalmazó elemértékek esetében fordul elő, a válasz többi Name eleme nem.

Datetime formátum és API-verzió időbélyegmezőkhöz

Elem	Datetime formátum	Mintaérték	API-verzió
`CreationTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-04-08 és újabb
`LastAccessTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-04-08 és újabb
`LastWriteTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-04-08 és újabb
`ChangeTime`	ISO 8601	`2020-09-17T13:38:03.2740000Z`	2020-06-12 és újabb
`Last-Modified`	RFC 1123	`Thu, 17 Sep 2020 13:38:07 GMT`	2020-06-12 és újabb

Engedélyezés

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

Megjegyzések

Az elemben Content-Length visszaadott érték a fájl fejlécének értékének x-ms-content-length felel meg.

Vegye figyelembe, hogy minden Directory visszaadott elem a maximális eredmény felé számít, ahogyan az egyes File elemek is. A fájlok és könyvtárak a válasz törzsében lexikálisan rendezett sorrendben jelennek meg.

A listázás a címtárhierarchia egyetlen szintjére korlátozódik. Több szint listázásához több hívást is kezdeményezhet iteratív módon. Használja az Directory egyik eredményből visszaadott értéket a következő hívásban: List Directories and Files.

Lásd még

Könyvtárakon végzett műveletek