Azure Synapse Analytics'te dosya bağlama/kaldırma API'lerine giriş
Azure Synapse Studio ekibi, Microsoft Spark Yardımcı Programları (mssparkutils
) paketinde iki yeni bağlama/çıkarma API'sini oluşturmştu. Bu API'leri, tüm çalışan düğümlere (sürücü düğümü ve çalışan düğümleri) uzak depolama (Azure Blob Depolama veya Azure Data Lake Storage 2. Nesil) eklemek için kullanabilirsiniz. Depolama gerçekleştikten sonra yerel dosya API'sini kullanarak verilere yerel dosya sisteminde depolanmış gibi erişebilirsiniz. Daha fazla bilgi için bkz . Microsoft Spark Yardımcı Programlarına Giriş.
Makale, çalışma alanınızda bağlama/çıkarma API'lerini nasıl kullanacağınızı gösterir. Şunları öğreneceksiniz:
- Data Lake Storage 2. Nesil veya Blob Depolama bağlama.
- Yerel dosya sistemi API'sini kullanarak bağlama noktası altındaki dosyalara erişme.
- API kullanarak bağlama noktası altındaki dosyalara
mssparktuils fs
erişme. - Spark okuma API'sini kullanarak bağlama noktası altındaki dosyalara erişme.
- Bağlama noktasını çıkarma.
Uyarı
Azure dosya paylaşımı bağlaması geçici olarak devre dışı bırakıldı. Sonraki bölümde açıklandığı gibi bunun yerine Data Lake Storage 2. Nesil veya Azure Blob Depolama bağlamayı kullanabilirsiniz.
Azure Data Lake Storage 1. Nesil depolama desteklenmez. Bağlama API'lerini kullanmadan önce Azure Data Lake Storage 1. Nesil 2. Nesil geçiş kılavuzunu izleyerek Data Lake Storage 2. Nesil geçirebilirsiniz.
Depolamayı bağlama
Bu bölümde örnek olarak adım adım Data Lake Storage 2. Nesil bağlama işlemi gösterilmektedir. Blob Depolama bağlama işlemi benzer şekilde çalışır.
Örnekte adlı storegen2
bir Data Lake Storage 2. Nesil hesabınız olduğu varsayılır. Hesabın Spark havuzunuzda bağlamak /test
istediğiniz adlı mycontainer
bir kapsayıcısı vardır.
adlı mycontainer
mssparkutils
kapsayıcıyı bağlamak için öncelikle kapsayıcıya erişim izniniz olup olmadığını denetlemeniz gerekir. Şu anda Azure Synapse Analytics tetikleyici bağlama işlemi için üç kimlik doğrulama yöntemini destekler: linkedService
, accountKey
ve sastoken
.
Bağlı hizmet kullanarak bağlama (önerilir)
Bağlı hizmet aracılığıyla bir tetikleyici bağlaması öneririz. Gizli dizi veya kimlik doğrulama değerlerinin kendisini depolamadığından bu mssparkutils
yöntem güvenlik sızıntılarını önler. Bunun yerine, mssparkutils
uzak depolamadan blob verileri istemek için her zaman bağlı hizmetten kimlik doğrulama değerlerini getirir.
Data Lake Storage 2. Nesil veya Blob Depolama için bağlı bir hizmet oluşturabilirsiniz. Azure Synapse Analytics şu anda bağlı bir hizmet oluşturduğunuzda iki kimlik doğrulama yöntemini destekler:
Hesap anahtarı kullanarak bağlı hizmet oluşturma
Yönetilen kimlik kullanarak bağlı hizmet oluşturma
Önemli
- Azure Data Lake Storage 2. Nesil için yukarıda oluşturulan Bağlı Hizmet yönetilen özel uç nokta (dfs URI ile) kullanıyorsa, iç fsspec/adlfs kodunu Azure Blob Depolama nBlobServiceClient arabirimi.
- İkincil yönetilen özel uç noktanın doğru yapılandırılmaması durumunda ServiceRequestError: [storageaccountname].blob.core.windows.net:443 ssl:True [Ad veya hizmet bilinmiyor] konağına bağlanılamıyor gibi bir hata iletisi görürsünüz
Not
Kimlik doğrulama yöntemi olarak yönetilen kimlik kullanarak bağlı bir hizmet oluşturursanız, çalışma alanı MSI dosyasının bağlı kapsayıcının Depolama Blob Verileri Katkıda Bulunanı rolüne sahip olduğundan emin olun.
Bağlı hizmeti başarıyla oluşturduktan sonra aşağıdaki Python kodunu kullanarak kapsayıcıyı Spark havuzunuza kolayca bağlayabilirsiniz:
mssparkutils.fs.mount(
"abfss://mycontainer@<accountname>.dfs.core.windows.net",
"/test",
{"linkedService": "mygen2account"}
)
Not
Kullanılamıyorsa içeri aktarmanız mssparkutils
gerekebilir:
from notebookutils import mssparkutils
Hangi kimlik doğrulama yöntemini kullanırsanız kullanın kök klasör bağlamanızı önermeyiz.
Bağlama parametreleri:
- fileCacheTimeout: Bloblar varsayılan olarak 120 saniye boyunca yerel geçici klasörde önbelleğe alınır. Bu süre boyunca blobfuse dosyanın güncel olup olmadığını denetlemez. parametresi varsayılan zaman aşımı süresini değiştirecek şekilde ayarlanabilir. Birden çok istemci dosyaları aynı anda değiştirdiğinde, yerel ve uzak dosyalar arasındaki tutarsızlıkları önlemek için önbellek süresini kısaltmanızı, hatta 0 olarak değiştirmenizi ve her zaman sunucudan en son dosyaları almanızı öneririz.
- zaman aşımı: Bağlama işlemi zaman aşımı varsayılan olarak 120 saniyedir. parametresi varsayılan zaman aşımı süresini değiştirecek şekilde ayarlanabilir. Çok fazla yürütücü olduğunda veya bağlama zaman aşımına uğradıysa değeri artırmanızı öneririz.
- scope: Kapsam parametresi bağlamanın kapsamını belirtmek için kullanılır. Varsayılan değer "job" değeridir. Kapsam "iş" olarak ayarlanırsa bağlama yalnızca geçerli kümede görünür. Kapsam "çalışma alanı" olarak ayarlanırsa, bağlama geçerli çalışma alanında tüm not defterleri tarafından görülebilir ve bağlama noktası yoksa otomatik olarak oluşturulur. Bağlama noktasını sökmek için aynı parametreleri çıkarma API'sine ekleyin. Çalışma alanı düzeyi bağlama yalnızca bağlı hizmet kimlik doğrulaması için desteklenir.
Aşağıdaki gibi parametreleri kullanabilirsiniz:
mssparkutils.fs.mount(
"abfss://mycontainer@<accountname>.dfs.core.windows.net",
"/test",
{"linkedService":"mygen2account", "fileCacheTimeout": 120, "timeout": 120}
)
Paylaşılan erişim imzası belirteci veya hesap anahtarı aracılığıyla bağlama
Bağlı hizmet aracılığıyla bağlamaya ek olarak, mssparkutils
bir hesap anahtarının veya paylaşılan erişim imzası (SAS) belirtecinin hedefi bağlamak için parametre olarak açıkça geçirilmesini destekler.
Güvenlik nedeniyle, hesap anahtarlarını veya SAS belirteçlerini Azure Key Vault'ta depolamanızı öneririz (aşağıdaki örnek ekran görüntüsünde gösterildiği gibi). Daha sonra API'yi mssparkutil.credentials.getSecret
kullanarak bunları alabilirsiniz. Daha fazla bilgi için bkz . Key Vault ve Azure CLI (eski) ile depolama hesabı anahtarlarını yönetme.
Örnek kod şu şekildedir:
from notebookutils import mssparkutils
accountKey = mssparkutils.credentials.getSecret("MountKV","mySecret")
mssparkutils.fs.mount(
"abfss://mycontainer@<accountname>.dfs.core.windows.net",
"/test",
{"accountKey":accountKey}
)
Not
Güvenlik nedeniyle kimlik bilgilerini kodda depolamayın.
mssparkutils fs API'sini kullanarak bağlama noktası altındaki dosyalara erişme
Bağlama işleminin temel amacı, müşterilerin yerel bir dosya sistemi API'sini kullanarak uzak depolama hesabında depolanan verilere erişmesine izin vermektir. Ayrıca API'yi bağlı bir yol ile parametre olarak kullanarak mssparkutils fs
da verilere erişebilirsiniz. Burada kullanılan yol biçimi biraz farklıdır.
mycontainer Data Lake Storage 2. Nesil kapsayıcısını bağlama API'sini kullanarak /test'e bağladığınız varsayılır. Verilere yerel bir dosya sistemi API'si aracılığıyla erişirken:
- 3.3'ten küçük veya buna eşit Spark sürümleri için yol biçimi şeklindedir
/synfs/{jobId}/test/{filename}
. - 3.4'ten büyük veya buna eşit Spark sürümleri için yol biçimi şeklindedir
/synfs/notebook/{jobId}/test/{filename}
.
Doğru yolu elde etmek için bir mssparkutils.fs.getMountPath()
kullanmanızı öneririz:
path = mssparkutils.fs.getMountPath("/test")
Not
Depolamayı kapsamla workspace
bağladığınızda, bağlama noktası klasörün altında /synfs/workspace
oluşturulur. Ve doğru yolu bulmak için kullanmanız mssparkutils.fs.getMountPath("/test", "workspace")
gerekir.
API'yi kullanarak mssparkutils fs
verilere erişmek istediğinizde yol biçimi şöyledir: synfs:/notebook/{jobId}/test/{filename}
. Bu durumda, bağlı yolun bir parçası yerine şema olarak kullanıldığını görebilirsiniz synfs
. Elbette, verilere erişmek için yerel dosya sistemi şemasını da kullanabilirsiniz. Örneğin, file:/synfs/notebook/{jobId}/test/{filename}
.
Aşağıdaki üç örnek kullanarak mssparkutils fs
bağlama noktası yolu olan bir dosyaya nasıl erişeceğini gösterir.
Liste dizinleri:
mssparkutils.fs.ls(f'file:{mssparkutils.fs.getMountPath("/test")}')
Dosya içeriğini okuma:
mssparkutils.fs.head(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv')
Dizin oluşturma:
mssparkutils.fs.mkdirs(f'file:{mssparkutils.fs.getMountPath("/test")}/myDir')
Spark okuma API'sini kullanarak bağlama noktası altındaki dosyalara erişme
Spark okuma API'sini kullanarak verilere erişmek için bir parametre sağlayabilirsiniz. Buradaki yol biçimi, API'yi kullandığınızda mssparkutils fs
aynıdır.
Bağlı bir Data Lake Storage 2. Nesil depolama hesabından dosya okuma
Aşağıdaki örnekte, bir Data Lake Storage 2. Nesil depolama hesabının zaten bağlı olduğu varsayılır ve ardından bağlama yolunu kullanarak dosyayı okursunuz:
%%pyspark
df = spark.read.load(f'file:{mssparkutils.fs.getMountPath("/test")}/myFile.csv', format='csv')
df.show()
Not
Bağlı hizmeti kullanarak depolamayı bağladığınızda, verilere erişmek için synfs şemasını kullanmadan önce spark bağlı hizmet yapılandırmasını her zaman açıkça ayarlamanız gerekir. Ayrıntılar için bağlı hizmetler içeren ADLS 2. Nesil depolamaya bakın.
Bağlı blob Depolama hesabından dosya okuma
Bir Blob Depolama hesabı bağladıysanız ve bu hesaba veya Spark API'sini kullanarak mssparkutils
erişmek istiyorsanız, bağlama API'sini kullanarak kapsayıcıyı bağlamayı denemeden önce Spark yapılandırması aracılığıyla SAS belirtecini açıkça yapılandırmanız gerekir:
Tetikleyici bağlama sonrasında veya Spark API'sini kullanarak
mssparkutils
bir Blob Depolama hesabına erişmek için aşağıdaki kod örneğinde gösterildiği gibi Spark yapılandırmasını güncelleştirin. Spark yapılandırmasına yalnızca bağlandıktan sonra yerel dosya API'sini kullanarak erişmek istiyorsanız bu adımı atlayabilirsiniz.blob_sas_token = mssparkutils.credentials.getConnectionStringOrCreds("myblobstorageaccount") spark.conf.set('fs.azure.sas.mycontainer.<blobStorageAccountName>.blob.core.windows.net', blob_sas_token)
Bağlı hizmeti oluşturun ve bağlı hizmeti
myblobstorageaccount
kullanarak Blob Depolama hesabını bağlayın:%%spark mssparkutils.fs.mount( "wasbs://mycontainer@<blobStorageAccountName>.blob.core.windows.net", "/test", Map("linkedService" -> "myblobstorageaccount") )
Blob Depolama kapsayıcısını bağlayın ve ardından yerel dosya API'sinde bir bağlama yolu kullanarak dosyayı okuyun:
# 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())
Spark okuma API'sini aracılığıyla bağlı Blob Depolama kapsayıcısından verileri okuyun:
%%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()
Bağlama noktasını çıkarma
Bağlama noktanızı/test
(bu örnekte) sökmek için aşağıdaki kodu kullanın:
mssparkutils.fs.unmount("/test")
Bilinen sınırlamalar
Çıkarma mekanizması otomatik değildir. Uygulama çalıştırması tamamlandığında, disk alanını serbest bırakmak için bağlama noktasını çıkarabilmek için kodunuzda bir çıkarma API'sini açıkça çağırmanız gerekir. Aksi takdirde, uygulama çalıştırması tamamlandıktan sonra bağlama noktası düğümde bulunmaya devam eder.
Data Lake Storage 1. Nesil depolama hesabı bağlama işlemi şimdilik desteklenmiyor.
Bilinen sorunlar:
- Spark 3.4'te, aynı kümede paralel olarak çalışan birden çok etkin oturum olduğunda bağlama noktaları kullanılamayabilir. Bu sorundan kaçınmak için kapsamla
workspace
bağlayabilirsiniz.
Sonraki adımlar
Geri Bildirim
https://aka.ms/ContentUserFeedback.
Çok yakında: 2024 boyunca, içerik için geri bildirim mekanizması olarak GitHub Sorunları’nı kullanımdan kaldıracak ve yeni bir geri bildirim sistemiyle değiştireceğiz. Daha fazla bilgi için bkz.Gönderin ve geri bildirimi görüntüleyin