Pustaka klien Azure Storage File Share untuk Python - versi 12.15.0

  • Artikel

Penyimpanan Azure File Share menawarkan berbagi file yang dikelola sepenuhnya di cloud yang dapat diakses melalui protokol Server Message Block (SMB) standar industri. Berbagi file Azure dapat dipasang bersamaan dengan penyebaran Windows, Linux, dan macOS cloud atau lokal. Selain itu, berbagi file Azure dapat di-cache di Windows Server dengan Azure File Sync untuk akses cepat di dekat tempat data digunakan.

Azure file share bisa digunakan untuk:

  • Ganti atau lengkapi server file lokal
  • Aplikasi "Angkat dan geser"
  • Menyederhanakan pengembangan cloud dengan pengaturan aplikasi bersama, berbagi diagnostik, dan alat Dev/Test/Debug

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

Memulai

Prasyarat

Instal paketnya

Instal pustaka klien Azure Storage File Share untuk Python dengan pip:

pip install azure-storage-file-share

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

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

Membuat klien

Pustaka klien Azure Storage File Share untuk Python memungkinkan Anda berinteraksi dengan empat jenis sumber daya: akun penyimpanan itu sendiri, berbagi file, direktori, dan file. Interaksi dengan sumber daya ini dimulai dengan instans klien. Untuk membuat objek klien, Anda memerlukan URL layanan file akun penyimpanan dan kredensial yang memungkinkan Anda mengakses akun penyimpanan:

from azure.storage.fileshare import ShareServiceClient

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

Mencari URL akun

Anda dapat menemukan URL layanan file akun penyimpanan menggunakan Portal Microsoft Azure, Azure PowerShell, atau Azure CLI:

# 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"

Jenis kredensial

Parameter credential dapat disediakan dalam sejumlah formulir yang berbeda, tergantung pada jenis otorisasi yang ingin Anda gunakan:

  1. Untuk menggunakan token tanda tangan akses bersama (SAS), berikan token sebagai string. Jika URL akun Anda menyertakan token SAS, hilangkan parameter kredensial. Anda dapat membuat token SAS dari Portal Microsoft Azure di bawah "Tanda tangan akses bersama" atau menggunakan salah generate_sas() satu fungsi untuk membuat token sas untuk akun penyimpanan, berbagi, atau file:

    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. Untuk menggunakan kunci bersama akun penyimpanan (kunci akun atau kunci akses), berikan kunci sebagai string. Ini dapat ditemukan di Portal Microsoft Azure di bawah bagian "Kunci Akses" atau dengan menjalankan perintah Azure CLI berikut:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Gunakan kunci sebagai parameter kredensial untuk mengautentikasi klien:

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

Membuat klien dari string koneksi

Bergantung pada kasus penggunaan dan metode otorisasi, Anda mungkin lebih suka menginisialisasi instans klien dengan string koneksi penyimpanan alih-alih memberikan URL akun dan kredensial secara terpisah. Untuk melakukan ini, teruskan string koneksi penyimpanan ke metode kelas klienfrom_connection_string:

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)

string koneksi ke akun penyimpanan Anda dapat ditemukan di Portal Microsoft Azure di bagian "Kunci Akses" atau dengan menjalankan perintah CLI berikut:

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

Konsep utama

Komponen berikut membentuk Azure File Share Service:

  • Akun penyimpanan itu sendiri
  • Berbagi file dalam akun penyimpanan
  • Hierarki direktori opsional dalam berbagi file
  • File dalam berbagi file, yang mungkin berukuran hingga 1 TiB

Pustaka klien Azure Storage File Share untuk Python memungkinkan Anda berinteraksi dengan masing-masing komponen ini melalui penggunaan objek klien khusus.

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 ini adalah manajer konteks asinkron dan menentukan metode asinkron close .

Klien

Empat klien yang berbeda disediakan untuk berinteraksi dengan berbagai komponen Layanan Berbagi File:

  1. ShareServiceClient - klien ini mewakili interaksi dengan akun penyimpanan Azure itu sendiri, dan memungkinkan Anda memperoleh instans klien yang telah dikonfigurasi sebelumnya untuk mengakses berbagi file di dalamnya. Ini menyediakan operasi untuk mengambil dan mengonfigurasi properti layanan serta mencantumkan, membuat, dan menghapus berbagi dalam akun. Untuk melakukan operasi pada berbagi tertentu, ambil klien menggunakan metode .get_share_client
  2. ShareClient - klien ini mewakili interaksi dengan berbagi file tertentu (yang belum ada), dan memungkinkan Anda memperoleh instans klien yang telah dikonfigurasi sebelumnya untuk mengakses direktori dan file di dalamnya. Ini menyediakan operasi untuk membuat, menghapus, mengonfigurasi, atau membuat rekam jepret dari berbagi dan menyertakan operasi untuk membuat dan menghitung konten direktori di dalamnya. Untuk melakukan operasi pada direktori atau file tertentu, ambil klien menggunakan get_directory_client metode atau get_file_client .
  3. ShareDirectoryClient - klien ini mewakili interaksi dengan direktori tertentu (yang belum ada). Ini menyediakan operasi untuk membuat, menghapus, atau menghitung konten subdirektori langsung atau berlapis, dan mencakup operasi untuk membuat dan menghapus file di dalamnya. Untuk operasi yang berkaitan dengan subdirektori atau file tertentu, klien untuk entitas tersebut get_subdirectory_client juga dapat diambil menggunakan fungsi dan get_file_client .
  4. ShareFileClient - klien ini mewakili interaksi dengan file tertentu (yang belum ada). Ini menyediakan operasi untuk mengunggah, mengunduh, membuat, menghapus, dan menyalin file.

Untuk detail tentang pembatasan penamaan jalur, lihat Penamaan dan Referensi Berbagi, Direktori, File, dan Metadata.

Contoh

Bagian berikut ini menyediakan beberapa cuplikan kode yang mencakup beberapa tugas Berbagi File Penyimpanan yang paling umum, termasuk:

Membuat berbagi file

Membuat berbagi file untuk menyimpan file Anda

from azure.storage.fileshare import ShareClient

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

Menggunakan klien asinkron untuk membuat berbagi file

from azure.storage.fileshare.aio import ShareClient

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

Mengunggah file

Mengunggah file ke berbagi

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)

Mengunggah file secara asinkron

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)

Mengunduh file

Mengunduh file dari berbagi

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)

Mengunduh file secara asinkron

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)

Mencantumkan konten direktori

Mencantumkan semua direktori dan file di bawah direktori induk

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)

Mencantumkan konten direktori secara asinkron

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)

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 ulang 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): Mengaktifkan 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 File Penyimpanan menaikkan pengecualian yang ditentukan dalam Azure Core.

Daftar ini dapat digunakan untuk referensi untuk 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 diredaktifkan, dapat diaktifkan pada klien dengan logging_enable argumen :

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)

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

service_client.get_service_properties(logging_enable=True)

Langkah berikutnya

Lebih banyak kode sampel

Mulai menggunakan sampel Berbagi File kami.

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

Dokumentasi tambahan

Untuk dokumentasi yang lebih luas tentang penyimpanan Azure File Share, lihat dokumentasi penyimpanan Azure File Share di 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.