Azure AI Search'te Azure SQL'den verileri dizine ekleme

Bu makalede, Azure SQL Veritabanı veya Azure SQL yönetilen örneğinden içerik içeri aktaran ve Azure AI Search'te aranabilir hale getiren bir dizin oluşturucu yapılandırmayı öğrenin.

Bu makale, Azure SQL'e özgü bilgilerle dizin oluşturucu oluşturma makalesini 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.

Bu makalede ayrıca şunlar sağlanır:

• Artımlı dizin oluşturma ayarlayabilmeniz için Azure SQL dizin oluşturucu tarafından desteklenen değişiklik algılama ilkelerinin açıklaması.

• Özellik uyumluluğu hakkındaki soruların yanıtları için sık sorulan sorular (SSS) bölümü.

Önkoşullar

• Tek bir tablo veya görünümdeki verileri içeren bir Azure SQL veritabanı ya da genel uç nokta içeren bir SQL Yönetilen Örneği.

  Verileriniz büyükse veya SQL'in yerel değişiklik algılama özelliklerini kullanarak artımlı dizine ihtiyacınız varsa bir tablo kullanın.

  Birden çok tabloya ait verileri birleştirmeniz gerekiyorsa bir görünüm kullanın. Büyük görünümler SQL dizin oluşturucu için ideal değildir. Geçici bir çözüm, yalnızca Azure AI Search dizininize alım için yeni bir tablo oluşturmaktır. Yüksek Su İşareti'ne göre uygulanması daha kolay olan SQL tümleşik değişiklik izleme özelliğini kullanabileceksiniz.

• Okuma izinleri. Azure AI Search, kullanıcı adı ve parolanın bağlantı dizesi sağlandığı SQL Server kimlik doğrulamasını destekler. Alternatif olarak, yönetilen kimlik ayarlayabilir ve Azure rollerini kullanabilirsiniz.

Bu makaledeki örnekleri inceleyebilmek için bir REST istemcisine ihtiyacınız vardır.

Azure SQL dizin oluşturucu oluşturmaya yönelik diğer yaklaşımlar arasında Azure SDK'ları veya Azure portalındaki Verileri içeri aktarma sihirbazı sayılabilir. Azure portalını kullanıyorsanız, Azure SQL güvenlik duvarında tüm genel ağlara erişimin etkinleştirildiğinden ve istemcinin bir gelen kuralı üzerinden erişimi olduğundan emin olun.

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 Veri Kaynağı Oluştur veya Veri Kaynağı Oluştur veya Güncelleştir:

    POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
    Content-Type: application/json
    api-key: admin-key
   
    {
        "name" : "myazuresqldatasource",
        "description" : "A database for testing Azure AI Search indexes.",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "Server=tcp:<your server>.database.windows.net,1433;Database=<your database>;User ID=<your user name>;Password=<your password>;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },
        "container" : { 
            "name" : "name of the table or view that you want to index",
            "query" : null (not supported in the Azure SQL indexer)
            },
        "dataChangeDetectionPolicy": null,
        "dataDeletionDetectionPolicy": null,
        "encryptionKey": null,
        "identity": null
    }
   

2. Veri kaynağı için Azure AI Search adlandırma kurallarına uygun benzersiz bir ad sağlayın.

3. "type" değerini (gerekli) olarak "azuresql" ayarlayın.

4. "Kimlik bilgilerini" bir bağlantı dizesi olarak ayarlayın:

   • Azure portalından tam erişim bağlantı dizesi alabilirsiniz. ADO.NET connection string seçeneğini kullanın. Kullanıcı adını ve parolayı ayarlayın.

   • Alternatif olarak, aşağıdaki biçime sahip veritabanı gizli dizilerini içermeyen bir yönetilen kimlik bağlantı dizesi belirtebilirsiniz: Initial Catalog|Database=<your database name>;ResourceId=/subscriptions/<your subscription ID>/resourceGroups/<your resource group name>/providers/Microsoft.Sql/servers/<your SQL Server name>/;Connection Timeout=connection timeout length;.

   Daha fazla bilgi için bkz. Yönetilen kimlik kullanarak Azure SQL Veritabanı dizin oluşturucuya bağlanma.

