Azure Data Lake Storage 2. Nesil'den dizin verileri

Azure Data Lake Storage 2. Nesil dizin oluşturucu, Azure Data Lake Storage 2. Nesil (ADLS 2. Nesil) içeriğini bir Azure Yapay Zeka Arama dizinine aktarır. Dizin oluşturucuya girişler, tek bir kapsayıcıdaki bloblarınızdır. Çıktı, aranabilir içerik ve meta verilerin tek tek alanlarda depolandığı bir arama dizinidir.

Bu makale, ADLS 2. Nesil'den dizin oluşturmaya özgü bilgilerle dizin oluşturucu oluşturma işlemini tamamlar. Rest API'lerini kullanarak tüm dizin oluşturucular için ortak olan üç parçalı bir iş akışını gösterir: veri kaynağı oluşturma, dizin oluşturma, dizin oluşturucu oluşturma. Dizin Oluşturucu Oluştur isteğini gönderdiğinizde veri ayıklama gerçekleşir.

C# dilindeki bir kod örneği için bkz. GitHub'da Microsoft Entra Id kullanarak Veri Gölü 2. Nesil'i dizine alma.

Önkoşullar

• ADLS Gen2 etkinleştirilmiş hiyerarşik ad alanı. ADLS 2. Nesil, Azure Depolama aracılığıyla kullanılabilir. Depolama hesabı ayarlarken hiyerarşik ad alanını etkinleştirme, dosyaları dizin hiyerarşisi ve iç içe alt dizinler halinde düzenleme seçeneğiniz vardır. Hiyerarşik ad alanını etkinleştirerek ADLS 2. Nesil'i etkinleştirirsiniz.

• ADLS 2. Nesil için erişim katmanları sık erişimli, seyrek erişimli ve arşivli katmanlardır. Yalnızca sıcak ve soğuk, arama dizinleyicileri tarafından erişilebilir.

• Metin içeren bloblar. İkili verileriniz varsa görüntü analizi için yapay zeka zenginleştirmesi ekleyebilirsiniz. Blob içeriği, arama hizmeti katmanınız için dizin oluşturucu sınırlarını aşamaz.

  Kaynak dizinleme ve yapay zeka zenginleştirmesini ayrı işleme aşamaları olarak değerlendirin. Beceri veya dış hizmet, dizin oluşturucunun ayıklayabileceğiniz içerik miktarından daha düşük bir giriş sınırına sahip olabilir. Beceri kümesindeki her beceri için başvuru makalesini gözden geçirin.

• Azure Depolama'da okuma izinleri. "Tam erişim" bağlantı dizesi, içeriğe erişim sağlayan bir anahtar içerir, ancak bunun yerine Azure rolleri kullanıyorsanız , arama hizmeti yönetilen kimliğininDepolama Blob Veri Okuyucusu izinlerine sahip olduğundan emin olun.

• REST çağrılarını bu makalede gösterilene benzer şekilde formüle etmek için REST istemcisini kullanın.

Sınırlamalar

• Blob dizin oluşturucularından farklı olarak, ADLS 2. Nesil dizin oluşturucuları bir depolama hesabından içerik listelemek ve dizin oluşturmak için kapsayıcı düzeyinde SAS belirteçleri kullanamaz. Bu sınırlamanın nedeni, dizin oluşturucunun Dosya Sistemi - Özellikleri al API'sini çağırarak depolama hesabının hiyerarşik ad alanlarının etkinleştirilip etkinleştirilmediğini belirlemek için bir denetim yapmasıdır. Hiyerarşik ad alanlarının etkinleştirilmediği depolama hesapları için blobların yüksek performanslı numaralandırmasını sağlamak için blob dizin oluşturucularını kullanın.

• Özellik metadata_storage_path dizin anahtarı alanıyla eşlenmişse, bir dizin yeniden adlandırması üzerine blobların yeniden dizinlenmesi garanti edilmez. Yeniden adlandırılan dizinlerin parçası olan blobları yeniden dizine eklemek isterseniz, bunların tümü için zaman damgalarını güncelleyin LastModified.

Desteklenen belge biçimleri

ADLS 2. Nesil dizin oluşturucu aşağıdaki belge biçimlerinden metin ayıklayabilir:

