Introdução às APIs de montagem/desmontagem de ficheiros no Azure Synapse Analytics

A equipa do Azure Synapse Studio construiu duas novas APIs de montagem/desmontagem no pacote Microsoft Spark Utilities (mssparkutils). Pode usar estas APIs para anexar armazenamento remoto (Armazenamento de Blobs do Azure, Azure Data Lake Storage Gen2 ou Azure File Share) a todos os nós em funcionamento (nó driver e nós trabalhadores). Depois que o armazenamento estiver instalado, você poderá usar a API de arquivo local para acessar dados como se estivessem armazenados no sistema de arquivos local. Para mais informações, consulte Introdução à Microsoft Spark Utilities.

O artigo mostra como usar APIs de montagem/desmontagem em seu espaço de trabalho. Irá aprender:

• Como montar Data Lake Storage Gen2, Armazenamento de Blobs ou Azure File Share.
• Como acessar arquivos sob o ponto de montagem através da API do sistema de arquivos local.
• Como acessar arquivos sob o ponto de montagem usando a mssparkutils fs API.
• Como acessar arquivos sob o ponto de montagem usando a API de leitura do Spark.
• Como desmontar o ponto de montagem.

Armazenamento de montagem

Esta secção ilustra como montar o Data Lake Storage Gen2 passo a passo, como exemplo. Montar Armazenamento de Blobs e Azure File Share funciona de forma semelhante.

O exemplo assume que tens uma conta Data Lake Storage Gen2 chamada storegen2. A conta tem um contêiner chamado mycontainer que você deseja montar /test no pool do Spark.

Para montar o contêiner chamado mycontainer, mssparkutils primeiro precisa verificar se você tem permissão para acessar o contêiner. Atualmente, Azure Synapse Analytics suporta três métodos de autenticação para a operação de montagem do gatilho: linkedService, accountKey e sastoken.

Montar usando um serviço vinculado (recomendado)

Recomendamos uma montagem de gatilho via serviço vinculado. Esse método evita vazamentos de segurança, porque mssparkutils não armazena nenhum segredo ou valores de autenticação em si. Em vez disso, mssparkutils sempre busca valores de autenticação do serviço vinculado para solicitar dados de blob do armazenamento remoto.

Pode criar um serviço ligado para Data Lake Storage Gen2 ou Armazenamento de Blobs. Atualmente, o Azure Synapse Analytics suporta dois métodos de autenticação quando cria um serviço ligado:

• Criar um serviço vinculado usando uma chave de conta

  

• Criar um serviço vinculado usando uma identidade gerenciada atribuída ao sistema

  

Depois de criar um serviço ligado com sucesso, pode facilmente montar o contentor no seu pool Spark usando o seguinte código Python:

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

from notebookutils import mssparkutils 

Parâmetros de montagem:

• fileCacheTimeout: Os blobs serão armazenados em cache na pasta temporária local por 120 segundos por padrão. Durante esse tempo, o blobfuse não verificará se o arquivo está atualizado ou não. O parâmetro pode ser definido para alterar o tempo limite padrão. Quando vários clientes modificam arquivos ao mesmo tempo, a fim de evitar inconsistências entre arquivos locais e remotos, recomendamos encurtar o tempo de cache, ou até mesmo alterá-lo para 0, e sempre obter os arquivos mais recentes do servidor.
• Tempo limite: O tempo limite da operação de montagem é de 120 segundos por padrão. O parâmetro pode ser definido para alterar o tempo limite padrão. Quando há muitos executores ou quando a montagem expira, recomendamos aumentar o valor.
• scope: O parâmetro scope é usado para especificar o escopo da montagem. O valor padrão é "job". Se o escopo estiver definido como "trabalho", a montagem será visível apenas para o cluster atual. Se o escopo estiver definido como "espaço de trabalho", a montagem ficará visível para todos os blocos de anotações no espaço de trabalho atual e o ponto de montagem será criado automaticamente se não existir. Adicione os mesmos parâmetros à API de desmontagem para desmontar o ponto de montagem. A montagem no nível do espaço de trabalho só é suportada para autenticação de serviço vinculado.

Você pode usar estes parâmetros assim:

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

Montagem via token de assinatura de acesso compartilhado ou chave de conta

Além de montar através de um serviço vinculado, mssparkutils suporta a passagem explícita de uma chave de conta ou token de assinatura de acesso compartilhado (SAS) como um parâmetro para montar o destino.

