Udostępnij za pośrednictwem

Biblioteka klienta udziału plików usługi Azure Storage dla języka Python — wersja 12.15.0

  • Artykuł

Magazyn udziałów plików platformy Azure oferuje w pełni zarządzane udziały plików w chmurze, które są dostępne za pośrednictwem standardowego protokołu SMB (Server Message Block). Udziały plików platformy Azure można instalować współbieżnie za pośrednictwem chmurowych lub lokalnych wdrożeń systemów Windows, Linux i macOS. Ponadto udziały plików platformy Azure mogą być buforowane w systemach Windows Server za pomocą usługi Azure File Sync w celu zapewnienia szybkiego dostępu blisko miejsca, w którym dane są używane.

Udziały plików platformy Azure mogą być używane w następujących celach:

  • Zastępowanie lub uzupełnianie lokalnych serwerów plików
  • Aplikacje "Lift and shift"
  • Upraszczanie tworzenia aplikacji w chmurze za pomocą udostępnionych ustawień aplikacji, udziału diagnostycznego i narzędzi do tworzenia i testowania/debugowania

Kod | źródłowyPakiet (PyPI) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Wprowadzenie

Wymagania wstępne

Instalowanie pakietu

Zainstaluj bibliotekę klienta udziału plików usługi Azure Storage dla języka Python za pomocą narzędzia pip:

pip install azure-storage-file-share

Tworzenie konta magazynu

Jeśli chcesz utworzyć nowe konto magazynu, możesz użyć witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure:

# 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

Tworzenie klienta

Biblioteka klienta udziału plików usługi Azure Storage dla języka Python umożliwia interakcję z czterema typami zasobów: samym kontem magazynu, udziałami plików, katalogami i plikami. Interakcja z tymi zasobami rozpoczyna się od wystąpienia klienta. Aby utworzyć obiekt klienta, musisz mieć adres URL usługi plików konta magazynu i poświadczenia umożliwiające dostęp do konta magazynu:

from azure.storage.fileshare import ShareServiceClient

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

Szukanie adresu URL konta

Adres URL usługi plików konta magazynu można znaleźć za pomocą witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy Azure:

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

Typy poświadczeń

Parametr credential może być podany w wielu różnych formularzach w zależności od typu autoryzacji , którego chcesz użyć:

  1. Aby użyć tokenu sygnatury dostępu współdzielonego (SAS), podaj token jako ciąg. Jeśli adres URL konta zawiera token SAS, pomiń parametr poświadczeń. Token SAS można wygenerować w witrynie Azure Portal w obszarze "Sygnatura dostępu współdzielonego" lub użyć jednej z generate_sas() funkcji do utworzenia tokenu sas dla konta magazynu, udziału lub pliku:

    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. Aby użyć klucza współużytkowanego konta magazynu (klucza konta lub klucza dostępu), podaj klucz jako ciąg. Można to znaleźć w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia platformy Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Użyj klucza jako parametru poświadczeń, aby uwierzytelnić klienta:

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

Tworzenie klienta na podstawie parametry połączenia

W zależności od przypadku użycia i metody autoryzacji wolisz zainicjować wystąpienie klienta przy użyciu parametry połączenia magazynu zamiast oddzielnie podać adres URL konta i poświadczenia. W tym celu przekaż parametry połączenia magazynu do metody klasy klientafrom_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)

Parametry połączenia konta magazynu można znaleźć w witrynie Azure Portal w sekcji "Klucze dostępu" lub uruchamiając następujące polecenie interfejsu wiersza polecenia:

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

Kluczowe pojęcia

Następujące składniki składają się na usługę udziału plików platformy Azure:

  • Samo konto magazynu
  • Udział plików na koncie magazynu
  • Opcjonalna hierarchia katalogów w udziale plików
  • Plik w udziale plików, który może mieć rozmiar maksymalnie 1 TiB

Biblioteka klienta udziału plików usługi Azure Storage dla języka Python umożliwia interakcję z każdym z tych składników za pomocą dedykowanego obiektu klienta.

Klienci asynchroniczny

Ta biblioteka zawiera kompletny asynchroniczny interfejs API obsługiwany w języku Python 3.5 lub nowszym. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczne i poświadczenia powinny być zamykane, gdy nie są już potrzebne. Te obiekty są menedżerami kontekstu asynchronicznego i definiują metody asynchroniczne close .

Klienci

Czterech różnych klientów jest udostępnianych do interakcji z różnymi składnikami usługi udostępniania plików:

  1. ShareServiceClient — ten klient reprezentuje interakcję z samym kontem usługi Azure Storage i umożliwia uzyskanie wstępnie skonfigurowanych wystąpień klienta w celu uzyskania dostępu do udziałów plików w ramach programu . Zapewnia ona operacje pobierania i konfigurowania właściwości usługi, a także tworzenia i usuwania udziałów na koncie. Aby wykonać operacje na określonym udziale, pobierz klienta przy użyciu get_share_client metody .
  2. ShareClient — ten klient reprezentuje interakcję z określonym udziałem plików (który nie musi jeszcze istnieć) i umożliwia uzyskanie wstępnie skonfigurowanych wystąpień klienta w celu uzyskania dostępu do katalogów i plików w programie . Zapewnia ona operacje tworzenia, usuwania, konfigurowania lub tworzenia migawek udziału oraz obejmuje operacje tworzenia i wyliczania zawartości katalogów. Aby wykonać operacje na określonym katalogu lub pliku, pobierz klienta przy użyciu get_directory_client metod lub get_file_client .
  3. ShareDirectoryClient — ten klient reprezentuje interakcję z określonym katalogiem (który nie musi jeszcze istnieć). Zapewnia ona operacje tworzenia, usuwania lub wyliczania zawartości podkatalogu natychmiastowego lub zagnieżdżonego oraz obejmuje operacje tworzenia i usuwania w nim plików. W przypadku operacji związanych z określonym podkatalogem lub plikiem można również pobrać klienta dla tej jednostki przy użyciu get_subdirectory_client funkcji i get_file_client .
  4. ShareFileClient — ten klient reprezentuje interakcję z określonym plikiem (który nie musi jeszcze istnieć). Zapewnia ona operacje przekazywania, pobierania, tworzenia, usuwania i kopiowania pliku.