• CSV (bkz. CSV bloblarının dizinini oluşturma)
• EML
• EPUB
• GZ
• HTML
• JSON (bkz. JSON bloblarını dizinleme)
• KML (coğrafi gösterimler için XML)
• Markdown
• Microsoft Office biçimleri: DOCX/DOC/DOCM, XLSX/XLS/XLSM, PPTX/PPT/PPTM, MSG (Outlook e-postaları), XML (hem 2003 hem de 2006 WORD XML)
• Belge biçimlerini açma: ODT, ODS, ODP
• PDF
• Düz metin dosyaları (ayrıca bkz. Düz metin dizini oluşturma)
• RTF
• XML
• Zip

Dizine eklemek istediğiniz blobları belirleme

Dizin oluşturmayı ayarlamadan önce, herhangi bir değişikliğin önceden yapılıp yapılmayacağını belirlemek için kaynak verilerinizi gözden geçirin. Dizin oluşturucu bir kerede bir kapsayıcıdaki içeriği dizine alabilir. Varsayılan olarak, kapsayıcıdaki tüm bloblar işlenir. Daha seçmeli işleme için çeşitli seçenekleriniz vardır:

• Blobları bir sanal klasöre yerleştirin. Dizin oluşturucu veri kaynağı tanımı , sanal klasör alabilen bir "sorgu" parametresi içerir. Sanal bir klasör belirtirseniz, yalnızca klasördeki bloblar dizine eklenir.

• Blobları dosya türüne göre dahil edin veya hariç tutun. Desteklenen belge biçimleri listesi , dışlamanız gereken blobları belirlemenize yardımcı olabilir. Örneğin, aranabilir metin sağlamayan görüntü veya ses dosyalarını dışlamak isteyebilirsiniz. Bu özellik, dizin oluşturucudaki yapılandırma ayarları aracılığıyla denetlenilir.

• Rastgele blobları dahil edin veya hariç tutun. Belirli bir blobu her nedenden dolayı atlamak istiyorsanız, Blob Depolama'daki bloblara aşağıdaki meta veri özelliklerini ve değerlerini ekleyebilirsiniz. Dizin oluşturucu bu özellik ile karşılaştığında, dizin oluşturma çalıştırmasında blobu veya içeriğini atlar.

  Özellik adı	Özellik değeri	Explanation
  AzureSearch_Skip	"true"	Blob dizin oluşturucusunun blobu tamamen atlamasını sağlar. Ne meta veriler ne de içerik ayıklama deneniyor. Bu, belirli bir blob tekrar tekrar başarısız olduğunda ve dizin oluşturma işlemini kestiğinde kullanışlıdır.
  "AzureSearch_SkipContent"	"true"	İçeriği atlar ve yalnızca meta verileri ayıklar. Bu ayar"dataToExtract" : "allMetadata" açıklanan ayara eşdeğerdir, ancak belirli bir blob için geçerlidir.

Ekleme veya dışlama ölçütlerini ayarlamazsanız, dizin oluşturucu uygun olmayan bir blobu hata olarak bildirir ve devam eder. Yeterli hata oluşursa işlem durdurulabilir. Dizin oluşturucu yapılandırma ayarlarında hataya dayanıklılık belirtebilirsiniz.

Dizin oluşturucu genellikle blob başına bir arama belgesi oluşturur ve burada metin içeriği ve meta veriler bir dizinde aranabilir alanlar olarak yakalanır. Bloblar tam dosyaysa, bunları birden çok arama belgesine ayrıştırabilirsiniz. Örneğin, bir CSV dosyasındaki satırları ayrıştırarak satır başına bir arama belgesi oluşturabilirsiniz.

Blob meta verilerini dizinleme

Standart veya özel meta veri özelliklerinden herhangi birinin filtreler ve sorgularda yararlı olduğunu düşünüyorsanız blob meta verilerini dizine alabilirsiniz.

Kullanıcı tarafından belirtilen meta veri özellikleri ayrıntılı olarak ayıklanır. Değerleri almak için, arama dizininde Edm.String blobun meta veri anahtarıyla aynı ada sahip bir alan tanımlamanız gerekir. Örneğin, bir blobun adı Sensitivity ve değeri High olan bir meta veri anahtarı varsa, arama dizininizde Sensitivity adlı ve High değeriyle doldurulan bir alan tanımlamanız gerekir.

Standart blob meta veri özellikleri, aşağıda listelendiği gibi benzer adlandırılmış ve yazılan alanlara ayıklanabilir. Blob dizinleyici, bu blob meta veri özellikleri için iç alan eşlemelerini otomatik olarak oluşturur ve orijinal kısa çizgili adı ("metadata-storage-name") alt çizgili eşdeğer ad ("metadata_storage_name") olarak dönüştürür.