Dizine arama alanları ekleme

Arama dizininde, SQL veritabanındaki alanlara karşılık gelen alanlar ekleyin. Eşdeğer veri türlerini kullanarak arama dizini şemasının kaynak şemayla uyumlu olduğundan emin olun.

1. Verileri depolayacak arama alanlarını tanımlamak için bir dizin oluşturun veya güncelleştirin:

   POST https://[service name].search.windows.net/indexes?api-version=2024-07-01
   Content-Type: application/json
   api-key: [Search service admin key]
   {
       "name": "mysearchindex",
       "fields": [{
           "name": "id",
           "type": "Edm.String",
           "key": true,
           "searchable": false
       }, 
       {
           "name": "description",
           "type": "Edm.String",
           "filterable": false,
           "searchable": true,
           "sortable": false,
           "facetable": false,
           "suggestions": true
       }
     ]
   }
   

2. Her arama belgesini benzersiz olarak tanımlayan bir belge anahtarı alanı ("anahtar": true) oluşturun. Arama dizininde gerekli olan tek alan budur. Genellikle tablonun birincil anahtarı dizin anahtarı alanına eşlenir. Belge anahtarı benzersiz ve null olmayan olmalıdır. Değerler kaynak verilerde sayısal olabilir, ancak arama dizininde anahtar her zaman bir dizedir.

3. Daha fazla aranabilir içerik eklemek için daha fazla alan oluşturun. Yönergeler için bkz . Dizin oluşturma.

Eşleme veri türleri

Azure SQL 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.

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

   POST https://[service name].search.windows.net/indexers?api-version=2024-07-01
   Content-Type: application/json
   api-key: [search service admin key]
   {
       "name" : "[my-sqldb-indexer]",
       "dataSourceName" : "[my-sqldb-ds]",
       "targetIndexName" : "[my-search-index]",
       "disabled": null,
       "schedule": null,
       "parameters": {
           "batchSize": null,
           "maxFailedItems": 0,
           "maxFailedItemsPerBatch": 0,
           "base64EncodeKeys": false,
           "configuration": {
               "queryTimeout": "00:04:00",
               "convertHighWaterMarkToRowVersion": false,
               "disableOrderByHighWaterMarkColumn": false
           }
       },
       "fieldMappings": [],
       "encryptionKey": null
   }
   

2. Parametreler altında yapılandırma bölümünde Azure SQL'e özgü parametreler bulunur:

   • SQL sorgu yürütmesi için varsayılan sorgu zaman aşımı 5 dakikadır ve bunu geçersiz kılabilirsiniz.

   • "convertHighWaterMarkToRowVersion" Yüksek Su İşareti Değişiklik Algılama ilkesi için iyileştirir. Değişiklik algılama ilkeleri veri kaynağında ayarlanır. Yerel değişiklik algılama ilkesini kullanıyorsanız, bu parametrenin hiçbir etkisi yoktur.

   • "disableOrderByHighWaterMarkColumn", yüksek su işareti ilkesi tarafından kullanılan SQL sorgusunun ORDER BY yan tümcesini atlamasına neden olur. Yerel değişiklik algılama ilkesini kullanıyorsanız, bu parametrenin hiçbir etkisi yoktur.

3. 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.

4. Diğer özellikler hakkında daha fazla bilgi için bkz . Dizin oluşturucu 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 denetleme

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