Aby uzyskać szczegółowe informacje na temat ograniczeń nazewnictwa ścieżek, zobacz Nazewnictwo i odwoływanie się do udziałów, katalogów, plików i metadanych.

Przykłady

Poniższe sekcje zawierają kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań udziału plików magazynu, w tym:

Tworzenie udziału plików

Tworzenie udziału plików do przechowywania plików

from azure.storage.fileshare import ShareClient

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

Tworzenie udziału plików za pomocą klienta asynchronicznego

from azure.storage.fileshare.aio import ShareClient

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

Przekazywanie pliku

Przekazywanie pliku do udziału

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)

Asynchronicznie przekaż plik

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)

Pobieranie pliku

Pobieranie pliku z udziału

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)

Pobieranie pliku asynchronicznie

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)

Wyświetlanie zawartości katalogu

Wyświetlanie listy wszystkich katalogów i plików w katalogu nadrzędnym

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)

Asynchroniczna lista zawartości katalogu

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)

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych, które można przekazać na poziomie klienta i na poziomie operacji.

Konfiguracja zasad ponawiania

Podczas tworzenia wystąpienia klienta w celu skonfigurowania zasad ponawiania należy użyć następujących argumentów słów kluczowych:

  • retry_total (int): całkowita liczba ponownych prób do zezwolenia. Ma pierwszeństwo przed innymi liczbami. Przekaż, retry_total=0 jeśli nie chcesz ponawiać prób na żądaniach. Wartość domyślna to 10.
  • retry_connect (int): ile błędów związanych z połączeniem należy ponowić próbę. Wartość domyślna to 3.
  • retry_read (int): ile razy należy ponowić próbę w przypadku błędów odczytu. Wartość domyślna to 3.
  • retry_status (int): ile razy należy ponowić próbę w przypadku kodów złego stanu. Wartość domyślna to 3.
  • retry_to_secondary (wartość logiczna): czy żądanie powinno zostać ponowione do pomocniczego, jeśli jest możliwe. Powinno być włączone tylko konta RA-GRS są używane i potencjalnie nieaktualne dane mogą być obsługiwane. Wartość domyślna to False.

Inna konfiguracja klienta /na operację

Inne opcjonalne argumenty słowa kluczowego konfiguracji, które można określić na kliencie lub na operację.

Argumenty słów kluczowych klienta:

  • connection_timeout (int): liczba sekund oczekiwania klienta na nawiązanie połączenia z serwerem. Wartość domyślna to 20 sekund.
  • read_timeout (int): liczba sekund oczekiwania klienta między kolejnymi operacjami odczytu na odpowiedź z serwera. Jest to limit czasu na poziomie gniazda i nie ma to wpływu na ogólny rozmiar danych. Limity czasu odczytu po stronie klienta będą automatycznie ponawiane. Wartość domyślna to 60 sekund.
  • transport (dowolny): transport dostarczony przez użytkownika w celu wysłania żądania HTTP.

Argumenty słów kluczowych dla operacji:

  • raw_response_hook (możliwe do wywołania): Podane wywołanie zwrotne używa odpowiedzi zwróconej z usługi.
  • raw_request_hook (możliwe do wywołania): podane wywołanie zwrotne używa żądania przed wysłaniem do usługi.
  • client_request_id (str): opcjonalna identyfikacja żądania przez użytkownika opcjonalnego.
  • user_agent (str): dołącza wartość niestandardową do nagłówka user-agent, który ma zostać wysłany za pomocą żądania.
  • logging_enable (bool): włącza rejestrowanie na poziomie DEBUG. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • logging_body (bool): włącza rejestrowanie treści żądania i odpowiedzi. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
  • nagłówki (dict): przekazuj niestandardowe nagłówki jako pary klucz, wartość. Przykład. headers={'CustomValue': value}

Rozwiązywanie problemów

Ogólne

Klienci plików magazynu zgłaszają wyjątki zdefiniowane w usłudze Azure Core.

Ta lista może służyć do przywoływania zgłaszanych wyjątków. Aby uzyskać określony kod błędu wyjątku, użyj atrybutu error_code , exception.error_codetj. .

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem logging_enable :

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)

Podobnie może logging_enable włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

service_client.get_service_properties(logging_enable=True)

Następne kroki

Więcej przykładów kodu

Rozpocznij pracę z przykładami udziału plików.

Kilka przykładów zestawu SDK udziału plików magazynu w języku Python jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy często napotykanych podczas pracy z udziałem plików magazynu:

Dodatkowa dokumentacja

Aby uzyskać bardziej obszerną dokumentację dotyczącą usługi Azure File Share Storage, zobacz dokumentację usługi Azure File Share Storage dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.