Yine de dizin tanımına alt puanlanmış alanları eklemeniz gerekir, ancak dizin oluşturucu ilişkilendirmeyi otomatik olarak yaptığından alan eşlemelerini atlayabilirsiniz.

• metadata_storage_name (Edm.String) - blobun dosya adı. Örneğin, /my-container/my-folder/subfolder/resume.pdf şeklinde bir blob varsa, bu alanın değeri resume.pdf olur.

• metadata_storage_path (Edm.String) - depolama hesabı dahil olmak üzere blobun tam URI'si. Örneğin, https://myaccount.blob.core.windows.net/my-container/my-folder/subfolder/resume.pdf

• metadata_storage_content_type (Edm.String) - blobu karşıya yüklemek için kullandığınız kod tarafından belirtilen içerik türü. Örneğin, application/octet-stream.

• metadata_storage_last_modified (Edm.DateTimeOffset) - blob için son değiştirilen zaman damgası. Azure Yapay Zeka Arama, ilk dizin oluşturma işleminden sonra her şeyin yeniden dizine alınmasını önlemek için değiştirilen blobları tanımlamak için bu zaman damgasını kullanır.

• metadata_storage_size (Edm.Int64) - bayt cinsinden blob boyutu.

• metadata_storage_content_md5 (Edm.String) - Varsa blob içeriğinin MD5 karması.

• metadata_storage_sas_token (Edm.String) - Bloba erişim sağlamak için özel beceriler tarafından kullanılabilecek geçici bir SAS belirteci. Bu belirtecin süresi dolabileceği için daha sonra kullanılmak üzere depolanmaması gerekir.

Son olarak, dizine eklediğiniz blobların belge biçimine özgü tüm meta veri özellikleri de dizin şemasında gösterilebilir. İçeriğe özgü meta veriler hakkında daha fazla bilgi için bkz . İçerik meta veri özellikleri.

Arama dizininizde yukarıdaki özelliklerin tümü için alan tanımlamanıza gerek olmadığını belirtmek önemlidir. Yalnızca uygulamanız için ihtiyacınız olan özellikleri yakalayın.

Veri kaynağını tanımlama

Veri kaynağı tanımı, verilerdeki değişiklikleri tanımlamak için dizine eklenecek verileri, kimlik bilgilerini ve ilkeleri belirtir. Veri kaynağı, birden çok dizin oluşturucu tarafından kullanılabilmesi için bağımsız bir kaynak olarak tanımlanır.

1. Tanımını ayarlamak için bir veri kaynağı oluşturun veya güncelleştirin:

   {
       "name" : "my-adlsgen2-datasource",
       "type" : "adlsgen2",
       "credentials" : { "connectionString" : "DefaultEndpointsProtocol=https;AccountName=<account name>;AccountKey=<account key>;" },
       "container" : { "name" : "my-container", "query" : "<optional-virtual-directory-name>" }
   }
   

2. "type" değerini (gerekli) olarak "adlsgen2" ayarlayın.

3. "credentials" bir Azure Depolama bağlantı dizesi olarak ayarlayın. Sonraki bölümde desteklenen biçimler açıklanmaktadır.

4. "container" öğesini blob kapsayıcısı olarak ayarlayın ve alt klasörleri belirtmek için "query" kullanın.

Veri kaynağı tanımı, kaynak belgenin silinmek üzere işaretlendiğinde dizin oluşturucunun bir arama belgesini silmesini istiyorsanız, yumuşak silme politikalarını da içerebilir.

Desteklenen kimlik bilgileri ve bağlantı dizesi

Dizin oluşturucular aşağıdaki bağlantıları kullanarak bir blob kapsayıcısına bağlanabilir.

Dizine arama alanları ekleme

Arama dizininde, Azure bloblarınızın içeriğini ve meta verilerini kabul etmek için alanlar ekleyin.

