Condividi tramite

DataLakeServiceClient Classe

  • Riferimento

Un client per interagire con il servizio DataLake a livello di account.

Questo client fornisce operazioni per recuperare e configurare le proprietà dell'account e l'elenco, creare ed eliminare file system all'interno dell'account. Per le operazioni relative a un file system, una directory o un file specifico, i client per tali entità possono essere recuperati anche usando le funzioni di get_client .

Ereditarietà
azure.storage.filedatalake._shared.base_client.StorageAccountHostsMixin
DataLakeServiceClient

Costruttore

DataLakeServiceClient(account_url: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any)

Parametri

account_url
str
Necessario

URL dell'account di archiviazione DataLake. Tutte le altre entità incluse nel percorso URL (ad esempio file system o file) verranno rimosse. Questo URL può essere autenticato facoltativamente con un token di firma di accesso condiviso.

credential
valore predefinito: None

Credenziali con cui eseguire l'autenticazione. Questo è facoltativo se l'URL dell'account ha già un token di firma di accesso condiviso. Il valore può essere una stringa di token sas, un'istanza di AzureSasCredential o AzureNamedKeyCredential da azure.core.credential, una chiave di accesso condiviso dell'account o un'istanza di una classe TokenCredentials da azure.identity. Se l'URI della risorsa contiene già un token di firma di accesso condiviso, questo verrà ignorato a favore di una credenziale esplicita

  • tranne nel caso di AzureSasCredential, in cui i token sas in conflitto genereranno un valoreError. Se si usa un'istanza di AzureNamedKeyCredential, "name" deve essere il nome dell'account di archiviazione e "key" deve essere la chiave dell'account di archiviazione.
api_version
str

Versione dell'API di archiviazione da usare per le richieste. Il valore predefinito è la versione del servizio più recente compatibile con l'SDK corrente. L'impostazione su una versione precedente può comportare una riduzione della compatibilità delle funzionalità.

Esempio

Creazione della stringa di connessione DataLakeServiceClient.


   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

Creazione di DataLakeServiceClient con le credenziali di Identità di Azure.


   from azure.identity import ClientSecretCredential
   token_credential = ClientSecretCredential(
       self.active_directory_tenant_id,
       self.active_directory_application_id,
       self.active_directory_application_secret,
   )
   datalake_service_client = DataLakeServiceClient("https://{}.dfs.core.windows.net".format(self.account_name),
                                                   credential=token_credential)

Variabili

url
str

URL completo dell'endpoint per l'endpoint del servizio datalake.

primary_endpoint
str

URL dell'endpoint primario completo.

primary_hostname
str

Nome host dell'endpoint primario.

Metodi

close

Questo metodo consiste nel chiudere i socket aperti dal client. Non è necessario usare quando si usa con un gestore di contesto.
create_file_system

Crea un nuovo file system nell'account specificato.

Se il file system con lo stesso nome esiste già, verrà generato un oggetto ResourceExistsError. Questo metodo restituisce un client con cui interagire con il file system appena creato.
delete_file_system

Contrassegna il file system specificato per l'eliminazione.

Il file system e tutti i file contenuti all'interno vengono eliminati in seguito durante la Garbage Collection. Se il file system non viene trovato, verrà generato un oggetto ResourceNotFoundError.
from_connection_string

Creare DataLakeServiceClient da una stringa di connessione.

:return a DataLakeServiceClient :rtype ~azure.storage.filedatalake.DataLakeServiceClient
get_directory_client

Ottenere un client per interagire con la directory specificata.

La directory non esiste già.
get_file_client

Ottenere un client per interagire con il file specificato.

Il file non esiste già.
get_file_system_client

Ottenere un client per interagire con il file system specificato.

Il file system non esiste già.
get_service_properties

Ottiene le proprietà del servizio datalake di un account di archiviazione, tra cui Azure Analisi archiviazione.

Novità nella versione 12.4.0: questa operazione è stata introdotta nella versione API '2020-06-12'.
get_user_delegation_key

Ottenere una chiave di delega utente allo scopo di firmare i token di firma di accesso condiviso. Una credenziale del token deve essere presente nell'oggetto del servizio per la riuscita della richiesta.
list_file_systems

Restituisce un generatore per elencare i file system nell'account specificato.

Il generatore seguirà i token di continuazione restituiti dal servizio e arresterà quando tutti i file system sono stati restituiti.
set_service_properties

Imposta le proprietà del servizio Datalake di un account di archiviazione, tra cui Azure Analisi archiviazione.

Novità nella versione 12.4.0: questa operazione è stata introdotta nella versione API '2020-06-12'.

