Python için Azure Depolama Dosya Paylaşımı istemci kitaplığı - sürüm 12.15.0b1

  • Makale

Azure Dosya Paylaşımı depolama, bulutta endüstri standardı Sunucu İleti Bloğu (SMB) protokolü aracılığıyla erişilebilen tam olarak yönetilen dosya paylaşımları sunar. Azure dosya paylaşımları Windows, Linux ve macOS bulut ve şirket içi dağıtımları tarafından aynı anda bağlanabilir. Azure dosya paylaşımları ayrıca verilerin kullanıldığı yerin yakınlarında hızlı erişim sağlamak için Azure Dosya Eşitleme ile Windows Server’larda önbelleğe alınabilir.

Azure dosya paylaşımları şunları yapmak için kullanılabilir:

  • Şirket içi dosya sunucularını değiştirme veya tamamlama
  • "Lift and shift" uygulamaları
  • Paylaşılan uygulama ayarları, tanılama paylaşımı ve Geliştirme/Test/Hata Ayıklama araçlarıyla bulut geliştirmeyi basitleştirme

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Başlarken

Önkoşullar

Paketi yükleme

Python için Azure Depolama Dosya Paylaşımı istemci kitaplığını pip ile yükleyin:

pip install azure-storage-file-share

Depolama hesabı oluşturma

Yeni bir depolama hesabı oluşturmak isterseniz Azure Portalı, Azure PowerShell veya Azure CLI'yı kullanabilirsiniz:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

İstemci oluşturma

Python için Azure Depolama Dosya Paylaşımı istemci kitaplığı, dört tür kaynakla etkileşim kurmanızı sağlar: depolama hesabının kendisi, dosya paylaşımları, dizinler ve dosyalar. Bu kaynaklarla etkileşim bir istemci örneğiyle başlar. İstemci nesnesi oluşturmak için depolama hesabının dosya hizmeti URL'sine ve depolama hesabına erişmenizi sağlayan bir kimlik bilgilerine ihtiyacınız olacaktır:

from azure.storage.fileshare import ShareServiceClient

service = ShareServiceClient(account_url="https://<my-storage-account-name>.file.core.windows.net/", credential=credential)

Hesap URL'sini arama

Depolama hesabının dosya hizmeti URL'sini Azure Portal, Azure PowerShell veya Azure CLI kullanarak bulabilirsiniz:

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

Kimlik bilgisi türleri

Parametre credential , kullanmak istediğiniz yetkilendirme türüne bağlı olarak bir dizi farklı biçimde sağlanabilir:

  1. Paylaşılan erişim imzası (SAS) belirteci kullanmak için belirteci dize olarak sağlayın. Hesap URL'niz SAS belirtecini içeriyorsa kimlik bilgisi parametresini atayın. Azure Portalı'ndan "Paylaşılan erişim imzası" altında bir SAS belirteci oluşturabilir veya işlevlerden generate_sas() birini kullanarak depolama hesabı, paylaşım veya dosya için sas belirteci oluşturabilirsiniz:

    from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

  2. Depolama hesabı paylaşılan anahtarı (diğer adıyla hesap anahtarı veya erişim anahtarı) kullanmak için anahtarı dize olarak sağlayın. Bu, Azure Portal'da "Erişim Anahtarları" bölümünde veya aşağıdaki Azure CLI komutunu çalıştırarak bulunabilir:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    İstemcinin kimliğini doğrulamak için kimlik bilgisi parametresi olarak anahtarını kullanın:

    from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")

İstemciyi bir bağlantı dizesi oluşturma

Kullanım örneğinize ve yetkilendirme yönteminize bağlı olarak, hesap URL'sini ve kimlik bilgilerini ayrı olarak sağlamak yerine depolama bağlantı dizesi bir istemci örneği başlatmayı tercih edebilirsiniz. Bunu yapmak için depolama bağlantı dizesi istemcinin from_connection_string sınıf yöntemine geçirin:

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

Depolama hesabınıza bağlantı dizesi Azure Portal'da "Erişim Anahtarları" bölümünde veya aşağıdaki CLI komutunu çalıştırarak bulunabilir:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Önemli kavramlar

Aşağıdaki bileşenler Azure Dosya Paylaşımı Hizmeti'ni oluşturur:

  • Depolama hesabının kendisi
  • Depolama hesabı içindeki bir dosya paylaşımı
  • Dosya paylaşımındaki isteğe bağlı dizin hiyerarşisi
  • Dosya paylaşımı içinde boyutu en çok 1 TiB olabilecek bir dosya