1. Blob içeriğini ve meta verilerini depolayan arama alanlarını tanımlamak için dizin oluşturun veya güncelleştirin:

   {
       "name" : "my-search-index",
       "fields": [
           { "name": "ID", "type": "Edm.String", "key": true, "searchable": false },
           { "name": "content", "type": "Edm.String", "searchable": true, "filterable": false },
           { "name": "metadata_storage_name", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_size", "type": "Edm.Int64", "searchable": false, "filterable": true, "sortable": true  },
           { "name": "metadata_storage_content_type", "type": "Edm.String", "searchable": false, "filterable": true, "sortable": true }     
       ]
   }
   

2. Belge anahtarı alanı oluştur ("anahtar": true). Blob içeriği için en iyi adaylar meta veri özellikleridir.

   • metadata_storage_path (varsayılan) nesnenin veya dosyanın tam yolu. Bu örnekteki anahtar alanı ("Kimlik") varsayılan değer olduğundan metadata_storage_path değerleriyle doldurulur.

   • metadata_storage_name, yalnızca adlar benzersizse kullanılabilir. Bu alanın anahtar olarak olmasını istiyorsanız, bu alan tanımına gidin "key": true .

   • Bloblara eklediğiniz özel meta veri özelliği. Bu seçenek, blob karşıya yükleme işleminizin bu meta veri özelliğini tüm bloblara eklemesini gerektirir. Anahtar gerekli bir özellik olduğundan, değeri eksik olan tüm bloblar dizine alınamaz. Anahtar olarak özel meta veri özelliği kullanıyorsanız, bu özellikte değişiklik yapmaktan kaçının. Anahtar özelliği değişirse dizin oluşturucular aynı blob için yinelenen belgeler ekler.

   Meta veri özellikleri genellikle / ve - gibi belge anahtarları için geçersiz karakterler içerir. Dizin oluşturucu, yapılandırma veya alan eşlemesi gerektirmeden anahtar meta veri özelliğini otomatik olarak kodlar.

3. Blob'un "content" özelliği aracılığıyla her dosyadan ayıklanan metni depolamak için bir "içerik" alanı ekleyin. Bu adı kullanmanız gerekmez, ancak bunu yaptığınızda örtük alan eşlemelerinden yararlanabilirsiniz.

4. Standart meta veri özellikleri için alanlar ekleyin. Dizin oluşturucu özel meta veri özelliklerini, standart meta veri özelliklerini ve içeriğe özgü meta veri özelliklerini okuyabilir.

ADLS 2. Nesil dizin oluşturucusunu yapılandırma ve çalıştırma

Dizin ve veri kaynağı oluşturulduktan sonra dizin oluşturucuyu oluşturmaya hazır olursunuz. Dizin oluşturucu yapılandırması, çalışma zamanı davranışlarını denetleen girişleri, parametreleri ve özellikleri belirtir. Bir blobun hangi bölümlerinin dizine ekleneceğini de belirtebilirsiniz.

1. Dizin oluşturucuya bir ad verip veri kaynağına ve hedef dizine başvurarak dizin oluşturucu oluşturun veya güncelleştirin:

   {
     "name" : "my-adlsgen2-indexer",
     "dataSourceName" : "my-adlsgen2-datasource",
     "targetIndexName" : "my-search-index",
     "parameters": {
         "batchSize": null,
         "maxFailedItems": null,
         "maxFailedItemsPerBatch": null,
         "configuration": {
             "indexedFileNameExtensions" : ".pdf,.docx",
             "excludedFileNameExtensions" : ".png,.jpeg",
             "dataToExtract": "contentAndMetadata",
             "parsingMode": "default"
         }
     },
     "schedule" : { },
     "fieldMappings" : [ ]
   }
   

2. Varsayılan (10 belge) kullanılabilir kaynakları az kullanıyor veya bunaltıyorsa "batchSize" değerini ayarlayın. Varsayılan toplu iş boyutları veri kaynağına özeldir. Blob indeksleme, daha büyük ortalama belge boyutu göz önünde bulundurularak toplu iş boyutunu 10 belge olarak ayarlar.

3. "Yapılandırma" altında, hangi blobların dosya türüne göre dizine alınıp alınacağını denetleyin veya tüm blobları almak istiyorsanız belirtmeyin.

   için "indexedFileNameExtensions", dosya uzantılarının virgülle ayrılmış bir listesini sağlayın (baştaki noktayla). Hangi uzantıların atlanması gerektiğini belirtmek için "excludedFileNameExtensions" de aynısını yapın. Aynı uzantı her iki listede de yer alırsa dizin oluşturmanın dışında tutulur.

4. "yapılandırma" bölümünde blobların hangi bölümlerinin dizine eklendiğini denetlemek için "dataToExtract" değerini ayarlayın:

   • "contentAndMetadata", blobdan ayıklanan tüm meta verilerin ve metin içeriğinin dizine alındığını belirtir. Bu varsayılan değerdir.

   • "storageMetadata", yalnızca standart blob özelliklerinin ve kullanıcı tarafından belirtilen meta verilerin dizine alındığını belirtir.

   • "allMetadata", standart blob özelliklerinin ve bulunan içerik türleri için meta verilerin blob içeriğinden ayıklandığını ve dizine alındığını belirtir.

5. Blobların birden çok arama belgesine eşlenmesi gerekiyorsa veya düz metin, JSON belgeleri veya CSV dosyalarından oluşuyorsa "configuration" altında "parsingMode" değerini ayarlayın.

6. Alan adında veya türünde farklılıklar varsa veya arama dizininde bir kaynak alanın birden çok sürümüne ihtiyacınız varsa alan eşlemelerini belirtin.

   Blob dizin oluşturmada, dizin oluşturucunun "içerik" ve meta veri özelliklerini dizindeki benzer adlandırılmış ve yazılan alanlarla eşlemeye yönelik yerleşik desteği olduğundan, alan eşlemelerini atlayabilirsiniz. Meta veri özellikleri için dizin oluşturucu, kısa çizgileri - otomatik olarak arama dizinindeki alt çizgilerle değiştirir.

7. Diğer özellikler hakkında daha fazla bilgi için Dizin Oluşturucu Oluştur'a bakın. Parametre açıklamalarının tam listesi için bkz . REST API'de Dizin Oluşturucu (REST) oluşturma.

Dizin oluşturucu oluşturulduğunda otomatik olarak çalışır. "Devre dışı" ayarını true olarak ayarlayarak bunu önleyebilirsiniz. Dizin oluşturucu yürütmesini denetlemek için isteğe bağlı olarak bir dizin oluşturucu çalıştırın veya zamanlamaya yerleştirin.

Dizin oluşturucu durumunu denetle

Dizin oluşturucu durumunu ve yürütme geçmişini izlemek için bir Oluşturucu Durumunu Al isteği gönderin.

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2026-04-01
  Content-Type: application/json  
  api-key: [admin key]

Yanıt, durumu ve işlenen öğe sayısını içerir. Aşağıdaki örneğe benzer görünmelidir:

    {
        "status":"running",
        "lastResult": {
            "status":"success",
            "errorMessage":null,
            "startTime":"2024-02-21T00:23:24.957Z",
            "endTime":"2024-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2024-02-21T00:23:24.957Z",
                "endTime":"2024-02-21T00:36:47.752Z",
                "errors":[],
                "itemsProcessed":1599501,
                "itemsFailed":0,
                "initialTrackingState":null,
                "finalTrackingState":null
            },
            ... earlier history items
        ]
    }

