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

A equipe do Azure Synapse Studio criou duas novas APIs de montagem/desmontagem no pacote Microsoft Spark Utilities (mssparkutils). Você pode usar essas APIs para anexar armazenamento remoto (Armazenamento de Blob do Azure ou Azure Data Lake Storage Gen2) a todos os nós de trabalho (nó de driver e nós de trabalho). 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 obter mais informações, consulte Introdução aos utilitários Microsoft Spark.

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

• Como montar o Data Lake Storage Gen2 ou Blob Storage.
• 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 mssparktuils fs API.
• Como acessar arquivos sob o ponto de montagem usando a API de leitura do Spark.
• Como desmontar o ponto de montagem.

Aviso

A montagem de compartilhamento de arquivos do Azure está temporariamente desabilitada. Em vez disso, você pode usar a montagem do Data Lake Storage Gen2 ou do Armazenamento de Blob do Azure, conforme descrito na próxima seção.

O armazenamento do Azure Data Lake Storage Gen1 não é suportado. Você pode migrar para o Data Lake Storage Gen2 seguindo as diretrizes de migração do Azure Data Lake Storage Gen1 para Gen2 antes de usar as APIs de montagem.

Armazenamento de montagem

Esta seção ilustra como montar o Data Lake Storage Gen2 passo a passo como exemplo. A montagem do armazenamento de Blob funciona de forma semelhante.

O exemplo pressupõe que você tenha uma conta do 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, o Azure Synapse Analytics dá suporte a três métodos de autenticação para a operação de montagem de gatilho: linkedService, accountKeye 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.

Você pode criar um serviço vinculado para o Data Lake Storage Gen2 ou Blob Storage. Atualmente, o Azure Synapse Analytics dá suporte a dois métodos de autenticação quando você cria um serviço vinculado:

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

  

• Criar um serviço vinculado usando uma identidade gerenciada

  

Importante

• Se o Serviço Vinculado ao Azure Data Lake Storage Gen2 criado acima usar um ponto de extremidade privado gerenciado (com um URI dfs), precisaremos criar outro ponto de extremidade privado gerenciado secundário usando a opção Armazenamento de Blob do Azure (com um URI de blob) para garantir que o código fsspec/adlfs interno possa se conectar usando a interface BlobServiceClient.
• Caso o ponto de extremidade privado gerenciado secundário não esteja configurado corretamente, veremos uma mensagem de erro como ServiceRequestError: Não é possível se conectar ao host [storageaccountname].blob.core.windows.net:443 ssl:True [Nome ou serviço desconhecido]

Nota

Se você criar um serviço vinculado usando uma identidade gerenciada como método de autenticação, verifique se o arquivo MSI do espaço de trabalho tem a função de Colaborador de Dados de Blob de Armazenamento do contêiner montado.

Depois de criar o serviço vinculado com êxito, você pode facilmente montar o contêiner no pool do Spark usando o seguinte código Python:

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

Nota

Talvez seja necessário importar mssparkutils se não estiver disponível:

from notebookutils import mssparkutils 

Não recomendamos que você monte uma pasta raiz, independentemente do método de autenticação usado.

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 motivos de segurança, recomendamos que você armazene chaves de conta ou tokens SAS no Cofre de Chaves do Azure (como mostra a captura de tela de exemplo a seguir). Em seguida, você pode recuperá-los usando a mssparkutil.credentials.getSecret API. Para obter mais informações, consulte Gerenciar chaves de conta de armazenamento com o Cofre de Chaves e a CLI do Azure (legado).

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}
) 

Nota

Por motivos de segurança, não armazene credenciais no código.

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.

Supondo que você tenha montado o contêiner do Data Lake Storage Gen2 mycontainer em /test usando a API de montagem. 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")

Nota

Quando você monta o armazenamento com workspace escopo, o ponto de montagem é criado sob a /synfs/workspace pasta. E você precisa usar mssparkutils.fs.getMountPath("/test", "workspace") para obter o caminho preciso.

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.

Ler um arquivo de uma conta de armazenamento montada do Data Lake Storage Gen2

O exemplo a seguir pressupõe que uma conta de armazenamento do Data Lake Storage Gen2 já estava montada e, em seguida, você lê o arquivo usando um caminho de montagem:

%%pyspark 

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

Nota

Ao montar o armazenamento usando um serviço vinculado, você sempre deve definir explicitamente a configuração do serviço vinculado spark antes de usar o esquema synfs para acessar os dados. Consulte o armazenamento ADLS Gen2 com serviços vinculados para obter detalhes.

Ler um arquivo de uma conta de armazenamento de Blob montada

Se você montou uma conta de Armazenamento de Blob e deseja acessá-la usando mssparkutils ou a API do Spark, precisará configurar explicitamente o token SAS por meio da configuração do Spark antes de tentar montar o contêiner usando a API de montagem:

1. Para acessar uma conta de Armazenamento de Blob usando mssparkutils ou a API do Spark após uma montagem de gatilho, atualize a configuração do Spark conforme mostrado no exemplo de código a seguir. 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 myblobstorageaccountvinculado e monte a conta de Armazenamento de Blob usando o serviço vinculado:

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

3. Monte o contêiner de Armazenamento de Blob e leia o arquivo usando um caminho de montagem por meio da API do arquivo local:

       # 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 contêiner de armazenamento de Blob montado por meio 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.

• Por enquanto, não há suporte para a montagem de uma conta de armazenamento do Data Lake Storage Gen1.

Próximos passos

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