Delen via

Azure Storage File Share-clientbibliotheek voor Python - versie 12.15.0

  • Artikel

Azure File Share Storage biedt volledig beheerde bestandsshares in de cloud die toegankelijk zijn via het standaard SMB-protocol (Server Message Block). Azure-bestandsshares kunnen gelijktijdig worden gekoppeld door on-premises implementaties of cloudimplementaties van Windows, Linux en macOS. Bovendien kunnen Azure-bestandsshares worden opgeslagen in de cache op Windows-servers met Azure-bestandssynchronisatie voor snelle toegang tot locaties waar de gegevens worden gebruikt.

Azure-bestandsshares kunnen worden gebruikt voor het volgende:

  • On-premises bestandsservers vervangen of aanvullen
  • 'Lift and Shift'-toepassingen
  • Cloudontwikkeling vereenvoudigen met gedeelde toepassingsinstellingen, diagnostische share en hulpprogramma's voor ontwikkelen/testen/foutopsporing

Broncode | Pakket (PyPI) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure Storage File Share-clientbibliotheek voor Python met pip:

pip install azure-storage-file-share

Create a storage account

Als u een nieuw opslagaccount wilt maken, kunt u azure portal, Azure PowerShell of Azure CLI gebruiken:

# 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

De client maken

Met de Azure Storage File Share-clientbibliotheek voor Python kunt u communiceren met vier typen resources: het opslagaccount zelf, bestandsshares, mappen en bestanden. Interactie met deze resources begint met een exemplaar van een client. Als u een clientobject wilt maken, hebt u de URL van de bestandsservice van het opslagaccount en een referentie nodig waarmee u toegang hebt tot het opslagaccount:

from azure.storage.fileshare import ShareServiceClient

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

De account-URL opzoeken

U kunt de URL van de bestandsservice van het opslagaccount vinden via azure portal, Azure PowerShell of 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"

Typen referenties

De credential parameter kan in een aantal verschillende vormen worden opgegeven, afhankelijk van het type autorisatie dat u wilt gebruiken:

  1. Als u een SAS-token (Shared Access Signature) wilt gebruiken, geeft u het token op als een tekenreeks. Als uw account-URL het SAS-token bevat, laat u de referentieparameter weg. U kunt een SAS-token genereren vanuit Azure Portal onder Shared Access Signature of een van de generate_sas() functies gebruiken om een SAS-token te maken voor het opslagaccount, de share of het bestand:

    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. Als u een gedeelde sleutel voor een opslagaccount (ook wel accountsleutel of toegangssleutel genoemd) wilt gebruiken, geeft u de sleutel op als een tekenreeks. U vindt dit in Azure Portal onder de sectie Toegangssleutels of door de volgende Azure CLI-opdracht uit te voeren:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Gebruik de sleutel als referentieparameter om de client te verifiëren:

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

De client maken op basis van een verbindingsreeks

Afhankelijk van uw use-case en autorisatiemethode kunt u een clientexemplaar initialiseren met een opslag-verbindingsreeks in plaats van de account-URL en referenties afzonderlijk op te geven. Hiervoor geeft u de opslag-verbindingsreeks door aan de klassemethode van from_connection_string de client:

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)

De verbindingsreeks voor uw opslagaccount vindt u in Azure Portal onder de sectie Toegangssleutels of door de volgende CLI-opdracht uit te voeren:

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

Belangrijkste concepten

De Azure File Share-service bestaat uit de volgende onderdelen:

  • Het opslagaccount zelf
  • Een bestandsshare in het opslagaccount
  • Een optionele hiërarchie van mappen in de bestandsshare
  • Een bestand in de bestandsshare, dat maximaal 1 TiB groot kan zijn

Met de Azure Storage File Share-clientbibliotheek voor Python kunt u communiceren met elk van deze onderdelen door gebruik te maken van een toegewezen clientobject.

Asynchrone clients

Deze bibliotheek bevat een volledige asynchrone API die wordt ondersteund in Python 3.5+. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.

Asynchrone clients en referenties moeten worden gesloten wanneer ze niet meer nodig zijn. Deze objecten zijn asynchrone contextbeheerders en definiëren asynchrone close methoden.

Clients

Er zijn vier verschillende clients beschikbaar om te communiceren met de verschillende onderdelen van de file share-service:

  1. ShareServiceClient : deze client vertegenwoordigt interactie met het Azure-opslagaccount zelf en stelt u in staat om vooraf geconfigureerde clientexemplaren te verkrijgen voor toegang tot de bestandsshares binnen. Het biedt bewerkingen voor het ophalen en configureren van de service-eigenschappen, evenals het weergeven, maken en verwijderen van shares in het account. Als u bewerkingen wilt uitvoeren op een specifieke share, haalt u een client op met behulp van de get_share_client methode .
  2. ShareClient : deze client vertegenwoordigt interactie met een specifieke bestandsshare (die nog niet hoeft te bestaan) en stelt u in staat om vooraf geconfigureerde clientexemplaren te verkrijgen voor toegang tot de mappen en bestanden erin. Het biedt bewerkingen voor het maken, verwijderen, configureren of maken van momentopnamen van een share en bevat bewerkingen om de inhoud van mappen in de share te maken en op te sommen. Als u bewerkingen wilt uitvoeren op een specifieke map of bestand, haalt u een client op met behulp van de get_directory_client methoden of get_file_client .
  3. ShareDirectoryClient : deze client vertegenwoordigt interactie met een specifieke map (die nog niet hoeft te bestaan). Het biedt bewerkingen voor het maken, verwijderen of inventariseren van de inhoud van een directe of geneste submap, en bevat bewerkingen voor het maken en verwijderen van bestanden in de map. Voor bewerkingen die betrekking hebben op een specifieke submap of een specifiek bestand, kan ook een client voor die entiteit worden opgehaald met behulp van de get_subdirectory_client functies en get_file_client .
  4. ShareFileClient : deze client vertegenwoordigt interactie met een specifiek bestand (dat nog niet hoeft te bestaan). Het biedt bewerkingen voor het uploaden, downloaden, maken, verwijderen en kopiëren van een bestand.

Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevens voor meer informatie over padnaambeperkingen.