Python için Azure Depolama Dosya Paylaşımı istemci kitaplığı, ayrılmış bir istemci nesnesi kullanarak bu bileşenlerin her biriyle etkileşim kurmanızı sağlar.

Zaman Uyumsuz İstemciler

Bu kitaplık, Python 3.5+ üzerinde desteklenen tam bir zaman uyumsuz API içerir. Bunu kullanmak için önce aiohttp gibi bir zaman uyumsuz aktarım yüklemeniz gerekir. Daha fazla bilgi için bkz. azure-core belgeleri .

Zaman uyumsuz istemciler ve kimlik bilgileri artık gerekli olmadığında kapatılmalıdır. Bu nesneler zaman uyumsuz bağlam yöneticileridir ve zaman uyumsuz close yöntemler tanımlar.

İstemciler

Dosya Paylaşımı Hizmeti'nin çeşitli bileşenleriyle etkileşime geçmek için dört farklı istemci sağlanır:

  1. ShareServiceClient - bu istemci Azure depolama hesabıyla etkileşimi temsil eder ve içindeki dosya paylaşımlarına erişmek için önceden yapılandırılmış istemci örnekleri almanıza olanak tanır. Hizmet özelliklerini alıp yapılandırmanın yanı sıra hesaptaki paylaşımları listeleme, oluşturma ve silme işlemleri sağlar. Belirli bir paylaşımda işlem gerçekleştirmek için yöntemini kullanarak bir istemci alın get_share_client .
  2. ShareClient - bu istemci belirli bir dosya paylaşımıyla etkileşimi temsil eder (henüz mevcut olması gerekmez) ve içindeki dizinlere ve dosyalara erişmek için önceden yapılandırılmış istemci örnekleri almanıza olanak tanır. Paylaşımın anlık görüntülerini oluşturmak, silmek, yapılandırmak veya oluşturmak için işlemler sağlar ve içindeki dizinlerin içeriğini oluşturup listeleme işlemlerini içerir. Belirli bir dizin veya dosya üzerinde işlem gerçekleştirmek için veya get_file_client yöntemlerini kullanarak get_directory_client bir istemci alın.
  3. ShareDirectoryClient - bu istemci belirli bir dizinle etkileşimi temsil eder (henüz mevcut olması gerekmez). Bir anlık veya iç içe alt dizinin içeriğini oluşturma, silme veya listeleme işlemleri sağlar ve içindeki dosyaları oluşturma ve silme işlemlerini içerir. Belirli bir alt dizin veya dosyayla ilgili işlemler için, bu varlığın istemcisi ve get_file_client işlevleri kullanılarak get_subdirectory_client da alınabilir.
  4. ShareFileClient - Bu istemci belirli bir dosyayla etkileşimi temsil eder (henüz mevcut olması gerekmez). Bir dosyayı karşıya yükleme, indirme, oluşturma, silme ve kopyalama işlemlerini sağlar.

Yol adlandırma kısıtlamalarıyla ilgili ayrıntılar için bkz. Paylaşımları, Dizinleri, Dosyaları ve Meta Verileri Adlandırma ve Başvurma.

Örnekler

Aşağıdaki bölümlerde, aşağıdakiler dahil olmak üzere en yaygın Depolama Dosya Paylaşımı görevlerinden bazılarını kapsayan çeşitli kod parçacıkları sağlanır:

Dosya paylaşımı oluşturma

Dosyalarınızı depolamak için dosya paylaşımı oluşturma

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

Dosya paylaşımı oluşturmak için zaman uyumsuz istemciyi kullanma

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

Dosyayı karşıya yükleme

Paylaşıma dosya yükleme

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

Dosyayı zaman uyumsuz olarak karşıya yükleme

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

Dosya indirme

Paylaşımdan dosya indirme

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

Dosyayı zaman uyumsuz olarak indirme

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

Dizinin içeriğini listeleme

Üst dizin altındaki tüm dizinleri ve dosyaları listeleme

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

Bir dizinin içeriğini zaman uyumsuz olarak listeleme

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

İsteğe Bağlı Yapılandırma

İstemcide ve işlem düzeyinde geçirilebilen isteğe bağlı anahtar sözcük bağımsız değişkenleri.

İlke yapılandırmasını yeniden deneme

