Liste Tanıtıcıları

Makale
06/01/2023

İşlem, List Handles bir dizin veya dosyadaki açık tanıtıcıların listesini döndürür. İsteğe bağlı olarak, dizinlerde ve dosyalarda açık tanıtıcıları yinelemeli olarak numaralandırabilir. Bu API, 2018-11-09 sürümünden itibaren kullanılabilir.

Protokol kullanılabilirliği

Etkin dosya paylaşımı protokolü	Kullanılabilir
SMB
NFS

İstek

İsteği aşağıdaki gibi oluşturabilirsiniz List Handles . HTTPS önerilir.

Yöntem	İstek URI'si	HTTP sürümü
`GET`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfileordirectory?comp=listhandles`	HTTP/1.1

İstek URI'sinde gösterilen yol bileşenlerini aşağıdaki gibi kendinizle değiştirin:

Yol bileşeni	Açıklama
`myaccount`	Depolama hesabınızın adı.
`myshare`	Dosya paylaşımınızın adı.
`mydirectorypath`	İsteğe bağlı. Dizinin yolu.
`myfileordirectory`	Dosyanın veya dizinin adı.

Yol adlandırma kısıtlamalarıyla ilgili ayrıntılar için bkz. Paylaşımları, dizinleri, dosyaları ve meta verileri adlandırma ve buna başvurma.

URI parametreleri

URI'de aşağıdaki ek parametreleri belirtebilirsiniz.

Parametre	Açıklama
`marker`	İsteğe bağlı. Listenin bir sonraki `List Handles` işlemle döndürülecek bölümünü tanımlayan dize değeri. Döndürülen liste tamamlanmadıysa, işlem yanıt gövdesinde bir işaretçi değeri döndürür. Bundan sonra sonraki bir çağrıda işaretleyici değerini kullanarak bir sonraki liste öğesi kümesini isteyebilirsiniz. İşaretçi değeri istemci için opaktır.
`maxresults`	İsteğe bağlı. Döndürülecek dosya veya dizinlerde alınan en fazla tanıtıcı sayısını belirtir. Sıfırdan küçük veya sıfıra eşit bir değere ayarlanması `maxresults` hata yanıtı kodu 400(Hatalı İstek) ile sonuçlanır.
`timeout`	İsteğe bağlı. `timeout` parametresi saniye cinsinden ifade edilir. Daha fazla bilgi için bkz. Azure Dosyalar işlemleri için zaman aşımlarını ayarlama.
`sharesnapshot`	İsteğe bağlı. `sharesnapshot` parametresi, mevcut olduğunda tanıtıcı listesini sorgulamak üzere paylaşım anlık görüntüsünü belirten opak `DateTime` bir değerdir.

İstek üst bilgileri

Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır.

İstek üst bilgisi	Açıklama
`Authorization`	Gereklidir. Yetkilendirme düzenini, hesap adını ve imzayı belirtir. Daha fazla bilgi için bkz. Azure Depolama'ya istekleri yetkilendirme.
`Date` veya `x-ms-date`	Gereklidir. İstek için Eşgüdümlü Evrensel Saat (UTC) biçimini belirtir. Daha fazla bilgi için bkz. Azure Depolama'ya istekleri yetkilendirme.
`x-ms-version`	Anonim istekler için isteğe bağlı olarak tüm yetkili istekler için gereklidir. Bu istek için kullanılacak işlemin sürümünü belirtir. Daha fazla bilgi için bkz. Azure Depolama hizmetleri için sürüm oluşturma.
`x-ms-client-request-id`	İsteğe bağlı. Günlüğe kaydetme yapılandırıldığında günlüklere kaydedilen 1 kibibayt (KiB) karakter sınırıyla istemci tarafından oluşturulan, opak bir değer sağlar. İstemci tarafı etkinlikleriyle sunucunun aldığı istekler arasında bağıntı sağlamak için bu üst bilgiyi kullanmanızı kesinlikle öneririz. Daha fazla bilgi için bkz. İzleme Azure Dosyalar.
`x-ms-recursive`	İsteğe bağlı. İşlemin URI'de belirtilen dizinin dosyalarına ve alt dizinlerine de uygulanıp uygulanacağını belirten bir Boole değeri.
`x-ms-file-request-intent`	Üst bilgi bir OAuth belirteci belirtiyorsa `Authorization` gereklidir. Kabul edilebilir değer: `backup`. Bu üst bilgi, üst bilgi kullanılarak yetkilendirilmiş kimliğe atanan RBAC ilkesine dahil edildiyse veya `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` izni verilmesi `Authorization` gerektiğini belirtir`Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action`. Sürüm 2022-11-02 ve üzeri için kullanılabilir.
`x-ms-allow-trailing-dot: { <Boolean> }`	İsteğe bağlı. Sürüm 2022-11-02 ve üzeri. Boole değeri, istek URL'sinde sondaki bir noktanın kırpılıp kırpılmaması gerektiğini belirtir. Daha fazla bilgi için bkz . Paylaşımları, dizinleri, dosyaları ve meta verileri adlandırma ve buna başvurma.

İstek gövdesi

Yok.

Yanıt

Yanıt bir HTTP durum kodu, bir dizi yanıt üst bilgisi ve XML biçiminde bir yanıt gövdesi içerir.

Durum kodu

Başarılı bir işlem 200 (Tamam) durum kodunu döndürür. Durum kodları hakkında bilgi için bkz. Durum ve hata kodları.

Yanıt üst bilgileri

Bu işlemin yanıtı aşağıdaki üst bilgileri içerir. Yanıt ek, standart HTTP üst bilgileri de içerebilir. Tüm standart üst bilgiler HTTP/1.1 protokol belirtimine uygundur.

Yanıt üst bilgisi	Açıklama
`Content-Type`	Sonuçların döndürüldiği biçimi belirtir. Şu anda bu değer şeklindedir `application/xml`.
`x-ms-request-id`	Bu üst bilgi, yapılan isteği benzersiz olarak tanımlar ve istek sorunlarını gidermek için kullanılabilir. Daha fazla bilgi için bkz . API işlemleriyle ilgili sorunları giderme.
`x-ms-version`	İsteği çalıştırmak için kullanılan Azure Dosyalar sürümünü gösterir.
`Date`	Yanıtın başlatıldığı saati gösteren UTC tarih/saat değeri. Hizmet bu değeri oluşturur.
`x-ms-client-request-id`	İsteklerde ve karşılık gelen yanıtlarda sorun gidermek için bu üst bilgiyi kullanabilirsiniz. Bu üst bilginin değeri, istekte varsa üst bilginin değerine `x-ms-client-request-id` eşittir. Değer en fazla 1024 görünür ASCII karakterdir. İstekte `x-ms-client-request-id` üst bilgi yoksa, yanıtta bu üst bilgi bulunmaz.

Yanıt gövdesi

XML yanıtının biçimi aşağıdaki gibidir. , ShareSnapshotve MaxResults öğelerinin Markeryalnızca istek URI'sinde belirttiğinizde mevcut olduğunu unutmayın. öğesinin NextMarker bir değeri olması için liste sonuçlarının tamamlanmamış olması gerekir.

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

Aşağıdaki tabloda yanıt gövdesinin alanları açıklanmaktadır:

Alan	Açıklama	Amaç
`HandleId`	XSMB hizmet tanıtıcı kimliği, UINT64.	Tanıtıcıyı tanımlamak için kullanılır.
`Path`	Paylaşım kökünden başlayarak tam yol da dahil olmak üzere dosya adı. Dize.	Tanıtıcının açık olduğu nesnenin adını tanımlamak için kullanılır.
`ClientIp`	Tanıtıcıyı açan istemci IP'i. Dize.	Tanıtıcının sızdırılıp sızmayabileceğine karar vermek için kullanılır.
`OpenTime`	Zaman tanıtıcısı açıldı (UTC). `DateTime` Dize olarak.	Tanıtıcının sızdırılıp sızmayabileceğine karar vermek için kullanılır. Sızan tutamaçlar genellikle uzun süredir açıktır.
`LastReconnectTime`	Zaman tanıtıcısı açıldı (UTC). `DateTime` Dize olarak.	Ağ veya diğer hatalardan dolayı istemci/sunucu bağlantısı kesildikten sonra tanıtıcının yeniden açılıp açılmay gerektiğine karar vermek için kullanılır. Alan yanıt gövdesine yalnızca bağlantı kesme olayı oluştuğunda ve tanıtıcı yeniden açıldığında eklenir.
`FileId`	Dosya Kimliği, UINT64.	`FileId` dosyayı benzersiz olarak tanımlar. Yeniden adlandırmalar sırasında yararlı olur çünkü `FileId` değeri değişmez.
`ParentId`	Üst Dosya Kimliği, UINT64.	`ParentId` dizini benzersiz olarak tanımlar. Bu, yeniden adlandırmalar sırasında yararlı olur çünkü `ParentId` değeri değişmez.
`SessionId`	Dosya tanıtıcısının açıldığı bağlamı belirten SMB oturum kimliği. UINT64.	`SessionId` oturumların bağlantısı zorla kesildiğinde olay görüntüleyici günlüklerine eklenir. Belirli bir grup sızan tanıtıcıyı belirli bir ağ olayıyla ilişkilendirmenizi sağlar.
`AccessRightList`	Dosya veya dizindeki açık tanıtıcıya verilen erişim izinleri.	Hizmet sürümü 2023-01-03 ve sonraki sürümlerde kullanılabilir. Bir dosya veya dizinde tutulan erişim izinlerini çeşitli açık tanıtıcılar tarafından sorgulamak için kullanılır. Olası değerler READ, WRITE ve DELETE değerleridir veya bu değerlerin bir birleşimidir.
`NextMarker`	Listelenecek sonraki tanıtıcıyı açıklayan bir dize. İsteği tamamlamak için daha fazla tanıtıcının listelenmesi gerektiğinde döndürülür.	Dize, kalan tanıtıcıları listelemek için sonraki isteklerde kullanılır. yokluğu `NextMarker` , tüm ilgili tanıtıcıların listelendiğini gösterir.

2021-12-02 ve daha yeni sürümlerde, List Handles XML'de geçersiz karakterler (özellikle U+FFFE veya U+FFFF) içeren tüm Path öğe değerlerini yüzde kodlar (RFC 2396 başına). Kodlanmışsa, Path öğesi bir Encoded=true öznitelik içerir. Bunun yanıttaki Path kalan Path öğeler için değil, yalnızca XML'de geçersiz karakterleri içeren öğe değerleri için oluşacağını unutmayın.

Yetkilendirme

Bu işlemi yalnızca hesap sahibi çağırabilir.

Açıklamalar

HandleId, istemci tanıtıcı kimliğinden ayrı bir hizmet tarafı tanıtıcı kimliğidir. İkisi arasında eşleme istemcide mümkündür.

Share via