Azure Storage-filresursklientbibliotek för Python – version 12.15.0

  • Artikel

Azure File Share Storage erbjuder fullständigt hanterade filresurser i molnet som är tillgängliga via branschstandardprotokollet Server Message Block (SMB). Azure-filresurser kan monteras samtidigt av molndistributioner eller lokala distributioner av Windows, Linux och macOS. Azure-filresurser kan dessutom cachelagras på Windows-servrar med Azure File Sync för snabb åtkomst nära den plats där data används.

Azure-filresurser kan användas för att:

  • Ersätta eller komplettera lokala filservrar
  • "Lift and shift"-program
  • Förenkla molnutvecklingen med delade programinställningar, diagnostikresurs och dev/test/felsökningsverktyg

Källkod | Paket (PyPI) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Komma igång

Förutsättningar

Installera paketet

Installera Azure Storage File Share-klientbiblioteket för Python med pip:

pip install azure-storage-file-share

Skapa ett lagringskonto

Om du vill skapa ett nytt lagringskonto kan du använda Azure Portal, Azure PowerShell eller 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

Skapa klienten

Med Azure Storage File Share-klientbiblioteket för Python kan du interagera med fyra typer av resurser: själva lagringskontot, filresurser, kataloger och filer. Interaktionen med dessa resurser börjar med en instans av en klient. För att skapa ett klientobjekt behöver du lagringskontots filtjänst-URL och en autentiseringsuppgift som gör att du kan komma åt lagringskontot:

from azure.storage.fileshare import ShareServiceClient

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

Leta upp konto-URL:en

Du hittar lagringskontots filtjänst-URL med hjälp av Azure-portalen, Azure PowerShell eller 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"

Typer av autentiseringsuppgifter

Parametern credential kan anges i ett antal olika formulär, beroende på vilken typ av auktorisering du vill använda:

  1. Om du vill använda en SAS-token (signatur för delad åtkomst) anger du token som en sträng. Om din konto-URL innehåller SAS-token utelämnar du parametern för autentiseringsuppgifter. Du kan generera en SAS-token från Azure-portalen under "Signatur för delad åtkomst" eller använda någon av generate_sas() funktionerna för att skapa en sas-token för lagringskontot, resursen eller filen:

    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. Om du vill använda en delad nyckel för lagringskontot (även kallad kontonyckel eller åtkomstnyckel) anger du nyckeln som en sträng. Detta finns i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande Azure CLI-kommando:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Använd nyckeln som parameter för autentiseringsuppgifter för att autentisera klienten:

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

Skapa klienten från en anslutningssträng

Beroende på användningsfall och auktoriseringsmetod kanske du föredrar att initiera en klientinstans med en lagrings-anslutningssträng i stället för att ange kontots URL och autentiseringsuppgifter separat. Det gör du genom att skicka lagrings-anslutningssträng till klientens from_connection_string klassmetod:

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)

Anslutningssträng till ditt lagringskonto finns i Azure-portalen under avsnittet "Åtkomstnycklar" eller genom att köra följande CLI-kommando:

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

Viktiga begrepp

Följande komponenter utgör Azure File Share Service:

  • Själva lagringskontot
  • En filresurs i lagringskontot
  • En valfri hierarki med kataloger i filresursen
  • En fil i filresursen, som kan vara upp till 1 TiB i storlek

Med Azure Storage File Share-klientbiblioteket för Python kan du interagera med var och en av dessa komponenter med hjälp av ett dedikerat klientobjekt.

Async-klienter

Det här biblioteket innehåller ett fullständigt asynkront API som stöds i Python 3.5+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i dokumentationen om azure-core .

Asynkrona klienter och autentiseringsuppgifter bör stängas när de inte längre behövs. Dessa objekt är asynkrona kontexthanterare och definierar asynkrona close metoder.

Klienter

Fyra olika klienter tillhandahålls för att interagera med de olika komponenterna i filresurstjänsten:

  1. ShareServiceClient – den här klienten representerar interaktion med själva Azure-lagringskontot och gör att du kan hämta förkonfigurerade klientinstanser för att få åtkomst till filresurserna i. Den tillhandahåller åtgärder för att hämta och konfigurera tjänstegenskaper samt lista, skapa och ta bort resurser i kontot. Om du vill utföra åtgärder på en specifik resurs hämtar du en klient med hjälp av get_share_client metoden .
  2. ShareClient – den här klienten representerar interaktion med en specifik filresurs (som inte behöver finnas ännu) och gör att du kan hämta förkonfigurerade klientinstanser för att komma åt katalogerna och filerna i. Den tillhandahåller åtgärder för att skapa, ta bort, konfigurera eller skapa ögonblicksbilder av en resurs och innehåller åtgärder för att skapa och räkna upp innehållet i kataloger i den. Om du vill utföra åtgärder på en specifik katalog eller fil hämtar du en klient med hjälp av get_directory_client metoderna eller get_file_client .
  3. ShareDirectoryClient – den här klienten representerar interaktion med en specifik katalog (som inte behöver finnas ännu). Den innehåller åtgärder för att skapa, ta bort eller räkna upp innehållet i en omedelbar eller kapslad underkatalog och innehåller åtgärder för att skapa och ta bort filer i den. För åtgärder som rör en specifik underkatalog eller fil kan en klient för den entiteten också hämtas med hjälp av get_subdirectory_client funktionerna och get_file_client .
  4. ShareFileClient – den här klienten representerar interaktion med en specifik fil (som inte behöver finnas ännu). Den tillhandahåller åtgärder för att ladda upp, ladda ned, skapa, ta bort och kopiera en fil.