Se un elemento (ad esempio, analytics_logging) viene lasciato come Nessuno, le impostazioni esistenti nel servizio per tale funzionalità vengono mantenute.
undelete_file_system

Ripristina il file system eliminato temporanea.

L'operazione avrà esito positivo solo se viene usato entro il numero di giorni specificato impostato nei criteri di conservazione di eliminazione.

Novità nella versione 12.3.0: questa operazione è stata introdotta nella versione API '2019-12-12'.

close

Questo metodo consiste nel chiudere i socket aperti dal client. Non è necessario usare quando si usa con un gestore di contesto.

close() -> None

create_file_system

Crea un nuovo file system nell'account specificato.

Se il file system con lo stesso nome esiste già, verrà generato un oggetto ResourceExistsError. Questo metodo restituisce un client con cui interagire con il file system appena creato.

create_file_system(file_system: FileSystemProperties | str, metadata: Dict[str, str] | None = None, public_access: PublicAccess | None = None, **kwargs) -> FileSystemClient

Parametri

file_system
str
Necessario

Nome del file system da creare.

metadata
dict(str, str)
Necessario

Una dict con coppie nome-valore da associare al file system come metadati. Esempio: {'Category':'test'}

public_access
PublicAccess
Necessario

I valori possibili includono: file system, file.

encryption_scope_options
dict oppure EncryptionScopeOptions

Specifica l'ambito di crittografia predefinito da impostare nel file system e usare per tutte le scritture future.

Novità nella versione 12.9.0.

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

Tipo restituito

FileSystemClient

Esempio

Creazione di un file system nel servizio datalake.


   datalake_service_client.create_file_system("filesystem")

delete_file_system

Contrassegna il file system specificato per l'eliminazione.

Il file system e tutti i file contenuti all'interno vengono eliminati in seguito durante la Garbage Collection. Se il file system non viene trovato, verrà generato un oggetto ResourceNotFoundError.

delete_file_system(file_system: FileSystemProperties | str, **kwargs) -> FileSystemClient

Parametri

file_system
str oppure FileSystemProperties
Necessario

File system da eliminare. Questo può essere il nome del file system o un'istanza di FileSystemProperties.

lease
DataLakeLeaseClient oppure str

Se specificato, delete_file_system ha esito positivo solo se il lease del file system è attivo e corrisponde a questo ID. Obbligatorio se il file system ha un lease attivo.

if_modified_since
datetime

Valore DateTime. Azure prevede che il valore di data passato sia UTC. Se il fuso orario è incluso, le datetime non UTC verranno convertite in formato UTC. Se una data viene passata senza informazioni sul fuso orario, si presuppone che sia UTC. Specificare questa intestazione per eseguire l'operazione solo se la risorsa è stata modificata dopo l'ora specificata.

if_unmodified_since
datetime

Valore DateTime. Azure prevede che il valore di data passato sia UTC. Se il fuso orario è incluso, le datetime non UTC verranno convertite in formato UTC. Se una data viene passata senza informazioni sul fuso orario, si presuppone che sia UTC. Specificare questa intestazione per eseguire l'operazione solo se la risorsa non è stata modificata dopo l'ora e la data specificate.

etag
str

Valore ETag o il carattere jolly (*). Usato per verificare se la risorsa è cambiata e agire in base alla condizione specificata dal parametro match_condition .

match_condition
MatchConditions

Condizione di corrispondenza da utilizzare sul etag.

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

Tipo restituito

None

Esempio

Eliminazione di un file system nel servizio datalake.


   datalake_service_client.delete_file_system("filesystem")

from_connection_string

Creare DataLakeServiceClient da una stringa di connessione.

:return a DataLakeServiceClient :rtype ~azure.storage.filedatalake.DataLakeServiceClient

from_connection_string(conn_str: str, credential: str | Dict[str, str] | AzureNamedKeyCredential | AzureSasCredential | TokenCredential | None = None, **kwargs: Any) -> Self

Parametri

conn_str
str
Necessario

Stringa di connessione a un account di archiviazione di Azure.

credential
valore predefinito: None

Credenziali con cui eseguire l'autenticazione. Questo è facoltativo se l'URL dell'account ha già un token di firma di accesso condiviso o la stringa di connessione ha già valori di chiave di accesso condiviso. Il valore può essere una stringa di token sas, un'istanza di AzureSasCredential da azure.core.credential, una chiave di accesso condiviso dell'account o un'istanza di una classe TokenCredentials da azure.identity. Le credenziali fornite qui avranno la precedenza su quelle nella stringa di connessione.

