Wprowadzenie do interfejsów API instalacji/odinstalowywanie plików w Azure Synapse Analytics

Zespół platformy Azure Synapse Studio utworzył dwa nowe interfejsy API instalacji/odinstalowania w pakiecie Microsoft Spark Utilities (mssparkutils). Tych interfejsów API można używać do dołączania magazynu zdalnego (Azure Blob Storage, Azure Data Lake Storage Gen2 lub udziału plików Azure) do wszystkich węzłów roboczych (węzłów sterownika i węzłów roboczych). Po zainstalowaniu magazynu można użyć lokalnego interfejsu API plików, aby uzyskać dostęp do danych tak, jakby był przechowywany w lokalnym systemie plików. Aby uzyskać więcej informacji, zobacz Introduction to Microsoft Spark Utilities.

W tym artykule pokazano, jak używać interfejsów API instalacji/odinstalowania w obszarze roboczym. Dowiesz się:

• Jak zainstalować udział plików Data Lake Storage Gen2, Blob Storage lub Azure.
• Jak uzyskać dostęp do plików w punkcie instalacji za pośrednictwem lokalnego interfejsu API systemu plików.
• Jak uzyskać dostęp do plików w punkcie instalacji przy użyciu interfejsu mssparkutils fs API.
• Jak uzyskać dostęp do plików w punkcie instalacji przy użyciu interfejsu API odczytu platformy Spark.
• Jak odinstalować punkt instalacji.

Instalowanie magazynu

W tej sekcji pokazano, jak zainstalować Data Lake Storage Gen2 krok po kroku jako przykład. Instalowanie Blob Storage i udziału plików Azure działa podobnie.

W przykładzie przyjęto założenie, że masz jedno konto Data Lake Storage Gen2 o nazwie storegen2. Konto ma jeden kontener o nazwie mycontainer , do którego chcesz zainstalować aplikację /test w puli platformy Spark.

Aby zainstalować kontener o nazwie mycontainer, najpierw należy sprawdzić, mssparkutils czy masz uprawnienia dostępu do kontenera. Obecnie Azure Synapse Analytics obsługuje trzy metody uwierzytelniania dla operacji instalacji wyzwalacza: linkedService, accountKey i sastoken.

Instalowanie przy użyciu połączonej usługi (zalecane)

Zalecamy instalację wyzwalacza za pośrednictwem połączonej usługi. Ta metoda pozwala uniknąć wycieków zabezpieczeń, ponieważ mssparkutils nie przechowuje żadnych wartości wpisów tajnych ani uwierzytelniania. mssparkutils Zamiast tego zawsze pobiera wartości uwierzytelniania z połączonej usługi w celu żądania danych obiektów blob z magazynu zdalnego.

Możesz utworzyć połączoną usługę dla Data Lake Storage Gen2 lub Blob Storage. Obecnie Azure Synapse Analytics obsługuje dwie metody uwierzytelniania podczas tworzenia połączonej usługi:

• Tworzenie połączonej usługi przy użyciu klucza konta

  

• Tworzenie połączonej usługi przy użyciu tożsamości zarządzanej przypisanej przez system

  

Po pomyślnym utworzeniu połączonej usługi można łatwo zainstalować kontener w puli Spark przy użyciu następującego kodu Python:

mssparkutils.fs.mount( 
    "abfss://mycontainer@<accountname>.dfs.core.windows.net", 
    "/test", 
    {"linkedService": "mygen2account"} 
) 

from notebookutils import mssparkutils 

Parametry instalacji:

