Pustaka klien layanan Azure DataLake untuk Python - versi 12.14.0

  • Artikel

Gambaran Umum

Paket pratinjau untuk Python ini mencakup dukungan API khusus ADLS Gen2 yang tersedia di Storage SDK. Drive ini termasuk:

  1. Operasi tingkat direktori baru (Buat, Ganti Nama, Hapus) untuk akun penyimpanan yang diaktifkan namespace hierarkis (HNS). Untuk akun yang diaktifkan HNS, operasi ganti nama/pindah adalah atomik.
  2. Operasi terkait izin (Get/Set ACL) untuk akun hierarkis namespace aktif (HNS).

Kode sumber | Paket (PyPi) | Paket (Conda) | Dokumentasi | referensi APIDokumentasi | produkSampel

Memulai

Prasyarat

Instal paketnya

Instal pustaka klien Azure DataLake Storage untuk Python dengan pip:

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

Buat akun penyimpanan

Jika Anda ingin membuat akun penyimpanan baru, Anda dapat menggunakan Portal Microsoft Azure, Azure PowerShell, atau Azure CLI:

# 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

Mengautentikasi klien

Interaksi dengan DataLake Storage dimulai dengan instans kelas DataLakeServiceClient. Anda memerlukan akun penyimpanan yang ada, URL-nya, dan kredensial untuk membuat instans objek klien.

Mendapatkan kredensial

Untuk mengautentikasi klien, Anda memiliki beberapa opsi:

  1. Menggunakan string token SAS
  2. Menggunakan kunci akses bersama akun
  3. Menggunakan kredensial token dari azure.identity

Atau, Anda dapat mengautentikasi dengan string koneksi penyimpanan menggunakan metode .from_connection_string Lihat contoh: Pembuatan klien dengan string koneksi.

Anda dapat menghilangkan kredensial jika URL akun Anda sudah memiliki token SAS.

Membuat klien

Setelah URL akun dan kredensial Anda siap, Anda dapat membuat DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Konsep utama

Penyimpanan DataLake menawarkan empat jenis sumber daya:

  • Akun penyimpanan
  • Sistem file di akun penyimpanan
  • Direktori di bawah sistem file
  • File dalam sistem file atau di bawah direktori

Klien Asinkron

Pustaka ini mencakup API asinkron lengkap yang didukung pada Python 3.5+. Untuk menggunakannya, Anda harus menginstal transportasi asinkron terlebih dahulu, seperti aiohttp. Lihat dokumentasi azure-core untuk informasi selengkapnya.

Klien dan kredensial asinkron harus ditutup ketika tidak lagi diperlukan. Objek-objek ini adalah manajer konteks asinkron dan mendefinisikan metode asinkron close .

Klien

DataLake Storage SDK menyediakan empat klien berbeda untuk berinteraksi dengan Layanan DataLake:

  1. DataLakeServiceClient - klien ini berinteraksi dengan Layanan DataLake di tingkat akun. Ini menyediakan operasi untuk mengambil dan mengonfigurasi properti akun serta mencantumkan, membuat, dan menghapus sistem file dalam akun. Untuk operasi yang berkaitan dengan sistem file, direktori, atau file tertentu, klien untuk entitas tersebut get_file_clientjuga dapat diambil menggunakan fungsi , get_directory_client atau get_file_system_client .
  2. FileSystemClient - klien ini mewakili interaksi dengan sistem file tertentu, bahkan jika sistem file tersebut belum ada. Ini menyediakan operasi untuk membuat, menghapus, atau mengonfigurasi sistem file dan menyertakan operasi untuk mencantumkan jalur di bawah sistem file, mengunggah, dan menghapus file atau direktori dalam sistem file. Untuk operasi yang berkaitan dengan file tertentu, klien juga dapat diambil menggunakan fungsi .get_file_client Untuk operasi yang berkaitan dengan direktori tertentu, klien dapat diambil menggunakan fungsi .get_directory_client
  3. DataLakeDirectoryClient - klien ini mewakili interaksi dengan direktori tertentu, bahkan jika direktori tersebut belum ada. Ini menyediakan operasi direktori membuat, menghapus, mengganti nama, mendapatkan properti dan mengatur operasi properti.
  4. DataLakeFileClient - klien ini mewakili interaksi dengan file tertentu, meskipun file tersebut belum ada. Ini menyediakan operasi file untuk menambahkan data, menghapus data, menghapus, membuat, dan membaca file.
  5. DataLakeLeaseClient - klien ini mewakili interaksi sewa dengan FileSystemClient, DataLakeDirectoryClient atau DataLakeFileClient. Ini menyediakan operasi untuk memperoleh, memperbarui, merilis, mengubah, dan memutuskan sewa pada sumber daya.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Storage DataLake yang paling umum, termasuk:

Pembuatan klien dengan string koneksi

Buat DataLakeServiceClient menggunakan string koneksi ke akun Azure Storage Anda.

from azure.storage.filedatalake import DataLakeServiceClient

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

Mengunggah file

Unggah file ke sistem file Anda.

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

Mengunduh file

Unduh file dari sistem file Anda.

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)

Menghitung jalur

Cantumkan jalur dalam sistem file Anda.

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')

Konfigurasi Opsional

Argumen kata kunci opsional yang dapat diteruskan di tingkat klien dan per operasi.

Konfigurasi Kebijakan Coba Lagi