Esempio

Creazione di DataLakeServiceClient da una stringa di connessione.


   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

get_directory_client

Ottenere un client per interagire con la directory specificata.

La directory non esiste già.

get_directory_client(file_system: FileSystemProperties | str, directory: DirectoryProperties | str) -> DataLakeDirectoryClient

Parametri

file_system
str oppure FileSystemProperties
Necessario

File system in cui si trova la directory. Questo può essere il nome del file system o un'istanza di FileSystemProperties.

directory
str oppure DirectoryProperties
Necessario

Directory con cui interagire. Può essere il nome della directory o un'istanza di DirectoryProperties.

Restituisce

A DataLakeDirectoryClient.

Tipo restituito

DataLakeDirectoryClient

Esempio

Ottenere il client della directory per interagire con una directory specifica.


   directory_client = datalake_service_client.get_directory_client(file_system_client.file_system_name,
                                                                   "mydirectory")

get_file_client

Ottenere un client per interagire con il file specificato.

Il file non esiste già.

get_file_client(file_system: FileSystemProperties | str, file_path: FileProperties | str) -> DataLakeFileClient

Parametri

file_system
str oppure FileSystemProperties
Necessario

File system in cui si trova il file. Questo può essere il nome del file system o un'istanza di FileSystemProperties.

file_path
str oppure FileProperties
Necessario

File con cui interagire. Questo può essere il percorso completo del file(dalla directory radice) o un'istanza di FileProperties. Ad esempio. directory/sottodirectory/file

Restituisce

A DataLakeFileClient.

Tipo restituito

DataLakeFileClient

Esempio

Ottenere il client di file per interagire con un file specifico.


   file_client = datalake_service_client.get_file_client(file_system_client.file_system_name, "myfile")

get_file_system_client

Ottenere un client per interagire con il file system specificato.

Il file system non esiste già.

get_file_system_client(file_system: FileSystemProperties | str) -> FileSystemClient

Parametri

file_system
str oppure FileSystemProperties
Necessario

File system. Questo può essere il nome del file system o un'istanza di FileSystemProperties.

Restituisce

A FileSystemClient.

Tipo restituito

FileSystemClient

Esempio

Ottenere il client del file system per interagire con un file system specifico.


   # Instantiate a DataLakeServiceClient using a connection string
   from azure.storage.filedatalake import DataLakeServiceClient
   datalake_service_client = DataLakeServiceClient.from_connection_string(self.connection_string)

   # Instantiate a FileSystemClient
   file_system_client = datalake_service_client.get_file_system_client("mynewfilesystem")

get_service_properties

Ottiene le proprietà del servizio datalake di un account di archiviazione, tra cui Azure Analisi archiviazione.

Novità nella versione 12.4.0: questa operazione è stata introdotta nella versione API '2020-06-12'.

get_service_properties(**kwargs: Any) -> Dict[str, Any]

Parametri

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

Restituisce

Oggetto contenente proprietà del servizio datalake, ad esempio registrazione analisi, metriche orarie/minuti, regole cors e così via.

Tipo restituito

Dict[str, Any]

get_user_delegation_key

Ottenere una chiave di delega utente allo scopo di firmare i token di firma di accesso condiviso. Una credenziale del token deve essere presente nell'oggetto del servizio per la riuscita della richiesta.

get_user_delegation_key(key_start_time: datetime, key_expiry_time: datetime, **kwargs: Any) -> UserDelegationKey

Parametri

key_start_time
datetime
Necessario

Valore DateTime. Indica quando la chiave diventa valida.

key_expiry_time
datetime
Necessario

Valore DateTime. Indica quando la chiave smette di essere valida.

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

Restituisce

Chiave di delega utente.

Tipo restituito

UserDelegationKey

Esempio

Ottenere la chiave di delega utente dal client del servizio datalake.


   from datetime import datetime, timedelta
   user_delegation_key = datalake_service_client.get_user_delegation_key(datetime.utcnow(),
                                                                         datetime.utcnow() + timedelta(hours=1))

list_file_systems

Restituisce un generatore per elencare i file system nell'account specificato.

Il generatore seguirà i token di continuazione restituiti dal servizio e arresterà quando tutti i file system sono stati restituiti.

list_file_systems(name_starts_with: str | None = None, include_metadata: bool | None = None, **kwargs) -> ItemPaged[FileSystemProperties]

Parametri

name_starts_with
str
Necessario

Filtra i risultati per restituire solo file system i cui nomi iniziano con il prefisso specificato.

include_metadata
bool
Necessario