GET https://myservice.search.windows.net/indexers/myindexer/status?api-version=2024-07-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":"2022-02-21T00:23:24.957Z",
            "endTime":"2022-02-21T00:36:47.752Z",
            "errors":[],
            "itemsProcessed":1599501,
            "itemsFailed":0,
            "initialTrackingState":null,
            "finalTrackingState":null
        },
        "executionHistory":
        [
            {
                "status":"success",
                "errorMessage":null,
                "startTime":"2022-02-21T00:23:24.957Z",
                "endTime":"2022-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.

Yeni, değiştirilmiş ve silinmiş satırları dizine ekleme

SQL veritabanınız değişiklik izlemeyi destekliyorsa, arama dizin oluşturucu sonraki dizin oluşturucu çalıştırmalarında yalnızca yeni ve güncelleştirilmiş içeriği alabilir.

Artımlı dizin oluşturmayı etkinleştirmek için veri kaynağı tanımınızda "dataChangeDetectionPolicy" özelliğini ayarlayın. Bu özellik, dizin oluşturucuya tablonuzda veya görünümünüzde hangi değişiklik izleme mekanizmasının kullanıldığını bildirir.

Azure SQL dizin oluşturucuları için iki değişiklik algılama ilkesi vardır:

• "SqlIntegratedChangeTrackingPolicy" (yalnızca tablolar için geçerlidir)

• "HighWaterMarkChangeDetectionPolicy" (tablolar ve görünümler için çalışır)

SQL Tümleşik Değişiklik İzleme İlkesi

Verimliliği ve silinen satırları tanımlama yeteneği için "SqlIntegratedChangeTrackingPolicy" kullanmanızı öneririz.

Veritabanı gereksinimleri:

• SQL Server 2012 SP3 ve üstü (Azure VM'lerinde SQL Server kullanıyorsanız)
• Azure SQL Veritabanı veya SQL Yönetilen Örneği
• Yalnızca tablolar (görünüm yok)
• Veritabanında, tablo için değişiklik izlemeyi etkinleştirin
• Tabloda bileşik birincil anahtar (birden fazla sütun içeren birincil anahtar) yok
• Tabloda kümelenmiş dizin yok. Geçici bir çözüm olarak kümelenmiş tüm dizinlerin bırakılması ve kümelenmemiş dizin olarak yeniden oluşturulması gerekir, ancak kümelenmiş dizine kıyasla kaynakta performans etkilenebilir

Değişiklik algılama ilkeleri veri kaynağı tanımlarına eklenir. Bu ilkeyi kullanmak için veri kaynağınızı şu şekilde oluşturun veya güncelleştirin:

POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: admin-key
    {
        "name" : "myazuresqldatasource",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "connection string" },
        "container" : { "name" : "table name" },
        "dataChangeDetectionPolicy" : {
            "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy"
    }

SQL tümleşik değişiklik izleme ilkesini kullanırken ayrı bir veri silme algılama ilkesi belirtmeyin. SQL tümleşik değişiklik izleme ilkesi, silinen satırları tanımlamaya yönelik yerleşik desteğe sahiptir. Ancak, silinen satırların otomatik olarak algılanması için, arama dizininizdeki belge anahtarı SQL tablosundaki birincil anahtarla aynı olmalıdır.

Yüksek Su İşareti Değişiklik Algılama ilkesi

Bu değişiklik algılama ilkesi, tablonuzda veya görünümde bir satırın son güncelleştirildiği sürümü veya saati yakalayan bir "yüksek su işareti" sütununa dayanır. Görünüm kullanıyorsanız yüksek su işareti ilkesi kullanmanız gerekir.

Yüksek su işareti sütunu aşağıdaki gereksinimleri karşılamalıdır:

• Tüm eklemeler sütun için bir değer belirtir.
• Bir öğedeki tüm güncelleştirmeler sütunun değerini de değiştirir.
• Her ekleme veya güncelleştirmede bu sütunun değeri artar.
• Aşağıdaki WHERE ve ORDER BY yan tümcelerine sahip sorgular verimli bir şekilde yürütülebilir: WHERE [High Water Mark Column] > [Current High Water Mark Value] ORDER BY [High Water Mark Column]

Değişiklik algılama ilkeleri veri kaynağı tanımlarına eklenir. Bu ilkeyi kullanmak için veri kaynağınızı şu şekilde oluşturun veya güncelleştirin:

POST https://myservice.search.windows.net/datasources?api-version=2024-07-01
Content-Type: application/json
api-key: admin-key
    {
        "name" : "myazuresqldatasource",
        "type" : "azuresql",
        "credentials" : { "connectionString" : "connection string" },
        "container" : { "name" : "table or view name" },
        "dataChangeDetectionPolicy" : {
            "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy",
            "highWaterMarkColumnName" : "[a rowversion or last_updated column name]"
        }
    }

convertHighWaterMarkToRowVersion

Yüksek su işareti sütunu için rowversion veri türü kullanıyorsanız dizin oluşturucu yapılandırmasında özelliğini ayarlamayı convertHighWaterMarkToRowVersion göz önünde bulundurun. Bu özelliğin true olarak ayarlanması aşağıdaki davranışlara neden olur:

• Dizin oluşturucu SQL sorgusundaki yüksek su işareti sütunu için rowversion veri türünü kullanır. Doğru veri türünün kullanılması dizin oluşturucu sorgu performansını artırır.

• Dizin oluşturucu sorgusu çalışmadan önce rowversion değerinden bir tane çıkarır. Bire çok birleşimleri olan görünümlerde yinelenen rowversion değerlerine sahip satırlar olabilir. Birinin çıkarılması, dizin oluşturucu sorgusunun bu satırları kaçırmamasını sağlar.

Bu özelliği etkinleştirmek için dizin oluşturucuyu aşağıdaki yapılandırmayla oluşturun veya güncelleştirin:

    {
      ... other indexer definition properties
     "parameters" : {
            "configuration" : { "convertHighWaterMarkToRowVersion" : true } }
    }

queryTimeout

Zaman aşımı hatalarıyla karşılaşırsanız dizin oluşturucu yapılandırma ayarını varsayılan 5 dakikalık zaman aşımından daha yüksek bir değere ayarlayın queryTimeout . Örneğin, zaman aşımını 10 dakikaya ayarlamak için dizin oluşturucuyu aşağıdaki yapılandırmayla oluşturun veya güncelleştirin:

    {
      ... other indexer definition properties
     "parameters" : {
            "configuration" : { "queryTimeout" : "00:10:00" } }
    }

disableOrderByHighWaterMarkColumn

Yan tümcesini ORDER BY [High Water Mark Column] de devre dışı bırakabilirsiniz. Ancak dizin oluşturucu yürütmesi bir hatayla kesildiğinde dizin oluşturucunun kesintiye uğradığı sırada neredeyse tüm satırları zaten işlemiş olsa bile daha sonra çalıştırılırsa tüm satırları yeniden işlemesi gerektiğinden bu önerilmez. Yan tümcesini ORDER BY devre dışı bırakmak için dizin oluşturucu tanımındaki ayarı kullanın disableOrderByHighWaterMarkColumn :

    {
     ... other indexer definition properties
     "parameters" : {
            "configuration" : { "disableOrderByHighWaterMarkColumn" : true } }
    }

Geçici Silme Sütunu Silme Algılama ilkesi

Satırlar kaynak tablodan silindiğinde, bu satırları arama dizininden de silmek isteyebilirsiniz. SQL tümleşik değişiklik izleme ilkesini kullanırsanız, bu sizin için halledilir. Ancak, yüksek su işareti değişiklik izleme ilkesi silinen satırlarda size yardımcı olmaz. Ne yapmalı?

Satırlar tablodan fiziksel olarak kaldırılırsa, Azure AI Search'ün artık mevcut olmayan kayıtların varlığını çıkarsama yolu yoktur. Ancak, satırları tablodan kaldırmadan mantıksal olarak silmek için "geçici silme" tekniğini kullanabilirsiniz. Tablonuza bir sütun ekleyin veya bu sütunu kullanarak satırları silindi olarak işaretleyin.

Geçici silme tekniğini kullanırken, veri kaynağını oluştururken veya güncelleştirirken geçici silme ilkesini aşağıdaki gibi belirtebilirsiniz:

    {
        …,
        "dataDeletionDetectionPolicy" : {
           "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy",
           "softDeleteColumnName" : "[a column name]",
           "softDeleteMarkerValue" : "[the value that indicates that a row is deleted]"
        }
    }

softDeleteMarkerValue, veri kaynağınızın JSON gösteriminde bir dize olmalıdır. Gerçek değerinizin dize gösterimini kullanın. Örneğin, silinen satırların 1 değeriyle işaretlendiği bir tamsayı sütununu kullanıyorsanız kullanın "1". Silinen satırların Boole gerçek değeriyle işaretlendiği bir BIT sütuna sahipseniz, sabit veya "true"dizesini "True" kullanın. Büyük/küçük harf fark etmez.

Azure portalından geçici silme ilkesi ayarlanıyorsa geçici silme işaretçisi değerinin çevresine tırnak işareti eklemeyin. Alan içeriği zaten bir dize olarak anlaşılmıştır ve sizin için otomatik olarak bir JSON dizesine çevrilir. Yukarıdaki örneklerde, portalın alanına veya true yazmanız 1True yeterlidir.

SSS

S: Always Encrypted sütunlarını dizine ekleyebilir miyim?

Hayır, Always Encrypted sütunları şu anda Azure AI Search dizin oluşturucuları tarafından desteklenmiyor.

S: Azure'da IaaS VM'lerinde çalışan SQL veritabanlarıyla Azure SQL dizin oluşturucu kullanabilir miyim?

Evet. Ancak, arama hizmetinizin veritabanınıza bağlanmasına izin vermeniz gerekir. Daha fazla bilgi için bkz . Azure AI Search dizin oluşturucudan Azure VM'de SQL Server'a bağlantı yapılandırma.

S: Şirket içinde çalışan SQL veritabanlarıyla Azure SQL dizin oluşturucu kullanabilir miyim?

Doğrudan değil. Veritabanlarınızı İnternet trafiğine açmanız gerekeceğinden doğrudan bağlantı önermiyoruz veya desteklemiyoruz. Müşteriler, Azure Data Factory gibi köprü teknolojilerini kullanarak bu senaryoyla başarılı olmuştur. Daha fazla bilgi için bkz . Azure Data Factory kullanarak Azure AI Search dizinine veri gönderme.

S: Yük devretme kümesinde ikincil çoğaltmayı veri kaynağı olarak kullanabilir miyim?

Duruma göre değişir. Bir tablonun veya görünümün tam dizini için ikincil çoğaltma kullanabilirsiniz.

Artımlı dizin oluşturma için Azure AI Search iki değişiklik algılama ilkesi destekler: SQL tümleşik değişiklik izleme ve Yüksek Su İşareti.

Salt okunur çoğaltmalarda SQL Veritabanı tümleşik değişiklik izlemeyi desteklemez. Bu nedenle, Yüksek Su İşareti ilkesini kullanmanız gerekir.

Standart önerimiz, yüksek su işareti sütunu için rowversion veri türünü kullanmaktır. Ancak rowversion kullanmak, salt okunur çoğaltmalarda MIN_ACTIVE_ROWVERSION desteklenmeyen işleve dayanır. Bu nedenle, rowversion kullanıyorsanız dizin oluşturucuyu birincil çoğaltmaya işaret etmeniz gerekir.

Salt okunur bir çoğaltmada rowversion kullanmayı denerseniz aşağıdaki hatayı görürsünüz:

"Değişiklik izleme için rowversion sütunu kullanılması ikincil (salt okunur) kullanılabilirlik çoğaltmalarında desteklenmez. Lütfen veri kaynağını güncelleştirin ve birincil kullanılabilirlik çoğaltmasına bir bağlantı belirtin. Geçerli veritabanı 'Updateability' özelliği 'READ_ONLY'" şeklindedir.

S: Yüksek su işareti değişiklik izlemesi için alternatif, rowversion olmayan bir sütun kullanabilir miyim?

Bu önerilmez. Yalnızca rowversion güvenilir veri eşitlemesine izin verir. Ancak, uygulama mantığınıza bağlı olarak, aşağıdakiler güvenli olabilir:

• Dizin oluşturucu çalıştırıldığında, dizine alınan tabloda bekleyen işlem olmadığından emin olabilirsiniz (örneğin, tüm tablo güncelleştirmeleri bir zamanlamaya göre toplu iş olarak gerçekleşir ve Azure AI Search dizin oluşturucu zamanlaması, tablo güncelleştirme zamanlaması ile çakışmasını önlemek için ayarlanır).

• Eksik satırları almak için düzenli aralıklarla tam bir yeniden dizin oluşturma işlemi yaparsınız.