Listatartományok

Cikk
03/29/2023

A List Ranges művelet egy fájl érvényes tartományainak listáját adja vissza.

Protokoll rendelkezésre állása

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

Kérés

A kérést az List Ranges alábbiak szerint 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/myfile?comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>&comp=rangelist`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&snapshot=<DateTime>&prevsharesnapshot=<DateTime>`	HTTP/1.1
GET	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rangelist&prevsharesnapshot=<DateTime>`	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`	Választható. A szülőkönyvtár elérési útja.
`myfile`	A fájl neve.

Az elérési utak elnevezési korlátozásával kapcsolatos részletekért lásd: Megosztások, könyvtárak, fájlok és metaadatok elnevezése és hivatkozása.

URI-paraméterek

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

Paraméter	Leírás
`sharesnapshot`	Választható. 2017-04-17-es és újabb verziók. A `sharesnapshot` paraméter egy átlátszatlan `DateTime` érték, amely jelen esetben meghatározza a fájlhoz lekérdezendő megosztási pillanatképet.
`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.
`prevsharesnapshot`	Nem kötelező a 2020-02-10-es és újabb verziókban. A `prevsharesnapshot` paraméter egy átlátszatlan `DateTime` érték, amely jelen esetben az előző pillanatképet adja meg. Ha ez a paraméter és `sharesnapshot` jelen van is, a válasz csak a két pillanatkép között módosított oldaltartományokat fogja tartalmazni. Ha csak `prevsharesnapshot` jelen van, a válasz csak azokat az oldaltartományokat tartalmazza, amelyek módosultak a pillanatkép és az élő megosztás között. A módosított lapok közé tartoznak a frissített és a törölt lapok is.

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érelmek 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érelmek engedélyezése az Azure Storage-ba.
`x-ms-version`	Minden engedélyezett kéréshez szükséges. A kérelemhez használandó művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`Range`	Választható. A tartományok listázásához használható bájttartományt adja meg. Ha nincs megadva, a rendszer a fájl összes tartományát visszaadja.
`x-ms-range`	Választható. A tartományok listázásához használható bájttartományt adja meg. Ha a és `x-ms-range` a `Range` fejléc is meg van adva, a szolgáltatás a értékét `x-ms-range`használja. További információ: Tartományfejléc megadása Azure Files műveletekhez.
`x-ms-lease-id:<ID>`	Választható. 2019-02-02-es és újabb verzió. Ha a fejléc meg van adva, a művelet csak akkor lesz végrehajtva, ha a fájl bérlete jelenleg aktív, és a kérelemben megadott bérletazonosító megegyezik a fájléval. Ellenkező esetben a művelet a 412-s állapotkóddal meghiúsul (az előfeltétel sikertelen).
`x-ms-client-request-id`	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ó: Azure Files figyelése.
`x-ms-file-request-intent`	Kötelező, ha `Authorization` a fejléc OAuth-jogkivonatot ad meg. Elfogadható érték: `backup`. Ez a fejléc határozza meg, hogy a `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` vagy `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` értéket kell megadni, 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 -os állapotkódot adja vissza (OK). 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
`Last-Modified`	A fájl utolsó módosításának dátuma/időpontja. Minden olyan művelet, amely módosítja a fájlt, beleértve a fájl metaadatainak vagy tulajdonságainak frissítését, megváltoztatja a fájl utolsó módosítási időpontját.
`ETag`	A `ETag` tartalmaz egy értéket, amely a fájl verzióját jelöli idézőjelek között.
`x-ms-content-length`	A fájl mérete bájtban. Ha `prevsharesnapshot` jelen van, akkor az érték a fájl méretét írja le a `sharesnapshot` (ha a `sharesnapshot` lekérdezési paraméter jelen van). Ellenkező esetben az élő fájl méretét írja le.
`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

A válasz törzse tartalmazza a nem átfedésben lévő érvényes tartományok listáját, a címtartomány növelésével rendezve. A válasz törzsének formátuma a következő.

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
  <Range>  
    <Start>Start Byte</Start>  
    <End>End Byte</End>  
  </Range>  
</Ranges>

Ha a fájl teljes tartománykészlete törölve lett, a válasz törzse nem tartalmaz tartományokat.

Ha prevsharesnapshot meg van adva, a válasz csak azokat az oldalakat tartalmazza, amelyek különböznek a célpillanatkép (vagy az élő fájl) és az előző pillanatkép között. A visszaadott tartományok közé tartoznak a frissített vagy törölt tartományok is. A válasz formátuma a következő:

<?xml version="1.0" encoding="utf-8"?> 
<Ranges> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
  <ClearRange> 
    <Start>Start Byte</Start>
    <End>End Byte</Start> 
  </ClearRange> 
  <Range> 
    <Start>Start Byte</Start> 
    <End>End Byte</Start> 
  </Range> 
</Ranges>

Ha a fájl teljes lapkészlete törölve lett, és a prevsharesnapshot paraméter nincs megadva, a válasz törzse nem tartalmaz tartományokat.

Engedélyezés

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

Megjegyzések

Az egyes tartományok kezdő és záró bájt eltolásai a teljes tartományra kiterjednek. Tekintse meg a Tartományfrissítési műveletek és a Tartomány törlése műveletek példákat a Put Range (Tartomány törlése) című témakörben. Ezek a példák azt mutatják be, hogy milyen tartományokat ad vissza a rendszer, ha egy 512 nemaligned bájttartományt ír vagy töröl a fájlból.

Egy nagy számú írást tartalmazó, erősen töredezett fájlban a List Ranges kérések meghiúsulhatnak egy belső kiszolgáló időtúllépése miatt. A nagy számú írási művelettel rendelkező fájltartományokat lekérő alkalmazásoknak egyszerre le kell kérnie a tartományok egy részhalmazát.

A 2020-02-10-es verziótól kezdve egy prevsharesnapshot paraméterrel hívhatList Ranges. Ez visszaadja az élő fájl és a pillanatkép, illetve a pillanatképeken lévő fájl két pillanatképe között eltérő tartományokat. Ezekkel a tartománykülönbségekkel lekérheti egy fájl növekményes pillanatképét. A növekményes pillanatképek költséghatékony megoldást jelentenek a fájlok biztonsági mentésére, ha saját biztonsági mentési megoldást szeretne implementálni.

Bizonyos fájlműveletek List Ranges meghiúsulnak, ha meghívják egy növekményes pillanatkép lekérésére. A szolgáltatás a következőt adja vissza:

404 (Nem található), ha olyan fájlt hív meg, amely nem létezik az egyik pillanatképben (vagy élőben, ha sharesnapshot nincs megadva).
409 (Ütközés), ha egy olyan fájlt hív meg, amely a pillanatkép után egy felülíró másolás célhelye volt, amelyet prevsharesnapshota megadott.
409 (Ütközés), ha egy törölt és újra létrehozott fájlt hív meg ugyanazzal a névvel és hellyel a megadott prevsharesnapshot pillanatkép készítése után.

Lásd még

Fájlokon végzett műveletek