Specifica che i metadati del file system vengono restituiti nella risposta. Il valore predefinito è False.

results_per_page
int

Numero massimo di nomi del file system da recuperare per chiamata API. Se la richiesta non specifica il server restituirà fino a 5.000 elementi per pagina.

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

include_deleted
bool

Specifica che i file system eliminati devono essere restituiti nella risposta. Si tratta di un account abilitato per il ripristino del file system. Il valore predefinito è False. .. versionadded:: 12.3.0

include_system
bool

Flag che specifica che i file system devono essere inclusi. .. versionadded:: 12.6.0

Restituisce

Iterabile (paging automatico) di FileSystemProperties.

Tipo restituito

ItemPaged[FileSystemProperties]

Esempio

Elencare i file system nel servizio datalake.


   file_systems = datalake_service_client.list_file_systems()
   for file_system in file_systems:
       print(file_system.name)

set_service_properties

Imposta le proprietà del servizio Datalake di un account di archiviazione, tra cui Azure Analisi archiviazione.

Novità nella versione 12.4.0: questa operazione è stata introdotta nella versione API '2020-06-12'.

Se un elemento (ad esempio, analytics_logging) viene lasciato come Nessuno, le impostazioni esistenti nel servizio per tale funzionalità vengono mantenute.

set_service_properties(**kwargs: Any) -> None

Parametri

analytics_logging

Raggruppa le impostazioni di registrazione di Azure Analytics.

hour_metrics

Le impostazioni delle metriche orarie forniscono un riepilogo delle statistiche richieste raggruppate dall'API in aggregazioni orarie.

minute_metrics

Le impostazioni delle metriche minuti forniscono le statistiche delle richieste per ogni minuto.

cors

È possibile includere fino a cinque elementi CorsRule nell'elenco. Se viene specificato un elenco vuoto, tutte le regole CORS verranno eliminate e CORS verrà disabilitata per il servizio.

target_version
str

Indica la versione predefinita da usare per le richieste se non è specificata la versione di una richiesta in ingresso.

delete_retention_policy

Il criterio di conservazione elimina specifica se conservare file/directory eliminati. Specifica anche il numero di giorni e versioni di file/directory da mantenere.

static_website

Specifica se la funzionalità del sito Web statico è abilitata e, se sì, indica il documento di errore di indice e 404 da usare.

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

Tipo restituito

None

undelete_file_system

Ripristina il file system eliminato temporanea.

L'operazione avrà esito positivo solo se viene usato entro il numero di giorni specificato impostato nei criteri di conservazione di eliminazione.

Novità nella versione 12.3.0: questa operazione è stata introdotta nella versione API '2019-12-12'.

undelete_file_system(name: str, deleted_version: str, **kwargs: Any) -> FileSystemClient

Parametri

name
str
Necessario

Specifica il nome del file system eliminato da ripristinare.

deleted_version
str
Necessario

Specifica la versione del file system eliminato da ripristinare.

timeout
int

Imposta il timeout lato server per l'operazione in secondi. Per informazioni dettagliate, vedere https://learn.microsoft.com/rest/api/storageservices/setting-timeouts-for-blob-service-operations. Questo valore non viene monitorato o convalidato nel client. Per configurare i timeout di rete lato client, vedere qui.

Restituisce

FileSystemClient ripristinato eliminato.

Tipo restituito

FileSystemClient

Attributi

api_version

Versione dell'API di archiviazione usata per le richieste.

location_mode

Modalità percorso attualmente usata dal client.

Per impostazione predefinita, questo sarà "primario". Le opzioni includono "primary" e "secondary".

primary_endpoint

URL dell'endpoint primario completo.

primary_hostname

Nome host dell'endpoint primario.

secondary_endpoint

URL dell'endpoint secondario completo se configurato.

Se non è disponibile, verrà generato un valore ValueError. Per specificare in modo esplicito un nome host secondario, usare l'argomento della parola chiave facoltativo secondary_hostname nell'istanza.

Eccezioni

ValueError

secondary_hostname

Nome host dell'endpoint secondario.

Se non è disponibile, questo sarà Nessuno. Per specificare in modo esplicito un nome host secondario, usare l'argomento della parola chiave facoltativo secondary_hostname nell'istanza.

url

URL completo dell'endpoint per questa entità, incluso il token di firma di accesso condiviso se usato.

Questo potrebbe essere l'endpoint primario o l'endpoint secondario a seconda dell'oggetto corrente location_mode. :restituisce: URL completo dell'endpoint per questa entità, incluso il token di firma di accesso condiviso se usato. :rtype: str