Por razões de segurança, recomendamos o uso de identidades geridas e autenticação Microsoft Entra em vez de chaves de conta ou tokens SAS, sempre que possível. Se tiver de usar chaves de conta, guarde-as no Azure Key Vault (como mostra o exemplo seguinte de captura). Em seguida, você pode recuperá-los usando a mssparkutil.credentials.getSecret API. Para mais informações, consulte Autorizar o acesso a dados em Armazenamento do Azure.

Aqui está o código de exemplo:

from notebookutils import mssparkutils  

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

Acessar arquivos sob o ponto de montagem usando a API mssparkutils fs

O principal objetivo da operação de montagem é permitir que os clientes acessem os dados armazenados em uma conta de armazenamento remoto usando uma API de sistema de arquivos local. Você também pode acessar os dados usando a mssparkutils fs API com um caminho montado como parâmetro. O formato de caminho usado aqui é um pouco diferente.

Assumindo que montaste o container mycontainer do Data Lake Storage Gen2 em /test usando a API mount. Ao acessar os dados por meio de uma API de sistema de arquivos local:

• Para versões do Spark menores ou iguais a 3.3, o formato de caminho é /synfs/{jobId}/test/{filename}.
• Para versões do Spark maiores ou iguais a 3.4, o formato de caminho é /synfs/notebook/{jobId}/test/{filename}.

Recomendamos o uso de a mssparkutils.fs.getMountPath() para obter o caminho preciso:

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

Quando você deseja acessar os dados usando a mssparkutils fs API, o formato do caminho é assim: synfs:/notebook/{jobId}/test/{filename}. Você pode ver que synfs é usado como o esquema neste caso, em vez de uma parte do caminho montado. Claro, você também pode usar o esquema do sistema de arquivos local para acessar os dados. Por exemplo, file:/synfs/notebook/{jobId}/test/{filename}.

Os três exemplos a seguir mostram como acessar um arquivo com um caminho de ponto de montagem usando mssparkutils fso .

• Listar diretórios:

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

• Leia o conteúdo do arquivo:

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

• Crie um diretório:

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

Acessar arquivos sob o ponto de montagem usando a API de leitura do Spark

Você pode fornecer um parâmetro para acessar os dados por meio da API de leitura do Spark. O formato de caminho aqui é o mesmo quando você usa a mssparkutils fs API.

Leia um ficheiro a partir de uma conta de armazenamento Data Lake Storage Gen2 montada

O exemplo seguinte assume que uma conta de armazenamento Data Lake Storage Gen2 já estava montada, e depois lê o ficheiro usando um caminho de montagem:

%%pyspark 

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

Leia um ficheiro a partir de uma conta Armazenamento de Blobs montada

Se criou uma conta Armazenamento de Blobs e quiser aceder a ela usando mssparkutils ou a API Spark, precisa de configurar explicitamente o token SAS via configuração Spark antes de tentar montar o contentor usando a API mount:

1. Para aceder a uma conta Armazenamento de Blobs usando mssparkutils ou a API do Spark após uma montagem de trigger, atualize a configuração do Spark conforme mostrado no seguinte exemplo de código. Você pode ignorar esta etapa se quiser acessar a configuração do Spark somente usando a API de arquivo local após a montagem.

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

2. Crie o serviço ligado myblobstorageaccount e monte a conta Armazenamento de Blobs usando o serviço ligado:

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

3. Monta o contentor Armazenamento de Blobs e depois lê o ficheiro usando um caminho de montagem através da API local do ficheiro:

       # 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. Leia os dados do contentor Armazenamento de Blobs montado através da API de leitura do 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()
   

Desmonte o ponto de montagem

Use o código a seguir para desmontar o ponto de montagem (/test neste exemplo):

mssparkutils.fs.unmount("/test") 

Limitações conhecidas

• O mecanismo de desmontagem não é automático. Quando a execução do aplicativo terminar, para desmontar o ponto de montagem para liberar espaço em disco, você precisará chamar explicitamente uma API de desmontagem em seu código. Caso contrário, o ponto de montagem ainda existirá no nó após a conclusão da execução do aplicativo.

• A montagem de uma conta de armazenamento Data Lake Storage Gen1 não é suportada para já.

Próximos passos

• Comece com Azure Synapse Analytics
• Monitore seu espaço de trabalho Synapse
• Introdução à Microsoft Spark Utilities