Voorbeelden

De volgende secties bevatten verschillende codefragmenten die betrekking hebben op enkele van de meest voorkomende taken van de Opslagbestandsshare, waaronder:

Een bestandsshare maken

Een bestandsshare maken om uw bestanden op te slaan

from azure.storage.fileshare import ShareClient

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

De asynchrone client gebruiken om een bestandsshare te maken

from azure.storage.fileshare.aio import ShareClient

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

Een bestand uploaden

Een bestand uploaden naar de share

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)

Een bestand asynchroon uploaden

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)

Een bestand downloaden

Een bestand downloaden van de share

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)

Een bestand asynchroon downloaden

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)

Inhoud van een map weergeven

Alle mappen en bestanden onder een bovenliggende map weergeven

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)

Inhoud van een map asynchroon weergeven

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)

Optionele configuratie

Optionele trefwoordargumenten die kunnen worden doorgegeven op client- en bewerkingsniveau.

Configuratie van beleid opnieuw proberen

Gebruik de volgende trefwoordargumenten bij het instantiëren van een client om het beleid voor opnieuw proberen te configureren:

  • retry_total (int): totaal aantal nieuwe pogingen dat is toegestaan. Heeft voorrang op andere aantallen. Geef door retry_total=0 als u aanvragen niet opnieuw wilt proberen. De standaardwaarde is 10.
  • retry_connect (int): hoeveel verbindingsgerelateerde fouten u opnieuw wilt proberen. Standaardwaarde is 3.
  • retry_read (int): hoe vaak moet u het opnieuw proberen bij leesfouten. Standaardwaarde is 3.
  • retry_status (int): hoe vaak moet u een ongeldige statuscode opnieuw proberen. Standaardwaarde is 3.
  • retry_to_secondary (bool): of de aanvraag opnieuw moet worden geprobeerd om secundair te worden, indien mogelijk. Dit mag alleen worden ingeschakeld wanneer RA-GRS-accounts worden gebruikt en mogelijk verouderde gegevens kunnen worden verwerkt. De standaardwaarde is False.

Andere client/configuratie per bewerking

Andere optionele trefwoordargumenten voor configuratie die kunnen worden opgegeven op de client of per bewerking.

Argumenten voor clientwoorden:

  • connection_timeout (int): het aantal seconden dat de client wacht om verbinding te maken met de server. De standaardwaarde is 20 seconden.
  • read_timeout (int): het aantal seconden dat de client tussen opeenvolgende leesbewerkingen wacht op een antwoord van de server. Dit is een time-out op socketniveau en wordt niet beïnvloed door de totale gegevensgrootte. Time-outs voor lezen aan de clientzijde worden automatisch opnieuw geprobeerd. De standaardwaarde is 60 seconden.
  • transport (alle): door de gebruiker opgegeven transport om de HTTP-aanvraag te verzenden.

Trefwoordargumenten per bewerking:

  • raw_response_hook (aanroepbaar): de opgegeven callback maakt gebruik van het antwoord dat is geretourneerd door de service.
  • raw_request_hook (aanroepbaar): de opgegeven callback maakt gebruik van de aanvraag voordat deze naar de service wordt verzonden.
  • client_request_id (str): optioneel door de gebruiker opgegeven identificatie van de aanvraag.
  • user_agent (str): voegt de aangepaste waarde toe aan de header user-agent die met de aanvraag moet worden verzonden.
  • logging_enable (bool): hiermee schakelt u logboekregistratie in op het niveau VAN FOUTOPSPORING. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • logging_body (bool): hiermee schakelt u logboekregistratie van de aanvraag- en antwoordtekst in. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • headers (dict): geef aangepaste headers door als sleutel, waardeparen. Bijvoorbeeld. headers={'CustomValue': value}

Problemen oplossen

Algemeen

Opslagbestandsclients genereren uitzonderingen die zijn gedefinieerd in Azure Core.

Deze lijst kan worden gebruikt ter referentie om opgetreden uitzonderingen te ondervangen. Als u de specifieke foutcode van de uitzondering wilt ophalen, gebruikt u het error_code kenmerk, dat wil zeggen exception.error_code.

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable argument:

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)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

service_client.get_service_properties(logging_enable=True)

Volgende stappen

Meer voorbeeldcode

Ga aan de slag met onze bestandssharevoorbeelden.

In de GitHub-opslagplaats van de SDK van de SDK zijn verschillende Python SDK-voorbeelden voor opslagbestandsshares beschikbaar. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met de opslagbestandsshare:

Aanvullende documentatie

Zie de documentatie voor Azure File Share Storage op docs.microsoft.com voor uitgebreidere documentatie over Azure File Share Storage .

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.