• fileCacheTimeout: obiekty blob będą domyślnie buforowane w lokalnym folderze tymczasowym przez 120 sekund. W tym czasie program blobfuse nie sprawdzi, czy plik jest aktualny, czy nie. Parametr można ustawić tak, aby zmienić domyślny limit czasu. Gdy wielu klientów modyfikuje pliki jednocześnie, aby uniknąć niespójności między plikami lokalnymi i zdalnymi, zalecamy skrócenie czasu pamięci podręcznej, a nawet zmianę jej na 0 i zawsze pobieranie najnowszych plików z serwera.
• limit czasu: limit czasu operacji instalacji wynosi domyślnie 120 sekund. Parametr można ustawić tak, aby zmienić domyślny limit czasu. W przypadku zbyt wielu funkcji wykonawczych lub limitu czasu instalacji zalecamy zwiększenie wartości.
• zakres: parametr zakresu służy do określania zakresu instalacji. Wartość domyślna to "job". Jeśli zakres jest ustawiony na "zadanie", instalacja jest widoczna tylko dla bieżącego klastra. Jeśli zakres jest ustawiony na "obszar roboczy", instalacja jest widoczna dla wszystkich notesów w bieżącym obszarze roboczym, a punkt instalacji zostanie utworzony automatycznie, jeśli nie istnieje. Dodaj te same parametry do interfejsu API odinstalowania, aby odinstalować punkt instalacji. Instalacja na poziomie obszaru roboczego jest obsługiwana tylko w przypadku uwierzytelniania połączonej usługi.

Możesz użyć tych parametrów w następujący sposób:

mssparkutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)

Instalowanie za pomocą tokenu sygnatury dostępu współdzielonego lub klucza konta

Oprócz instalowania za pośrednictwem połączonej usługi program mssparkutils obsługuje jawne przekazywanie klucza konta lub tokenu sygnatury dostępu współdzielonego (SAS) jako parametru w celu zainstalowania obiektu docelowego.

Ze względów bezpieczeństwa zalecamy używanie tożsamości zarządzanych i Microsoft Entra uwierzytelniania zamiast kluczy kont lub tokenów SAS, jeśli to możliwe. Jeśli musisz użyć kluczy konta, zapisz je w Azure Key Vault (jak pokazano na poniższym przykładowym zrzucie ekranu). Następnie możesz je pobrać przy użyciu interfejsu mssparkutil.credentials.getSecret API. Aby uzyskać więcej informacji, zobacz Authorize access to data in Azure Storage (Dostęp do danych w Azure Storage.

Oto przykładowy kod:

from notebookutils import mssparkutils  

accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")  
mssparkutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
) 

Uzyskiwanie dostępu do plików w punkcie instalacji przy użyciu interfejsu API mssparkutils fs

Głównym celem operacji instalacji jest umożliwianie klientom dostępu do danych przechowywanych na koncie magazynu zdalnego przy użyciu lokalnego interfejsu API systemu plików. Dostęp do danych można również uzyskać przy użyciu interfejsu mssparkutils fs API z instalowaną ścieżką jako parametrem. Format ścieżki używany w tym miejscu jest nieco inny.

Zakładając, że masz zainstalowany kontener Data Lake Storage Gen2 mycontainer do /test przy użyciu interfejsu API instalacji. Podczas uzyskiwania dostępu do danych za pośrednictwem lokalnego interfejsu API systemu plików:

• W przypadku wersji platformy Spark mniejszej lub równej 3.3 format ścieżki to /synfs/{jobId}/test/{filename}.
• W przypadku wersji platformy Spark większej lub równej 3.4 format ścieżki to /synfs/notebook/{jobId}/test/{filename}.

Zalecamy użycie elementu , mssparkutils.fs.getMountPath() aby uzyskać dokładną ścieżkę:

path = mssparkutils.fs.getMountPath("/test")

Jeśli chcesz uzyskać dostęp do danych przy użyciu interfejsu mssparkutils fs API, format ścieżki wygląda następująco: synfs:/notebook/{jobId}/test/{filename}. Można zobaczyć, że synfs jest używany jako schemat w tym przypadku, zamiast części zainstalowanej ścieżki. Oczywiście można również użyć lokalnego schematu systemu plików, aby uzyskać dostęp do danych. Na przykład file:/synfs/notebook/{jobId}/test/{filename}.