Yürütme geçmişi, en son tamamlanan yürütmelerin en son 50'sini içerir ve en son yürütme önce gelecek şekilde ters kronolojik sırada sıralanır.

Hatalarla başa çıkma

Dizin oluşturma sırasında sık karşılaşılan hatalar desteklenmeyen içerik türleri, eksik içerik veya büyük harfli bloblardır.

Varsayılan olarak, blob dizin oluşturucu desteklenmeyen içerik türüne (örneğin bir ses dosyası) sahip bir blobla karşılaştığında durur. Belirli içerik türlerini atlamak için "excludedFileNameExtensions" parametresini kullanabilirsiniz. Ancak, hatalar oluşsa bile dizin oluşturma işleminin devam edip daha sonra tek tek belgelerde hata ayıklamasını isteyebilirsiniz. Dizin oluşturucu hataları hakkında daha fazla bilgi için bkz . Dizin oluşturucu sorun giderme kılavuzu ve Dizin oluşturucu hataları ve uyarıları.

Hatalar oluştuğunda dizin oluşturucunun yanıtını denetleyebilen beş dizin oluşturucu özelliği vardır.

PUT /indexers/[indexer name]?api-version=2026-04-01
{
  "parameters" : { 
    "maxFailedItems" : 10, 
    "maxFailedItemsPerBatch" : 10,
    "configuration" : { 
        "failOnUnsupportedContentType" : false, 
        "failOnUnprocessableDocument" : false,
        "indexStorageMetadataOnlyForOversizedDocuments": false
    }
  }
}

Sonraki Adımlar

Artık dizin oluşturucuyu çalıştırabilir, durumu izleyebilir veya dizin oluşturucu yürütmesini zamanlayabilirsiniz. Aşağıdaki makaleler Azure Depolama'dan içerik çeken dizin oluşturucular için geçerlidir:

• Değişiklik algılama ve silme algılama
• Büyük veri kümelerini dizine ekleme
• C# Örneği: Microsoft Entra Id kullanarak Veri Gölü 2. Nesil dizinini oluşturma