Gunakan argumen kata kunci berikut saat membuat instans klien untuk mengonfigurasi kebijakan coba lagi:

  • retry_total (int): Jumlah total percobaan ulang yang diizinkan. Lebih diutamakan daripada hitungan lain. retry_total=0 Teruskan jika Anda tidak ingin mencoba kembali permintaan. Default ke 10.
  • retry_connect (int): Berapa banyak kesalahan terkait koneksi yang akan diulang. Default ke 3.
  • retry_read (int): Berapa kali untuk mencoba kembali kesalahan baca. Default ke 3.
  • retry_status (int): Berapa kali untuk mencoba kembali kode status yang buruk. Default ke 3.
  • retry_to_secondary (bool): Apakah permintaan harus dicoba kembali ke sekunder, jika dapat. Ini hanya boleh diaktifkan dari akun RA-GRS yang digunakan dan data yang berpotensi kedaluarsa dapat ditangani. Default ke False.

Konfigurasi klien/per operasi lainnya

Argumen kata kunci konfigurasi opsional lainnya yang dapat ditentukan pada klien atau per operasi.

Argumen kata kunci klien:

  • connection_timeout (int): Jumlah detik klien akan menunggu untuk membuat koneksi ke server. Default ke 20 detik.
  • read_timeout (int): Jumlah detik klien akan menunggu, antara operasi baca berturut-turut, untuk respons dari server. Ini adalah batas waktu tingkat soket dan tidak terpengaruh oleh ukuran data keseluruhan. Batas waktu baca sisi klien akan dicoba kembali secara otomatis. Default ke 60 detik.
  • transport (Any): Transportasi yang disediakan pengguna untuk mengirim permintaan HTTP.

Argumen kata kunci per operasi:

  • raw_response_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan respons yang dikembalikan dari layanan.
  • raw_request_hook (dapat dipanggil): Panggilan balik yang diberikan menggunakan permintaan sebelum dikirim ke layanan.
  • client_request_id (str): Identifikasi permintaan yang ditentukan pengguna opsional.
  • user_agent (str): Menambahkan nilai kustom ke header agen pengguna untuk dikirim dengan permintaan.
  • logging_enable (bool): Memungkinkan pengelogan di tingkat DEBUG. Default ke False. Juga dapat diteruskan di tingkat klien untuk mengaktifkannya untuk semua permintaan.
  • logging_body (bool): Memungkinkan pengelogan isi permintaan dan respons. Default ke False. Juga dapat diteruskan di tingkat klien untuk mengaktifkannya untuk semua permintaan.
  • header (dict): Meneruskan header kustom sebagai kunci, pasangan nilai. Misalnya headers={'CustomValue': value}

Pemecahan Masalah

Umum

Klien DataLake Storage memunculkan pengecualian yang ditentukan di Azure Core.

Daftar ini dapat digunakan untuk referensi guna menangkap pengecualian yang dilemparkan. Untuk mendapatkan kode kesalahan tertentu dari pengecualian, gunakan error_code atribut , yaitu , exception.error_code.

Pembuatan Log

Pustaka ini menggunakan pustaka pengelogan standar untuk pengelogan. Informasi dasar tentang sesi HTTP (URL, header, dll.) dicatat di tingkat INFO.

Pengelogan tingkat DEBUG terperinci, termasuk isi permintaan/respons dan header yang tidak diredaksikan, dapat diaktifkan pada klien dengan logging_enable argumen :

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)

Demikian pula, logging_enable dapat mengaktifkan pengelogan mendetail untuk satu operasi, meskipun tidak diaktifkan untuk klien:

service_client.list_file_systems(logging_enable=True)

Langkah berikutnya

Lebih banyak kode sampel

Mulai menggunakan sampel Azure DataLake kami.

Beberapa sampel DataLake Storage Python SDK tersedia untuk Anda di repositori GitHub SDK. Sampel ini menyediakan kode contoh untuk skenario tambahan yang biasa ditemui saat bekerja dengan DataLake Storage:

  • datalake_samples_access_control.py - Contoh untuk tugas DataLake Storage umum:

    • Menyiapkan sistem file
    • Buat direktori
    • Mengatur/Mendapatkan kontrol akses untuk direktori
    • Membuat file di bawah direktori
    • Mengatur/Mendapatkan kontrol akses untuk setiap file
    • Menghapus sistem file

  • datalake_samples_upload_download.py - Contoh untuk tugas DataLake Storage umum:

    • Menyiapkan sistem file
    • Membuat file
    • Menambahkan data ke file
    • Menghapus data ke file
    • Mengunduh data yang diunggah
    • Menghapus sistem file

Dokumentasi tambahan

Tabel untuk Pemetaan API ADLS Gen1 ke ADLS Gen2 Untuk dokumentasi REST yang lebih luas tentang Data Lake Storage Gen2, lihat dokumentasi Data Lake Storage Gen2 tentang docs.microsoft.com.

Berkontribusi

Proyek ini menyambut baik kontribusi dan saran. Sebagian besar kontribusi mengharuskan Anda menyetujui Perjanjian Lisensi Kontributor (CLA) yang menyatakan bahwa Anda memiliki hak untuk, dan benar-benar melakukannya, memberi kami hak untuk menggunakan kontribusi Anda. Untuk detailnya, kunjungi https://cla.microsoft.com.

Ketika Anda mengirimkan permintaan tarik, CLA-bot akan secara otomatis menentukan apakah Anda perlu memberikan CLA dan menghias PR dengan tepat (misalnya, label, komentar). Cukup ikuti instruksi yang diberikan oleh bot. Anda hanya perlu melakukan ini sekali di semua repos menggunakan CLA kami.

Proyek ini telah mengadopsi Kode Etik Sumber Terbuka Microsoft. Untuk informasi selengkapnya, lihat Tanya Jawab Umum Tata Tertib atau hubungi opencode@microsoft.com untuk pertanyaan atau komentar lainnya.