W poniższych trzech przykładach pokazano, jak uzyskać dostęp do pliku ze ścieżką punktu instalacji przy użyciu polecenia mssparkutils fs.

• Katalogi listy:

  mssparkutils.fs.ls(f'file:{mssparkutils.fs.getMountPath("/test")}') 
  

• Odczytywanie zawartości pliku:

  mssparkutils.fs.head(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv') 
  

• Utwórz katalog:

  mssparkutils.fs.mkdirs(f'file:{mssparkutils.fs.getMountPath("/test")}/myDir') 
  

Uzyskiwanie dostępu do plików w punkcie instalacji przy użyciu interfejsu API odczytu platformy Spark

Możesz podać parametr, aby uzyskać dostęp do danych za pośrednictwem interfejsu API odczytu platformy Spark. Format ścieżki jest taki sam, gdy używasz interfejsu mssparkutils fs API.

Odczytywanie pliku z zainstalowanego konta magazynu Data Lake Storage Gen2

W poniższym przykładzie przyjęto założenie, że konto magazynu Data Lake Storage Gen2 zostało już zainstalowane, a następnie odczytasz plik przy użyciu ścieżki instalacji:

%%pyspark 

df = spark.read.load(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv', format='csv') 
df.show() 

Odczytywanie pliku z zainstalowanego konta Blob Storage

Jeśli masz zainstalowane konto Blob Storage i chcesz uzyskać do niego dostęp przy użyciu mssparkutils lub interfejsu API platformy Spark, musisz jawnie skonfigurować token SAS za pomocą konfiguracji platformy Spark przed podjęciem próby zainstalowania kontenera przy użyciu interfejsu API instalacji:

1. Aby uzyskać dostęp do konta Blob Storage przy użyciu mssparkutils lub interfejsu API platformy Spark po zainstalowaniu wyzwalacza, zaktualizuj konfigurację platformy Spark, jak pokazano w poniższym przykładzie kodu. Ten krok można pominąć, jeśli chcesz uzyskać dostęp do konfiguracji platformy Spark tylko przy użyciu lokalnego interfejsu API plików po zainstalowaniu.

   blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") 
   
   spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token) 
   

2. Utwórz połączoną usługę myblobstorageaccount i zainstaluj konto Blob Storage przy użyciu połączonej usługi:

   %%spark 
   mssparkutils.fs.mount( 
       "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", 
       "/test", 
       Map("linkedService" -> "myblobstorageaccount") 
   ) 
   

3. Zainstaluj kontener Blob Storage, a następnie odczytaj plik przy użyciu ścieżki instalacji za pośrednictwem lokalnego interfejsu API pliku:

       # mount the Blob Storage container, and then read the file by using a mount path
       with open(mssparkutils.fs.getMountPath("/test") + "/myFile.txt") as f:
       print(f.read())
   

4. Odczytywanie danych z zainstalowanego kontenera Blob Storage za pośrednictwem interfejsu API odczytu platformy Spark:

   %%spark
   // mount blob storage container and then read file using mount path
   val df = spark.read.text(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.txt')
   df.show()
   

Odinstalowywanie punktu instalacji

Użyj następującego kodu, aby odinstalować punkt instalacji (/test w tym przykładzie):

mssparkutils.fs.unmount("/test") 

Znane ograniczenia

• Mechanizm odinstalowania nie jest automatyczny. Po zakończeniu działania aplikacji, aby odinstalować punkt instalacji, aby zwolnić miejsce na dysku, musisz jawnie wywołać odinstalowywanie interfejsu API w kodzie. W przeciwnym razie punkt instalacji nadal będzie istnieć w węźle po zakończeniu działania aplikacji.

• Instalowanie konta magazynu Data Lake Storage Gen1 nie jest obecnie obsługiwane.

Następne kroki

• Get rozpoczął pracę z Azure Synapse Analytics
• Monitorowanie obszaru roboczego usługi Synapse
• Introduction Microsoft Spark Utilities