Mer information om namngivningsbegränsningar för sökvägar finns i Namngivning och referens av resurser, kataloger, filer och metadata.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste lagringsfilresursuppgifterna, inklusive:

Skapa en filresurs

Skapa en filresurs för att lagra dina filer

from azure.storage.fileshare import ShareClient

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

Använda async-klienten för att skapa en filresurs

from azure.storage.fileshare.aio import ShareClient

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

Ladda upp en fil

Ladda upp en fil till resursen

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)

Ladda upp en fil asynkront

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)

Ladda ned en fil

Ladda ned en fil från resursen

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)

Ladda ned en fil asynkront

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)

Visa en lista över innehållet i en katalog

Visa en lista över alla kataloger och filer under en överordnad katalog

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)

Visa en lista över innehållet i en katalog asynkront

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)

Valfri konfiguration

Valfria nyckelordsargument som kan skickas på klient- och åtgärdsnivå.

Konfiguration av återförsöksprincip

Använd följande nyckelordsargument när du instansierar en klient för att konfigurera återförsöksprincipen:

  • retry_total (int): Totalt antal återförsök att tillåta. Har företräde framför andra antal. Skicka in retry_total=0 om du inte vill försöka igen på begäranden. Standardvärdet är 10.
  • retry_connect (int): Hur många anslutningsrelaterade fel som ska försöka igen. Standardvärdet är 3.
  • retry_read (int): Hur många gånger läsfel ska försöka igen. Standardvärdet är 3.
  • retry_status (int): Hur många gånger du försöker igen med felaktiga statuskoder. Standardvärdet är 3.
  • retry_to_secondary (bool): Om begäran ska prövas på nytt till sekundär, om det går. Detta bör endast aktiveras för RA-GRS-konton som används och potentiellt inaktuella data kan hanteras. Standardvärdet är False.

Annan klient/per åtgärd-konfiguration

Andra valfria nyckelordsargument för konfiguration som kan anges för klienten eller per åtgärd.

Argument för klientnyckelord:

  • connection_timeout (int): Antalet sekunder som klienten väntar på att upprätta en anslutning till servern. Standardvärdet är 20 sekunder.
  • read_timeout (int): Antalet sekunder som klienten väntar, mellan efterföljande läsåtgärder, på ett svar från servern. Det här är en tidsgräns på socketnivå och påverkas inte av den totala datastorleken. Tidsgränser för läsning på klientsidan görs automatiskt på nytt. Standardvärdet är 60 sekunder.
  • transport (alla): Transport som tillhandahålls av användaren för att skicka HTTP-begäran.

Nyckelordsargument per åtgärd:

  • raw_response_hook (anropsbar): Det angivna återanropet använder svaret som returneras från tjänsten.
  • raw_request_hook (anropsbar): Den angivna motringningen använder begäran innan den skickas till tjänsten.
  • client_request_id (str): Valfri användare har angett identifiering av begäran.
  • user_agent (str): Lägger till det anpassade värdet i användaragenthuvudet som ska skickas med begäran.
  • logging_enable (bool): Aktiverar loggning på felsökningsnivå. Standardvärdet är Falskt. Kan också skickas in på klientnivå för att aktivera den för alla begäranden.
  • logging_body (bool): Aktiverar loggning av begäran och svarstext. Standardvärdet är Falskt. Kan också skickas in på klientnivå för att aktivera den för alla begäranden.
  • headers (dict): Skicka in anpassade rubriker som nyckel, värdepar. E.g. headers={'CustomValue': value}

Felsökning

Allmänt

Storage File-klienter genererar undantag som definierats i Azure Core.

Den här listan kan användas som referens för att fånga undantag som genereras. Om du vill hämta den specifika felkoden för undantaget använder du error_code attributet, t.ex. exception.error_code.

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

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)

logging_enable På samma sätt kan du aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

service_client.get_service_properties(logging_enable=True)

Nästa steg

Mer exempelkod

Kom igång med våra filresursexempel.

Flera Python SDK-exempel för lagringsfilresurs är tillgängliga på SDK:s GitHub-lagringsplats. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med Lagringsfilresurs:

Ytterligare dokumentation

Mer omfattande dokumentation om Azure File Share Storage finns i Azure File Share Storage-dokumentationen om docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.