Yeniden deneme ilkesini yapılandırmak için bir istemci örneği oluştururken aşağıdaki anahtar sözcük bağımsız değişkenlerini kullanın:

  • retry_total (int): İzin vermek için toplam yeniden deneme sayısı. Diğer sayılardan önceliklidir. İstekleri retry_total=0 yeniden denemek istemiyorsanız geçiş yapın. Varsayılan değer 10'dır.
  • retry_connect (int): Bağlantıyla ilgili kaç hatanın yeniden denenebileceği. Varsayılan değer 3'tir.
  • retry_read (int): Okuma hatalarında yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_status (int): Hatalı durum kodları üzerinde yeniden deneme sayısı. Varsayılan değer 3'tir.
  • retry_to_secondary (bool): mümkünse isteğin ikincil olarak yeniden denenip denenmeyeceği. Bu yalnızca RA-GRS hesaplarının etkinleştirilmesi gerekir ve eski olabilecek veriler işlenebilir. Varsayılan olarak olarak Falsegösterilir.

Diğer istemci /işlem başına yapılandırma

İstemcide veya işlem başına belirtilebilen diğer isteğe bağlı yapılandırma anahtar sözcük bağımsız değişkenleri.

İstemci anahtar sözcük bağımsız değişkenleri:

  • connection_timeout (int): İstemcinin sunucuyla bağlantı kurmak için bekleyeceği saniye sayısı. Varsayılan değer 20 saniyedir.
  • read_timeout (int): İstemcinin sunucudan gelen bir yanıt için ardışık okuma işlemleri arasında bekleyeceği saniye sayısı. Bu bir yuva düzeyi zaman aşımıdır ve genel veri boyutundan etkilenmez. İstemci tarafı okuma zaman aşımları otomatik olarak yeniden denenecek. Varsayılan değer 60 saniyedir.
  • transport (Any): HTTP isteğini göndermek için kullanıcı tarafından sağlanan aktarım.

İşlem başına anahtar sözcük bağımsız değişkenleri:

  • raw_response_hook (çağrılabilir): Verilen geri arama, hizmetten döndürülen yanıtı kullanır.
  • raw_request_hook (çağrılabilir): Verilen geri arama, hizmete gönderilmeden önce isteği kullanır.
  • client_request_id (str): İsteğin kullanıcı tarafından belirtilen isteğe bağlı kimliği.
  • user_agent (str): İstekle birlikte gönderilecek kullanıcı aracısı üst bilgisine özel değeri ekler.
  • logging_enable (bool): HATA AYıKLAMA düzeyinde günlüğe kaydetmeyi etkinleştirir. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • logging_body (bool): İsteğin ve yanıt gövdesinin günlüğe kaydedilmesini sağlar. Varsayılan değer False'tur. Tüm istekler için etkinleştirmek üzere istemci düzeyinde de geçirilebilir.
  • headers (dict): Özel üst bilgileri anahtar, değer çiftleri olarak geçirin. Örneğin. headers={'CustomValue': value}

Sorun giderme

Genel

Depolama Dosyası istemcileri Azure Core'da tanımlanan özel durumları tetikler.

Bu liste, atılan özel durumları yakalamak için başvuru için kullanılabilir. Özel durumun belirli hata kodunu almak için özniteliğini error_code kullanın, örneğin. exception.error_code

Günlüğe Kaydetme

Bu kitaplık , günlüğe kaydetme için standart günlük kitaplığını kullanır. HTTP oturumları (URL'ler, üst bilgiler vb.) hakkındaki temel bilgiler BİlGİ düzeyinde günlüğe kaydedilir.

İstek/yanıt gövdeleri ve kaydedilmemiş üst bilgiler de dahil olmak üzere ayrıntılı HATA AYıKLAMA düzeyi günlüğü, bir istemcide şu bağımsız değişkenle logging_enable etkinleştirilebilir:

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = ShareServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Benzer şekilde, logging_enable istemci için etkinleştirilmemiş olsa bile tek bir işlem için ayrıntılı günlüğe kaydetmeyi etkinleştirebilir:

service_client.get_service_properties(logging_enable=True)

Sonraki adımlar

Daha fazla örnek kod

Dosya Paylaşımı örneklerimizi kullanmaya başlayın.

SDK'nın GitHub deposunda çeşitli Depolama Dosya Paylaşımı Python SDK'sı örnekleri sağlanır. Bu örnekler, Depolama Dosya Paylaşımı ile çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

Diğer belgeler

Azure Dosya Paylaşımı depolaması hakkında daha kapsamlı belgeler için docs.microsoft.com ile ilgili Azure Dosya Paylaşımı depolama belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları SSS bölümüne bakın veya ek sorularınız veya yorumlarınızla iletişime geçin opencode@microsoft.com .