Python için Azure DataLake hizmeti istemci kitaplığı - sürüm 12.14.0b1

  • Makale

Genel Bakış

Python için bu önizleme paketi, Depolama SDK'sında kullanıma sunulan ADLS 2. Nesil'e özgü API desteğini içerir. Şunları içerir:

  1. Hiyerarşik ad alanı etkin (HNS) depolama hesabı için yeni dizin düzeyinde işlemler (Oluşturma, Yeniden Adlandırma, Silme). HNS özellikli hesaplar için yeniden adlandırma/taşıma işlemleri atomiktir.
  2. Hiyerarşik ad alanı etkin (HNS) hesapları için izinle ilgili işlemler (ACL'leri Alma/Ayarlama).

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

Başlarken

Önkoşullar

Paketi yükleme

Pip ile Python için Azure DataLake Depolama istemci kitaplığını yükleyin:

pip install azure-storage-file-datalake --pre

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

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

İstemcinin kimliğini doğrulama

DataLake Depolama ile etkileşim DataLakeServiceClient sınıfının bir örneğiyle başlar. İstemci nesnesinin örneğini oluşturmak için mevcut bir depolama hesabına, URL'sine ve kimlik bilgilerine ihtiyacınız vardır.

Kimlik bilgilerini alma

İstemcinin kimliğini doğrulamak için birkaç seçeneğiniz vardır:

  1. SAS belirteç dizesi kullanma
  2. Hesap paylaşılan erişim anahtarı kullanma
  3. azure.identity'den belirteç kimlik bilgisi kullanma

Alternatif olarak, yöntemini kullanarak from_connection_string bir depolama bağlantı dizesi kimlik doğrulaması yapabilirsiniz. Bkz. örnek: bağlantı dizesi ile istemci oluşturma.

Hesap URL'nizde zaten bir SAS belirteci varsa kimlik bilgilerini atlayabilirsiniz.

İstemci oluşturma

Hesap URL'nizi ve kimlik bilgilerinizi hazırladıktan sonra DataLakeServiceClient'ı oluşturabilirsiniz:

from azure.storage.filedatalake import DataLakeServiceClient

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

Önemli kavramlar

DataLake depolama dört tür kaynak sunar:

  • Depolama hesabı
  • Depolama hesabındaki bir dosya sistemi
  • Dosya sistemi altındaki bir dizin
  • Dosya sistemindeki veya dizinin altındaki bir dosya

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

DataLake Depolama SDK'sı, DataLake Hizmeti ile etkileşime geçmek için dört farklı istemci sağlar:

  1. DataLakeServiceClient - Bu istemci datalake hizmetiyle hesap düzeyinde etkileşim kurar. Hesap özelliklerini alma ve yapılandırmanın yanı sıra hesap içindeki dosya sistemlerini listeleme, oluşturma ve silme işlemlerini sağlar. Belirli bir dosya sistemi, dizin veya dosyayla ilgili işlemler için, bu varlıkların get_file_clientget_directory_clientget_file_system_client istemcileri veya işlevleri kullanılarak da alınabilir.
  2. FileSystemClient - Bu istemci, belirli bir dosya sistemi henüz mevcut olmasa bile belirli bir dosya sistemiyle etkileşimi temsil eder. Dosya sistemlerini oluşturma, silme veya yapılandırma işlemleri sağlar ve dosya sistemi altındaki yolları listeleme, dosya sistemindeki dosya veya dizini karşıya yükleme ve silme işlemlerini içerir. Belirli bir dosyayla ilgili işlemler için istemci işlevi kullanılarak get_file_client da alınabilir. Belirli bir dizinle ilgili işlemler için istemci işlevi kullanılarak get_directory_client alınabilir.
  3. DataLakeDirectoryClient - Bu istemci, henüz mevcut olmasa bile belirli bir dizinle etkileşimi temsil eder. Dizin oluşturma, silme, yeniden adlandırma, özellikleri alma ve özellik işlemlerini ayarlama işlemlerini sağlar.
  4. DataLakeFileClient - Bu istemci, belirli bir dosya henüz mevcut olmasa bile belirli bir dosyayla etkileşimi temsil eder. Verileri eklemek, verileri temizlemek, silmek, oluşturmak ve okumak için dosya işlemleri sağlar.
  5. DataLakeLeaseClient - Bu istemci FileSystemClient, DataLakeDirectoryClient veya DataLakeFileClient ile kira etkileşimlerini temsil eder. Kaynaklardaki kiraları alma, yenileme, serbest bırakma, değiştirme ve kesme işlemleri sağlar.

Örnekler

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

bağlantı dizesi ile istemci oluşturma

Azure Depolama hesabınıza bağlantı dizesi kullanarak DataLakeServiceClient'ı oluşturun.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

Dosyayı karşıya yükleme

Dosya sisteminize bir dosya yükleyin.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

Dosya indirme

Dosya sisteminizden bir dosya indirin.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

Yolları numaralandırma

Dosya sisteminizdeki yolları listeleyin.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

İ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

DataLake Depolama 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.filedatalake import DataLakeServiceClient

# Create a logger for the 'azure.storage.filedatalake' SDK
logger = logging.getLogger('azure.storage')
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 = DataLakeServiceClient.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.list_file_systems(logging_enable=True)

Sonraki adımlar

Daha fazla örnek kod

Azure DataLake örneklerimizi kullanmaya başlayın.

SDK'nın GitHub deposunda birkaç DataLake Depolama Python SDK'sı örneği mevcuttur. Bu örnekler DataLake Storage ile çalışırken yaygın olarak karşılaşılan ek senaryolar için örnek kod sağlar:

  • datalake_samples_access_control.py - Yaygın DataLake Depolama görevleri için örnekler:

    • Dosya sistemi ayarlama
    • Dizin oluşturma
    • Dizin için erişim denetimini ayarlama/alma
    • Dizinin altında dosya oluşturma
    • Her dosya için erişim denetimini ayarlama/alma
    • Dosya sistemini silme

  • datalake_samples_upload_download.py - Yaygın DataLake Depolama görevleri için örnekler:

    • Dosya sistemi ayarlama
    • Dosya oluştur
    • Dosyaya veri ekleme
    • Verileri dosyaya boşaltma
    • Karşıya yüklenen verileri indirme
    • Dosya sistemini silme

Diğer belgeler

ADLS 1. Nesilden ADLS 2. Nesil API Eşleme tablosu Data Lake Storage 2. Nesil hakkında daha kapsamlı REST belgeleri için docs.microsoft.com ile ilgili Data Lake Storage 2. Nesil 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 .