Aracılığıyla paylaş

Hızlı Başlangıç: Tam metin arama

Bu hızlı başlangıçta, .NET için Azure AI Search istemci kitaplığını kullanarak anahtar sözcük arama olarak da bilinen full-text search arama dizinini oluşturur, yükler ve sorgularsınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-dotnet-samples

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

    cd azure-search-dotnet-samples/quickstart-keyword-search/AzureSearchQuickstart
code .

  3. Program.cs'da, serviceEndpoint yer tutucu değerini Get uç noktası içinde aldığınız URL ile değiştirin.

  4. AzureSearchQuickstart.csproj'den bağımlılıkları yükleyin.

    dotnet restore

    Geri yükleme tamamlandığında, çıkışta hata görünmediğini doğrulayın.

  5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştır

Uygulamayı derleyin ve çalıştırın.

dotnet run

Çıktı

Çıkış aşağıdakine benzer olmalıdır:

Deleting index...

Creating index...

Uploading documents...

Waiting for indexing...

Starting queries...

Query #1: Search on empty term '*' to return all documents, showing a subset of fields...

HotelId: 3
Name: Gastronomic Landscape Hotel
Rating: 4.8

HotelId: 2
Name: Old Century Hotel
Rating: 3.6

HotelId: 4
Name: Sublime Palace Hotel
Rating: 4.6

HotelId: 1
Name: Stay-Kay City Hotel
Rating: 3.6


Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...

HotelId: 3
Name: Gastronomic Landscape Hotel
Rating: 4.8

HotelId: 4
Name: Sublime Palace Hotel
Rating: 4.6


Query #3: Limit search to specific fields (pool in Tags field)...

HotelId: 2
Name: Old Century Hotel
Tags: [ pool, free wifi, concierge ]


Query #4: Facet on 'Category'...

HotelId: 3
Name: Gastronomic Landscape Hotel
Category: Suite

HotelId: 2
Name: Old Century Hotel
Category: Boutique

HotelId: 4
Name: Sublime Palace Hotel
Category: Boutique

HotelId: 1
Name: Stay-Kay City Hotel
Category: Boutique


Query #5: Look up a specific document...

3
Query #6: Call Autocomplete on HotelName...

san
sarasota

Complete. Press any key to end this program...

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Arama istemcisi oluşturma
  2. Arama dizini oluşturma
  3. Belgeleri dizine yükleme
  4. Dizini sorgulama

Arama istemcisi oluşturma

içinde Program.csiki istemci oluşturursunuz:

Her iki istemci için de hizmet uç noktası ve kimlik doğrulaması için bir kimlik bilgisi gerekir. Bu hızlı başlangıçta, Microsoft Entra ID ile anahtarsız kimlik doğrulaması için DefaultAzureCredential kullanacaksınız.

Arama dizini oluşturma

Bu hızlı başlangıçta, otel verileriyle birlikte yükleyip sorgular yürütdüğünüz bir otel dizini oluşturacaksınız. Bu adımda, dizindeki alanları tanımlarsınız. Her alan tanımı, alanın nasıl kullanıldığını belirleyen bir ad, veri türü ve öznitelikler içerir.

Bu örnek, kolaylık ve okunabilirlik için SearchIndexClient sınıfının zaman uyumlu yöntemlerini kullanır. Ancak üretim senaryolarında, uygulamanızı ölçeklenebilir ve duyarlı tutmak için zaman uyumsuz yöntemler kullanın. Örneğin, CreateIndex yerine CreateIndexAsync kullanın.

Yapıları tanımlama

Bir otel belgesinin yapısını ve adresini tanımlamak için Hotel.cs ve Address.cs olmak üzere iki yardımcı sınıf oluşturursunuz. Sınıfı Hotel bir otel kimliği, ad, açıklama, kategori, etiketler, otopark, yenileme tarihi, derecelendirme ve adres için alanlar içerir. Address sınıfı sokak adresi, şehir, eyalet/il, posta kodu ve ülke/bölge alanlarını içerir.

Azure. Search.Documents istemci kitaplığı, alan tanımlarını kolaylaştırmak için SearchableField ve SimpleField kullanabilirsiniz. Her ikisi de SearchField oluşturan ve kodunuzu basitleştirebilecek yardımcı sınıflardır:

  • SimpleField herhangi bir veri türü olabilir, her zaman aranamaz (tam metin arama sorguları için yoksayılır) ve alınabilir (gizli değildir). Diğer öznitelikler varsayılan olarak kapalıdır, ancak etkinleştirilebilir. SimpleField belge kimlikleri veya yalnızca filtrelerde, modellerde veya puanlama profillerinde kullanılan alanlar için kullanabilirsiniz. Bu durumda, belge kimliği gibi IsKey = true senaryo için gerekli olan öznitelikleri uygulayın.

  • SearchableField bir dize olmalıdır ve her zaman aranabilir ve alınabilir. Diğer öznitelikler varsayılan olarak kapalıdır, ancak etkinleştirilebilir. Bu alan türü aranabilir olduğundan, eş anlamlıları ve çözümleyici özelliklerinin tam tamamlayıcısını destekler.

İster temel SearchField API'yi ister yardımcı modellerden birini kullanın, filtre, model ve sıralama özniteliklerini açıkça etkinleştirmeniz gerekir. Örneğin, önceki örnekte gösterildiği gibi IsFilterable, IsSortable ve IsFacetable açıkça ilişkilendirilmelidir.

Arama dizinini oluşturma

içinde Program.csbir SearchIndex nesnesi oluşturup createOrUpdateIndex yöntemini çağırarak dizini arama hizmetinizde ifade edebilirsiniz. Dizin ayrıca, belirtilen alanlarda otomatik tamamlamayı etkinleştirmek için bir SearchSuggester içerir.

// Create hotels-quickstart index
private static void CreateIndex(string indexName, SearchIndexClient searchIndexClient)
{
    FieldBuilder fieldBuilder = new FieldBuilder();
    var searchFields = fieldBuilder.Build(typeof(Hotel));

    var definition = new SearchIndex(indexName, searchFields);

    var suggester = new SearchSuggester("sg", new[] { "HotelName", "Category", "Address/City", "Address/StateProvince" });
    definition.Suggesters.Add(suggester);

    searchIndexClient.CreateOrUpdateIndex(definition);
}

Belgeleri dizine yükleme

Azure AI Search hizmette depolanan içerik üzerinde aramalar. Bu adımda, oluşturduğunuz otel dizinine uygun JSON belgelerini yüklersiniz.

Azure AI Search arama belgeleri, hem dizin oluşturma hem de sorgulardan alınan çıkışlar olan veri yapılarıdır. Dış veri kaynağından elde edilen belge girişleri veritabanındaki satırlar, Azure Blob Storage bloblar veya diskteki JSON belgeleri olabilir. Bu örnekte, doğrudan dört otel için bir kısayol alır ve JSON belgelerini eklersiniz.

Belgeleri karşıya yüklerken IndexDocumentsBatch nesnesi kullanmanız gerekir. IndexDocumentsBatch nesnesi, her biri bir belge içeren bir Actions koleksiyonunu barındırır ve bu eylemlerin her birinde, hangi işlemin gerçekleştirileceğini (yükleme, birleştirme, silme ve birleştirme veya yükleme) Azure AI Search'e bildiren bir özellik bulunur.

Program.cs içinde, belge ve dizin eylemleri dizisi oluşturur ve ardından bu diziyi IndexDocumentsBatch'e geçirirsiniz. Aşağıdaki belgeler, otel sınıfı tarafından tanımlanan hotels-quickstart dizinine uygundur.

// Upload documents in a single Upload request.
private static void UploadDocuments(SearchClient searchClient)
{
    IndexDocumentsBatch<Hotel> batch = IndexDocumentsBatch.Create(
        IndexDocumentsAction.Upload(
            new Hotel()
            {
                HotelId = "1",
                HotelName = "Stay-Kay City Hotel",
                Description = "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
                Category = "Boutique",
                Tags = new[] { "view", "air conditioning", "concierge" },
                ParkingIncluded = false,
                LastRenovationDate = new DateTimeOffset(2022, 1, 18, 0, 0, 0, TimeSpan.Zero),
                Rating = 3.6,
                Address = new Address()
                {
                    StreetAddress = "677 5th Ave",
                    City = "New York",
                    StateProvince = "NY",
                    PostalCode = "10022",
                    Country = "USA"
                }
            }),
        // REDACTED FOR BREVITY
}

UploadDocuments yöntemi bir IndexDocumentsBatch oluşturur ve belgeleri karşıya yüklemek için bir SearchClient üzerinde IndexDocuments çağırır. Bu hızlı başlangıç, aynı kimlik bilgilerini yeniden kullanan SearchClient kullanarak elde SearchIndexClient edilir.

SearchClient ingesterClient = searchIndexClient.GetSearchClient(indexName);

// Load documents
Console.WriteLine("{0}", "Uploading documents...\n");
UploadDocuments(ingesterClient);

Bu konsol uygulaması tüm komutları sırayla çalıştırdığından, kod dizin oluşturma ve sorgular arasında iki saniyelik bir bekleme süresi ekler.

// Wait 2 seconds for indexing to complete before starting queries (for demo and console-app purposes only)
Console.WriteLine("Waiting for indexing...\n");
System.Threading.Thread.Sleep(2000);

İki saniyelik gecikme, sorgular yürütülmeden önce tüm belgelerin dizine alınabilmesi için zaman uyumsuz olan dizin oluşturmayı telafi eder. Gecikmeli kodlama genellikle yalnızca tanıtımlarda, testlerde ve örnek uygulamalarda gereklidir.

Dizini sorgulama

İlk belge dizine alındıktan hemen sonra sorgu sonuçlarını alabilirsiniz, ancak dizininizin gerçek testi, tüm belgeler dizine alınana kadar beklemelidir.

Bu bölüm iki işlev parçası ekler: sorgu mantığı ve sonuçları. Sorgular için Search yöntemini kullanın. Bu yöntem arama metnini (sorgu dizesi) ve diğer seçenekleri alır.

SearchResults sınıfı sonuçları temsil eder.

Program.cs içindeki WriteDocuments yöntemi, arama sonuçlarını konsola yazdırır.

// Write search results to console
private static void WriteDocuments(SearchResults<Hotel> searchResults)
{
    foreach (SearchResult<Hotel> result in searchResults.GetResults())
    {
        Console.WriteLine(result.Document);
    }

    Console.WriteLine();
}

private static void WriteDocuments(AutocompleteResults autoResults)
{
    foreach (AutocompleteItem result in autoResults.Results)
    {
        Console.WriteLine(result.Text);
    }

    Console.WriteLine();
}

Sorgu örneği 1

RunQueries yöntemi sorguları yürütür ve sonuçları döndürür. Sonuçlar Otel nesneleridir. Bu örnek yöntem imzasını ve ilk sorguyu gösterir. Bu sorgu, belgeden Select seçilen alanları kullanarak sonucu oluşturmanızı sağlayan parametreyi gösterir.

// Run queries, use WriteDocuments to print output
private static void RunQueries(SearchClient searchClient)
{
    SearchOptions options;
    SearchResults<Hotel> response;
    
    // Query 1
    Console.WriteLine("Query #1: Search on empty term '*' to return all documents, showing a subset of fields...\n");

    options = new SearchOptions()
    {
        IncludeTotalCount = true,
        Filter = "",
        OrderBy = { "" }
    };

    options.Select.Add("HotelId");
    options.Select.Add("HotelName");
    options.Select.Add("Rating");

    response = searchClient.Search<Hotel>("*", options);
    WriteDocuments(response);
    // REDACTED FOR BREVITY
}

Sorgu örneği 2

İkinci sorguda terimi arayın, Rating'ın 4'ten büyük olduğu belgeleri belirleyen bir filtre ekleyin ve azalan düzende Rating sıralayın. Filtre, dizindeki IsFilterable alanları üzerinden değerlendirilen boole ifadesidir. Filtre sorguları değerleri içerir veya hariç tutar. Bu nedenle, filtre sorgusuyla ilişkilendirilmiş bir ilgi puanı yoktur.

// Query 2
Console.WriteLine("Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...\n");

options = new SearchOptions()
{
    Filter = "Rating gt 4",
    OrderBy = { "Rating desc" }
};

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Rating");

response = searchClient.Search<Hotel>("hotels", options);
WriteDocuments(response);

Sorgu örneği 3

Üçüncü sorgu, tam metin arama işleminin kapsamını belirli alanlara göre ayarlamak için kullanılan öğesini gösterir searchFields.

// Query 3
Console.WriteLine("Query #3: Limit search to specific fields (pool in Tags field)...\n");

options = new SearchOptions()
{
    SearchFields = { "Tags" }
};

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Tags");

response = searchClient.Search<Hotel>("pool", options);
WriteDocuments(response);

Sorgu örneği 4

Dördüncü sorgu, açılımlı bir gezinti yapısını yapılandırmak için kullanılabilen facets öğesini gösterir.

// Query 4
Console.WriteLine("Query #4: Facet on 'Category'...\n");

options = new SearchOptions()
{
    Filter = ""
};

options.Facets.Add("Category");

options.Select.Add("HotelId");
options.Select.Add("HotelName");
options.Select.Add("Category");

response = searchClient.Search<Hotel>("*", options);
WriteDocuments(response);

Sorgu örneği 5

Beşinci sorguda belirli bir belgeyi döndürür. Belge arama, sonuç kümesindeki bir OnClick olaya verilen tipik bir yanıttır.

// Query 5
Console.WriteLine("Query #5: Look up a specific document...\n");

Response<Hotel> lookupResponse;
lookupResponse = searchClient.GetDocument<Hotel>("3");

Console.WriteLine(lookupResponse.Value.HotelId);

Sorgu örneği 6

Son yapılan sorgu, dizinde tanımladığınız öneri sistemi ile ilişkili iki olası eşleşmeye 'sa' çözümleyen kısmi kullanıcı girişi simülasyonunu yaparak otomatik tamamlama işlevinin söz dizimini gösterir.

// Query 6
Console.WriteLine("Query #6: Call Autocomplete on HotelName...\n");

var autoresponse = searchClient.Autocomplete("sa", "sg");
WriteDocuments(autoresponse);

Sorguların özeti

Önceki sorgular sorguda terimleri eşleştirmenin birden çok yolunu gösterir: tam metin araması, filtreler ve otomatik tamamlama.

SearchClient.Search yöntemi tam metin araması ve filtreleri gerçekleştirir. searchText dizisinde bir arama sorgusu geçirebilirken, SearchOptions sınıfının Filter özelliğinde bir filtre ifadesi geçirebilirsiniz. Arama yapmadan filtreleme yapmak için, "*" yöntemi için searchText parametresine geçirin. Filtreleme olmadan arama yapmak için özellik Filter ayarsız bırakın veya hiç SearchOptions örneği geçirmeyin.

Bu hızlı başlangıçta, Java için Azure AI Search istemci kitaplığını kullanarak, anahtar sözcük araması olarak da bilinen tam metin araması yapmak için bir arama dizini oluşturur, yükler ve sorgularsınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-java-samples

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

    cd azure-search-java-samples/quickstart-keyword-search
code .

  3. src/main/java/azure/search/sample/App.java'da, searchServiceEndpoint yer tutucu değerini Get uç noktası içinde aldığınız URL ile değiştirin.

  4. Bağımlılıkları yükleyin.

    mvn clean dependency:copy-dependencies

    Derleme tamamlandığında, çıkışta hata görünmediğini doğrulayın.

  5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştır

Uygulamayı derleyin ve çalıştırın.

javac -d target/classes -cp "target/dependency/*" src/main/java/azure/search/sample/*.java
java -cp "target/classes;target/dependency/*" azure.search.sample.App

Çıktı

Çıkış aşağıdakine benzer olmalıdır:

Waiting for indexing...

Starting queries...

Query #1: Search on empty term '*' to return all documents, showing a subset of fields...

{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Address":{"City":"Atlanta"}}
{"HotelId":"2","HotelName":"Old Century Hotel","Address":{"City":"Sarasota"}}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Address":{"City":"San Antonio"}}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Address":{"City":"New York"}}

Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...

{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}

Query #3: Limit search to specific fields (pool in Tags field)...

{"HotelId":"2","HotelName":"Old Century Hotel","Tags":["pool","free wifi","concierge"]}

Query #4: Facet on 'Category'...

{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Category":"Suite"}
{"HotelId":"2","HotelName":"Old Century Hotel","Category":"Boutique"}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Category":"Boutique"}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Category":"Boutique"}

Query #5: Look up a specific document...

3

Query #6: Call Autocomplete on HotelName that starts with 's'...

stay
sublime

Complete.

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Arama istemcisi oluşturma
  2. Arama dizini oluşturma
  3. Belgeleri dizine yükleme
  4. Dizini sorgulama

Arama istemcisi oluşturma

içinde App.javaiki istemci oluşturursunuz:

Her iki istemci için de hizmet uç noktası ve kimlik doğrulaması için bir kimlik bilgisi gerekir. Bu hızlı başlangıçta, Microsoft Entra ID ile anahtarsız kimlik doğrulaması için DefaultAzureCredential kullanacaksınız.

Arama dizini oluşturma

Bu hızlı başlangıçta, otel verileriyle birlikte yükleyip sorgular yürütdüğünüz bir otel dizini oluşturacaksınız. Bu adımda, dizindeki alanları tanımlarsınız. Her alan tanımı, alanın nasıl kullanıldığını belirleyen bir ad, veri türü ve öznitelikler içerir.

Bu örnek, kolaylık ve okunabilirlik için SearchIndexClient sınıfının zaman uyumlu yöntemlerini kullanır. Ancak üretim senaryolarında, uygulamanızı ölçeklenebilir ve duyarlı tutmak için SearchIndexAsyncClient sınıfını kullanın.

Yapıları tanımlama

Bir otel belgesinin yapısını ve adresini tanımlamak için Hotel.java ve Address.java olmak üzere iki yardımcı sınıf oluşturursunuz. Sınıfı Hotel bir otel kimliği, ad, açıklama, kategori, etiketler, otopark, yenileme tarihi, derecelendirme ve adres için alanlar içerir. Address sınıfı sokak adresi, şehir, eyalet/il, posta kodu ve ülke/bölge alanlarını içerir.

azure-search-documents istemci kitaplığında, alan tanımlarını kolaylaştırmak için SearchableField ve SimpleField kullanabilirsiniz. Her ikisi de SearchField oluşturmak için alanlara veya yöntemlere uygulayabileceğiniz ek açıklamalardır:

  • SimpleField herhangi bir veri türü olabilir, her zaman aranamaz (tam metin arama sorguları için yoksayılır) ve alınabilir (gizli değildir). Diğer öznitelikler varsayılan olarak kapalıdır, ancak etkinleştirilebilir. SimpleField belge kimlikleri veya yalnızca filtrelerde, modellerde veya puanlama profillerinde kullanılan alanlar için kullanabilirsiniz. Bu durumda, belge kimliği gibi isKey = true senaryo için gerekli olan öznitelikleri uygulayın.
  • SearchableField bir dize olmalıdır ve her zaman aranabilir ve alınabilir. Diğer öznitelikler varsayılan olarak kapalıdır, ancak etkinleştirilebilir. Bu alan türü aranabilir olduğundan, eş anlamlıları ve çözümleyici özelliklerinin tam tamamlayıcısını destekler.

İster temel SearchField API'yi ister yardımcı modellerden birini kullanın, filtre, model ve sıralama özniteliklerini açıkça etkinleştirmeniz gerekir. Örneğin, önceki örnekte gösterildiği gibi isFilterable, isSortable ve isFacetable açıkça ilişkilendirilmelidir.

Arama dizinini oluşturma

içinde App.javabir SearchIndex nesnesi oluşturur ve ardından arama hizmetinizde dizini ifade etmek için createOrUpdateIndex yöntemini çağırırsınız. Dizin ayrıca, belirtilen alanlarda otomatik tamamlamayı etkinleştirmek için bir SearchSuggester içerir.

// Create Search Index for Hotel model
searchIndexClient.createOrUpdateIndex(
    new SearchIndex(indexName, SearchIndexClient.buildSearchFields(Hotel.class, null))
    .setSuggesters(new SearchSuggester("sg", Arrays.asList("HotelName"))));

Belgeleri dizine yükleme

Azure AI Search hizmette depolanan içerik üzerinde aramalar. Bu adımda, oluşturduğunuz otel dizinine uygun JSON belgelerini yüklersiniz.

Azure AI Search arama belgeleri, hem dizin oluşturma hem de sorgulardan alınan çıkışlar olan veri yapılarıdır. Dış veri kaynağından elde edilen belge girişleri veritabanındaki satırlar, Azure Blob Storage bloblar veya diskteki JSON belgeleri olabilir. Bu örnekte, doğrudan dört otel için bir kısayol alır ve JSON belgelerini eklersiniz.

Belgeleri karşıya yüklerken IndexDocumentsBatch nesnesi kullanmanız gerekir. IndexDocumentsBatch nesnesi, her biri bir belge ve Azure AI Search'ün hangi işlemi gerçekleştireceğini belirten bir özellik içeren, IndexActions koleksiyonu içerir (yükleme, birleştirme, silme ve birleştir veya yükle).

App.java içinde, belge ve dizin eylemleri dizisi oluşturur ve ardından bu diziyi IndexDocumentsBatch'e geçirirsiniz. Aşağıdaki belgeler, otel sınıfı tarafından tanımlanan hotels-quickstart dizinine uygundur.

private static void uploadDocuments(SearchClient searchClient)
{
    var hotelList = new ArrayList<Hotel>();

    var hotel = new Hotel();
    hotel.hotelId = "1";
    hotel.hotelName = "Stay-Kay City Hotel";
    hotel.description = "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
    hotel.category = "Boutique";
    hotel.tags = new String[] { "view", "air conditioning", "concierge" };
    hotel.parkingIncluded = false;
    hotel.lastRenovationDate = OffsetDateTime.of(LocalDateTime.of(LocalDate.of(2022, 1, 18), LocalTime.of(0, 0)), ZoneOffset.UTC);
    hotel.rating = 3.6;
    hotel.address = new Address();
    hotel.address.streetAddress = "677 5th Ave";
    hotel.address.city = "New York";
    hotel.address.stateProvince = "NY";
    hotel.address.postalCode = "10022";
    hotel.address.country = "USA";
    hotelList.add(hotel);
    
    // REDACTED FOR BREVITY

    var batch = new IndexDocumentsBatch<Hotel>();
    batch.addMergeOrUploadActions(hotelList);
    try
    {
        searchClient.indexDocuments(batch);
    }
    catch (Exception e)
    {
        e.printStackTrace();
        // If for some reason any documents are dropped during indexing, you can compensate by delaying and
        // retrying. This simple demo just logs failure and continues
        System.err.println("Failed to index some of the documents");
    }
}

uploadDocuments yöntemi bir IndexDocumentsBatch oluşturur ve belgeleri karşıya yüklemek için SearchClient üzerinde indexDocuments'ı çağırır. SearchClient, uç nokta ve kimlik bilgilerinin ayrı olarak yapılandırılması gereken SearchClientBuilder kullanılarak bağımsız olarak oluşturulur.

uploadDocuments(searchClient);

Bu konsol uygulaması tüm komutları sırayla çalıştırdığından, kod dizin oluşturma ve sorgular arasında iki saniyelik bir bekleme süresi ekler.

// Wait 2 seconds for indexing to complete before starting queries (for demo and console-app purposes only)
System.out.println("Waiting for indexing...\n");
try
{
    Thread.sleep(2000);
}
catch (InterruptedException e)
{
}

İki saniyelik gecikme, sorgular yürütülmeden önce tüm belgelerin dizine alınabilmesi için zaman uyumsuz olan dizin oluşturmayı telafi eder. Gecikmeli kodlama genellikle yalnızca tanıtımlarda, testlerde ve örnek uygulamalarda gereklidir.

Dizini sorgulama

İlk belge dizine alındıktan hemen sonra sorgu sonuçlarını alabilirsiniz, ancak dizininizin gerçek testi, tüm belgeler dizine alınana kadar beklemelidir.

Bu bölüm iki işlev parçası ekler: sorgu mantığı ve sonuçları. Sorgular için arama yöntemini kullanın. Bu yöntem arama metnini (sorgu dizesi) ve diğer seçenekleri alır.

SearchPagedIterable sınıfı sonuçları temsil eder.

App.java içindeki WriteDocuments yöntemi, arama sonuçlarını konsola yazdırır.

// Write search results to console
private static void WriteSearchResults(SearchPagedIterable searchResults)
{
    searchResults.iterator().forEachRemaining(result ->
    {
        Hotel hotel = result.getDocument(Hotel.class);
        System.out.println(hotel);
    });

    System.out.println();
}

// Write autocomplete results to console
private static void WriteAutocompleteResults(AutocompletePagedIterable autocompleteResults)
{
    autocompleteResults.iterator().forEachRemaining(result ->
    {
        String text = result.getText();
        System.out.println(text);
    });

    System.out.println();
}

Sorgu örneği 1

RunQueries yöntemi sorguları yürütür ve sonuçları döndürür. Sonuçlar Otel nesneleridir. Bu örnek yöntem imzasını ve ilk sorguyu gösterir. Bu sorgu, belgeden Select seçilen alanları kullanarak sonucu oluşturmanızı sağlayan parametreyi gösterir.

// Run queries, use WriteDocuments to print output
private static void RunQueries(SearchClient searchClient)
{
    // Query 1
    System.out.println("Query #1: Search on empty term '*' to return all documents, showing a subset of fields...\n");

    SearchOptions options = new SearchOptions();
    options.setIncludeTotalCount(true);
    options.setFilter("");
    options.setOrderBy("");
    options.setSelect("HotelId", "HotelName", "Address/City");

    WriteSearchResults(searchClient.search("*", options, Context.NONE));
}

Sorgu örneği 2

İkinci sorguda terimi arayın, Rating'ın 4'ten büyük olduğu belgeleri belirleyen bir filtre ekleyin ve azalan düzende Rating sıralayın. Filtre, dizindeki isFilterable alanları üzerinden değerlendirilen boole ifadesidir. Filtre sorguları değerleri içerir veya hariç tutar. Bu nedenle, filtre sorgusuyla ilişkilendirilmiş bir ilgi puanı yoktur.

// Query 2
System.out.println("Query #2: Search on 'hotels', filter on 'Rating gt 4', sort by Rating in descending order...\n");

options = new SearchOptions();
options.setFilter("Rating gt 4");
options.setOrderBy("Rating desc");
options.setSelect("HotelId", "HotelName", "Rating");

WriteSearchResults(searchClient.search("hotels", options, Context.NONE));

Sorgu örneği 3

Üçüncü sorgu, tam metin arama işleminin kapsamını belirli alanlara göre ayarlamak için kullanılan öğesini gösterir searchFields.

// Query 3
System.out.println("Query #3: Limit search to specific fields (pool in Tags field)...\n");

options = new SearchOptions();
options.setSearchFields("Tags");

options.setSelect("HotelId", "HotelName", "Tags");

WriteSearchResults(searchClient.search("pool", options, Context.NONE));

Sorgu örneği 4

Dördüncü sorgu, açılımlı bir gezinti yapısını yapılandırmak için kullanılabilen facets öğesini gösterir.

// Query 4
System.out.println("Query #4: Facet on 'Category'...\n");

options = new SearchOptions();
options.setFilter("");
options.setFacets("Category");
options.setSelect("HotelId", "HotelName", "Category");

WriteSearchResults(searchClient.search("*", options, Context.NONE));

Sorgu örneği 5

Beşinci sorguda belirli bir belgeyi döndürür. Belge arama, sonuç kümesindeki bir OnClick olaya verilen tipik bir yanıttır.

// Query 5
System.out.println("Query #5: Look up a specific document...\n");

Hotel lookupResponse = searchClient.getDocument("3", Hotel.class);
System.out.println(lookupResponse.hotelId);
System.out.println();

Sorgu örneği 6

Son sorgu, dizinde tanımladığınız önericiyle ilişkili olan, iki olası eşleşmeye çözümleyen s kısmi kullanıcı girişi simülasyonu yaparak otomatik tamamlama söz dizimini gösterir.

// Query 6
System.out.println("Query #6: Call Autocomplete on HotelName that starts with 's'...\n");

WriteAutocompleteResults(searchClient.autocomplete("s", "sg"));

Sorguların özeti

Önceki sorgular sorguda terimleri eşleştirmenin birden çok yolunu gösterir: tam metin araması, filtreler ve otomatik tamamlama.

SearchClient.search yöntemi tam metin araması ve filtreleri gerçekleştirir. searchText dizisinde bir arama sorgusu geçirebilirken, SearchOptions sınıfının filter özelliğinde bir filtre ifadesi geçirebilirsiniz. Arama yapmaksızın filtrelemek için, "*" yönteminin searchText parametresi olarak sadece geçirin. Filtreleme olmadan arama yapmak için özellik filter ayarsız bırakın veya hiç SearchOptions örneği geçirmeyin.

Bu hızlı başlangıçta, JavaScript için Azure AI Search istemci kitaplığını kullanarak, tam metin arama olarak da bilinen anahtar kelime araması için bir arama dizini oluşturacak, yükleyecek ve sorgulayacaksınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

    cd azure-search-javascript-samples/quickstart-keyword-search
code .

  3. sample.env'da, SEARCH_API_ENDPOINT yer tutucu değerini Get uç noktası içinde aldığınız URL ile değiştirin.

  4. sample.env öğesini .env olarak yeniden adlandırın.

    mv sample.env .env

  5. Bağımlılıkları yükleyin.

    npm install

    Yükleme tamamlandığında proje dizininde bir node_modules klasör görmeniz gerekir.

  6. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştır

Uygulamayı çalıştırın.

node index.js

Çıktı

Çıkış aşağıdakine benzer olmalıdır:

Running Azure AI Search Javascript quickstart...
Checking if index exists...
Deleting index...
Creating index...
Index named hotels-quickstart-js has been created.
Uploading documents...
Index operations succeeded: true
Querying the index...

Query #1 - search everything:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}
Result count: 4

Query #2 - search with filter, orderBy, and select:
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}

Query #3 - limit searchFields:
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}

Query #4 - limit searchFields and use facets:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}

Query #5 - Lookup document:
HotelId: 3; HotelName: Gastronomic Landscape Hotel

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Arama istemcisi oluşturma
  2. Arama dizini oluşturma
  3. Belgeleri dizine yükleme
  4. Dizini sorgulama

Arama istemcisi oluşturma

içinde index.jsiki istemci oluşturursunuz:

Her iki istemci için de hizmet uç noktası ve kimlik doğrulaması için bir kimlik bilgisi gerekir. Bu hızlı başlangıçta, Microsoft Entra ID ile anahtarsız kimlik doğrulaması için DefaultAzureCredential kullanacaksınız.

const credential = new DefaultAzureCredential();
const indexClient = new SearchIndexClient(endpoint, credential);

Arama dizini oluşturma

Bu hızlı başlangıçta, otel verileriyle birlikte yükleyip sorgular yürütdüğünüz bir otel dizini oluşturacaksınız. Bu adımda, bir JSON dosyasından dizin tanımını içeri aktaracak ve arama hizmetinizde dizini oluşturacaksınız.

Dosya hotels_quickstart_index.json , alanlar ve öznitelikleri de dahil olmak üzere dizin şemasını tanımlar. Her bir alan, bir name ile tanımlanır ve belirtilmiş bir type değerine sahiptir. Her alanın, Azure AI Search'ün bu alanda arama yapıp yapamayacağını, filtreleme, sıralama ve fasetleme işlemlerini gerçekleştirip gerçekleştiremeyeceğini belirten bir dizi dizin özniteliği vardır. Alanların çoğu basit veri türleridir, ancak bazıları gibi Address, dizininizde zengin veri yapıları oluşturmanıza olanak sağlayan karmaşık türlerdir. Dizin Oluşturma (REST) bölümünde açıklanan desteklenen veri türleri ve dizin öznitelikleri hakkında daha fazla bilgi edinebilirsiniz.

Aşağıdaki kod, ana işlevin dizin tanımına erişebilmesi için hotels_quickstart_index.json'i index.js'in üst kısmında import eder.

const indexDefinition = require('./hotels_quickstart_index.json');

Bu hızlı başlangıç, zaten varsa dizini siler. Bu, test/tanıtım kodu için yaygın bir uygulamadır. Aşağıdaki işlev dizini silmeye çalışır.

async function deleteIndexIfExists(indexClient, indexName) {
    try {
        await indexClient.deleteIndex(indexName);
        console.log('Deleting index...');
    } catch {
        console.log('Index does not exist yet.');
    }
}

Aşağıdaki kod, dizin tanımından dizin adını ayıklar ve indexName ile indexClient'i deleteIndexIfExists() işlevine geçirir.

const indexName = indexDefinition["name"];

console.log('Checking if index exists...');
await deleteIndexIfExists(indexClient, indexName);

Bundan sonra, createIndex() yöntemini kullanarak dizini oluşturursunuz.

console.log('Creating index...');
let index = await indexClient.createIndex(indexDefinition);

console.log(`Index named ${index.name} has been created.`);

Belgeleri dizine yükleme

Azure AI Search belgeler hem dizin oluşturmaya giriş hem de sorgulardan çıkışlar olan veri yapılarıdır. Bu tür verileri dizine gönderebilirsiniz veya dizin oluşturucu kullanabilirsiniz. Bu hızlı başlangıçta, belgeleri program aracılığıyla dizine gönderebilirsiniz.

Belge girişleri, bu hızlı başlangıçta olduğu gibi veritabanındaki satırlar, Azure Blob Storage bloblar veya diskteki JSON belgeleri olabilir. indexDefinition örneğine benzer şekilde, verileri ana işlevde erişilebilir hale getirmek için hotels.json öğesini index.js'in üst kısmında içeri aktarırsınız.

const hotelData = require('./hotels.json');

Verileri arama dizinine dizine almak için bir SearchClient oluşturursunuz. Dizin oluşturup yönetirken SearchIndexClient , SearchClient belgeleri karşıya yükler ve dizini sorgular.

Bu hızlı başlangıç, aynı kimlik bilgilerini yeniden kullanan SearchClient kullanılarak SearchIndexClient konumundan elde eder.

const searchClient = indexClient.getSearchClient(indexName);

Aşağıdaki kod, belgeleri, aynı anahtara sahip bir belge zaten varsa, bunları arama dizinine yükleyen veya mevcut bir belgeyle birleştiren mergeOrUploadDocuments() yöntemini kullanarak karşıya yükler.

console.log('Uploading documents...');
let indexDocumentsResult = await searchClient.mergeOrUploadDocuments(hotelData['value']);

console.log(`Index operations succeeded: ${JSON.stringify(indexDocumentsResult.results[0].succeeded)}`);

Dizini sorgulama

Bir dizin oluşturulduğunda ve belgeler karşıya yüklendiğinde, dizine sorgu göndermeye hazırsınız demektir. Bu bölüm, kullanabileceğiniz farklı sorgu işlevlerini göstermek için arama dizinine beş farklı sorgu gönderir.

Sorgular, main işlevinde adı verilen bir sendQueries() işlevde aşağıdaki gibi yazılır:

await sendQueries(searchClient);

search() yöntemi searchClient sorguları gönderir. İlk parametre arama metnidir ve ikinci parametre arama seçeneklerini belirtir.

Sorgu örneği 1

İlk sorgu, her şeyi aramaya eşdeğer olan * öğesini arar ve dizindeki üç alanı seçer. Gereksiz verilerin geri çekilmesi sorgularınıza gecikme süresi kazandırabileceğinden, yalnızca select ihtiyacınız olan alanları kullanmak en iyi yöntemdir.

searchOptions Bu sorgu için, eşleşen sonuç sayısını döndüren includeTotalCount, true olarak ayarlanmış.

async function sendQueries(searchClient) {
    console.log('Query #1 - search everything:');
    let searchOptions = {
        includeTotalCount: true,
        select: ["HotelId", "HotelName", "Rating"]
    };

    let searchResults = await searchClient.search("*", searchOptions);
    for await (const result of searchResults.results) {
        console.log(`${JSON.stringify(result.document)}`);
    }
    console.log(`Result count: ${searchResults.count}`);

    // remaining queries go here
}

Aşağıda belirtilen kalan sorguların da sendQueries() fonksiyonuna eklenmesi gerekmektedir. Okunabilirlik için burada ayrılmışlardır.

Sorgu örneği 2

Sonraki sorgu, arama terimini "wifi" belirtir ve yalnızca durumun değerine eşit olduğu sonuçları döndürmek için 'FL'bir filtre içerir. Sonuçlar ayrıca otelin Rating'e göre sıralanır. Filtre, bir dizindeki filtrelenebilir alanlar üzerinde değerlendirilen bir mantıksal ifadedir. Filtre sorguları değerleri içerir veya hariç tutar. Bu nedenle, filtre sorgusuyla ilişkilendirilmiş bir ilgi puanı yoktur.

console.log('Query #2 - Search with filter, orderBy, and select:');
let state = 'FL';
searchOptions = {
    filter: odata`Address/StateProvince eq ${state}`,
    orderBy: ["Rating desc"],
    select: ["HotelId", "HotelName", "Rating"]
};

searchResults = await searchClient.search("wifi", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Sorgu örneği 3

Üçüncü sorgu, searchFields parametresini kullanarak aramayı tek bir aranabilir alanla sınırlar. Bu yaklaşım, yalnızca belirli alanlardaki eşleşmelerle ilgilendiğinizi biliyorsanız sorgunuzu daha verimli hale getirmek için harika bir seçenektir.

console.log('Query #3 - Limit searchFields:');
searchOptions = {
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("sublime cliff", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Sorgu örneği 4

Sorguya dahil etmek için sık kullanılan bir diğer seçenek de 'dir facets. Modeller, kullanıcıların hangi değerlere filtre uygulayabileceklerini öğrenmesini kolaylaştırmak için kullanıcı arabiriminizde filtreler oluşturmanıza olanak tanır. Bu sorgu ayrıca aramayı HotelName alanıyla sınırlar.

console.log('Query #4 - limit searchFields and use facets:');
searchOptions = {
    facets: ["Category"],
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("*", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Sorgu örneği 5

Son sorgu, getDocument() öğesinin searchClient yöntemini kullanır. Bu, bir belgeyi anahtarına göre verimli bir şekilde almanıza olanak tanır.

console.log('Query #5 - Lookup document:');
let documentResult = await searchClient.getDocument(key='3')
console.log(`HotelId: ${documentResult.HotelId}; HotelName: ${documentResult.HotelName}`)

Sorguların özeti

Önceki sorgular, sorgudaki terimleri eşleştirmenin birden çok yolunu gösterir: tam metin araması, filtreler ve belge arama.

searchClient.search yöntemi tam metin araması ve filtreleri gerçekleştirir. Sınıfın searchText özelliğinde bir filtre ifadesi geçirirken filter dizesinde bir arama sorgusu geçirebilirsiniz. Arama yapmadan filtrelemek için "*" yönteminin searchText parametresi olarak search geçirin. Filtreleme olmadan arama yapmak için özellik filter ayarsız bırakın veya hiç SearchOptions örneği geçirmeyin.

Bu hızlı başlangıçta, Python için Azure AI Search istemci kitaplığını kullanarak anahtar sözcük araması olarak da bilinen full-text search arama dizinini oluşturur, yükler ve sorgularsınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-python-samples

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

    cd azure-search-python-samples/Quickstart-Keyword-Search
code .

  3. azure-search-quickstart.ipynb'ı açın.

  4. Ctrl+Shift+P tuşlarına basın, Not Defteri: Not Defteri Çekirdeği'ni seçin ve bir sanal ortam oluşturmak için istemleri izleyin.

    Tamamlandığında, proje dizininde bir .venv klasör görmeniz gerekir.

  5. Gerekli paketleri yüklemek için ilk kod hücresini çalıştırın.

  6. İkinci kod hücresinde, search_endpoint için yer tutucu değeri Uç nokta alma bölümünde aldığınız URL ile değiştirin ve hücreyi çalıştırın.

  7. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştır

Dizin oluşturmak, belgeleri karşıya yüklemek ve dizini sorgulamak için kalan kod hücrelerini sıralı olarak çalıştırın.

Çıktı

Her kod hücresi çıktısını not defterine yazdırır. Aşağıdaki örnek, dizindeki tüm belgeleri döndüren boş bir arama olan ilk sorgunun çıktısıdır.

Total Documents Matching Query: 4
1.0
Gastronomic Landscape Hotel
['restaurant', 'bar', 'continental breakfast']
Description: The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.
1.0
Old Century Hotel
['pool', 'free wifi', 'concierge']
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
1.0
Sublime Palace Hotel
['concierge', 'view', 'air conditioning']
Description: Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
1.0
Stay-Kay City Hotel
['view', 'air conditioning', 'concierge']
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. İstemcileri oluşturun
  2. Arama dizini oluşturma
  3. Belgeleri dizine yükleme
  4. Dizini sorgulama
  5. Dizini kaldırma

İstemcileri oluşturun

Not defteri iki istemci oluşturur:

Her iki istemci için de hizmet uç noktası ve kimlik bilgisi gerekir. Bu hızlı başlangıçta, Microsoft Entra ID ile anahtarsız kimlik doğrulaması için DefaultAzureCredential kullanacaksınız.

Arama dizini oluşturma

Bu hızlı başlangıçta, otel verileriyle birlikte yükleyip sorguları çalıştırdığınız bir otel dizini oluşturacaksınız. Bu adımda, dizindeki alanları tanımlarsınız. Her alan tanımı, alanın nasıl kullanıldığını belirleyen bir ad, veri türü ve öznitelikler içerir.

Dizüstü bilgisayar, şemayı tanımlamak için SimpleFieldSearchableField, ComplexField, ve kullanır. Dizin Oluşturma (REST) bölümünde açıklanan desteklenen veri türleri ve dizin öznitelikleri hakkında daha fazla bilgi edinebilirsiniz.

# Create a search schema
index_client = SearchIndexClient(
    endpoint=search_endpoint, credential=credential)
fields = [
        SimpleField(name="HotelId", type=SearchFieldDataType.String, key=True),
        SearchableField(name="HotelName", type=SearchFieldDataType.String, sortable=True),
        SearchableField(name="Description", type=SearchFieldDataType.String, analyzer_name="en.lucene"),
        SearchableField(name="Category", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),

        SearchableField(name="Tags", collection=True, type=SearchFieldDataType.String, facetable=True, filterable=True),

        SimpleField(name="ParkingIncluded", type=SearchFieldDataType.Boolean, facetable=True, filterable=True, sortable=True),
        SimpleField(name="LastRenovationDate", type=SearchFieldDataType.DateTimeOffset, facetable=True, filterable=True, sortable=True),
        SimpleField(name="Rating", type=SearchFieldDataType.Double, facetable=True, filterable=True, sortable=True),

        ComplexField(name="Address", fields=[
            SearchableField(name="StreetAddress", type=SearchFieldDataType.String),
            SearchableField(name="City", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            SearchableField(name="StateProvince", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            SearchableField(name="PostalCode", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
            SearchableField(name="Country", type=SearchFieldDataType.String, facetable=True, filterable=True, sortable=True),
        ])
    ]

scoring_profiles = []
suggester = [{'name': 'sg', 'source_fields': ['Tags', 'Address/City', 'Address/Country']}]

# Create the search index=
index = SearchIndex(name=index_name, fields=fields, suggesters=suggester, scoring_profiles=scoring_profiles)
result = index_client.create_or_update_index(index)
print(f' {result.name} created')

Belgeleri dizine yükleme

Azure AI Search hizmette depolanan içerik üzerinde aramalar. Bu adımda, oluşturduğunuz otel dizinine uygun JSON belgelerini yüklersiniz.

Azure AI Search belgeler hem dizin oluşturmaya giriş hem de sorgulardan çıkışlar olan veri yapılarıdır. Not defteri, bir belge yükünü otel verilerini içeren sözlüklerin listesi olarak tanımlar.

# Create a documents payload
documents = [
    {
    "@search.action": "upload",
    "HotelId": "1",
    "HotelName": "Stay-Kay City Hotel",
    "Description": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
    "Category": "Boutique",
    "Tags": [ "view", "air conditioning", "concierge" ],
    "ParkingIncluded": "false",
    "LastRenovationDate": "2020-01-18T00:00:00Z",
    "Rating": 3.60,
    "Address": {
        "StreetAddress": "677 5th Ave",
        "City": "New York",
        "StateProvince": "NY",
        "PostalCode": "10022",
        "Country": "USA"
        }
    },
    {
    "@search.action": "upload",
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique",
    "Tags": [ "pool", "free wifi", "concierge" ],
    "ParkingIncluded": "false",
    "LastRenovationDate": "2019-02-18T00:00:00Z",
    "Rating": 3.60,
    "Address": {
        "StreetAddress": "140 University Town Center Dr",
        "City": "Sarasota",
        "StateProvince": "FL",
        "PostalCode": "34243",
        "Country": "USA"
        }
    },
    {
    "@search.action": "upload",
    "HotelId": "3",
    "HotelName": "Gastronomic Landscape Hotel",
    "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
    "Category": "Suite",
    "Tags": [ "restaurant", "bar", "continental breakfast" ],
    "ParkingIncluded": "true",
    "LastRenovationDate": "2015-09-20T00:00:00Z",
    "Rating": 4.80,
    "Address": {
        "StreetAddress": "3393 Peachtree Rd",
        "City": "Atlanta",
        "StateProvince": "GA",
        "PostalCode": "30326",
        "Country": "USA"
        }
    },
    {
    "@search.action": "upload",
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.",
    "Category": "Boutique",
    "Tags": [ "concierge", "view", "air conditioning" ],
    "ParkingIncluded": "true",
    "LastRenovationDate": "2020-02-06T00:00:00Z",
    "Rating": 4.60,
    "Address": {
        "StreetAddress": "7400 San Pedro Ave",
        "City": "San Antonio",
        "StateProvince": "TX",
        "PostalCode": "78216",
        "Country": "USA"
        }
    }
]

upload_documents yöntemi, belgeleri dizine ekler, yoksa oluşturur veya varsa güncelleştirir.

search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

try:
    result = search_client.upload_documents(documents=documents)
    print("Upload of new document succeeded: {}".format(result[0].succeeded))
except Exception as ex:
    print (ex.message)

Dizini sorgulama

İlk belge dizine alındıktan hemen sonra sorgu sonuçlarını alabilirsiniz, ancak dizininizin gerçek testi, tüm belgeler dizine alınana kadar beklemelidir.

search Sorguları çalıştırmak için SearchClient yöntemini kullanın.

Not defterindeki örnek sorgular yaygın desenleri gösterir:

  • Boş arama: Gelişigüzel belgelerin sıralanmamış bir listesini (arama puanı = 1,0) döndüren bir boş arama () yürütür. Ölçüt olmadığından, tüm belgeler sonuçlara eklenir.

  • Terim araması: Arama ifadesine (search_text="wifi" tüm terimleri ekler. Bu sorgu, sonuçların yalnızca select parametresindeki alanları içerdiğini belirtir. Geri gelen alanları sınırlamak, kablo üzerinden geri gönderilen veri miktarını en aza indirir ve arama gecikme süresini azaltır.

  • Filtrelenmiş arama: Yalnızca derecelendirmesi dörtten büyük olan ve azalan düzende sıralanan otelleri döndüren bir filtre ifadesi ekler.

  • Alanlı arama: Sorgu yürütme kapsamını belirli alanlara ekler search_fields .

  • Fasetsiz arama: Arama sonuçlarında bulunan pozitif eşleşmeler için fasetler oluşturur. Sıfır eşleşme yok. Arama sonuçları "wifi" terimini içermiyorsa, "wifi" modelli gezinti yapısında görünmez.

  • Belge arama: Bir belgeyi anahtarına göre döndürür. Bir kullanıcı arama sonucunda bir öğe seçtiğinde detaylandırma sağlamak istiyorsanız bu işlem yararlıdır.

  • Otomatik Tamamlama: Kullanıcı arama kutusuna yazarken olası eşleşmeler sağlar. Otomatik Tamamlama, hangi alanların öneri istekleriyle olası eşleşmeler içerdiğini bilmek için bir öneri oluşturucu (sg) kullanır. Bu hızlı başlangıçta, bu alanlar , Tagsve Address/CityşeklindedirAddress/Country. Otomatik tamamlama benzetimi yapmak için "sa" harflerini kısmi dize olarak geçirin. autocomplete yöntemi SearchClient olası terim eşleşmelerini geri gönderir.

Dizini kaldırma

Bu dizinle işiniz bittiyse, kod hücresini Clean up çalıştırarak silebilirsiniz. Gereksiz dizinleri silmek, daha fazla hızlı başlangıç ve öğreticiye yer açar.

try:
    result = index_client.delete_index(index_name)
    print ('Index', index_name, 'Deleted')
except Exception as ex:
    print (ex)

Bu hızlı başlangıçta, anahtar sözcük araması olarak da bilinen full-text search için arama dizini oluşturmak, yüklemek ve sorgulamak için JavaScript (TypeScript ile uyumlu) için Azure AI Search istemci kitaplığını kullanacaksınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

    cd azure-search-javascript-samples/quickstart-keyword-search
code .

  3. sample.env'da, SEARCH_API_ENDPOINT yer tutucu değerini Get uç noktası içinde aldığınız URL ile değiştirin.

  4. sample.env öğesini .env olarak yeniden adlandırın.

    mv sample.env .env

  5. Bağımlılıkları yükleyin.

    npm install
npm install typescript @types/node --save-dev
npm pkg set type=module

    Yükleme tamamlandığında proje dizininde bir node_modules klasör görmeniz gerekir.

  6. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

Kodu çalıştır

Örnek kod varsayılan olarak JavaScript kullanır. Kodu TypeScript ile çalıştırmak için:

  1. adlı tsconfig.jsonbir dosya oluşturun ve ardından aşağıdaki kodu dosyaya yapıştırın.

    {
  "compilerOptions": {
    "module": "NodeNext",
    "target": "ES2022",
    "moduleResolution": "NodeNext",
    "skipLibCheck": true,
    "strict": true,
    "resolveJsonModule": true
  },
  "include": ["*.ts"],
  "exclude": ["node_modules"]
}

  2. dosyasını index.jsolarak yeniden adlandırın index.ts ve ardından içeriği aşağıdaki kodla değiştirin. Bu kod, CommonJS söz dizimini TypeScript derlemesi için gereken ES modülü içeri aktarmalarına dönüştürür.

    // Import from the @azure/search-documents library
import {
    SearchIndexClient,
    SearchClient,
    SearchFieldDataType,
    odata,
    SearchIndex
} from "@azure/search-documents";

// Import from the Azure Identity library
import { DefaultAzureCredential } from "@azure/identity";

// Importing the hotels sample data
import hotelData from './hotels.json' with { type: "json" };

// Load the .env file if it exists
import "dotenv/config";

// Defining the index definition
const indexDefinition: SearchIndex = {
	"name": "hotels-quickstart",
	"fields": [
		{
			"name": "HotelId",
			"type": "Edm.String" as SearchFieldDataType,
			"key": true,
			"filterable": true
		},
		{
			"name": "HotelName",
			"type": "Edm.String" as SearchFieldDataType,
			"searchable": true,
			"filterable": false,
			"sortable": true,
			"facetable": false
		},
		{
			"name": "Description",
			"type": "Edm.String" as SearchFieldDataType,
			"searchable": true,
			"filterable": false,
			"sortable": false,
			"facetable": false,
			"analyzerName": "en.lucene"
		},
		{
			"name": "Category",
			"type": "Edm.String" as SearchFieldDataType,
			"searchable": true,
			"filterable": true,
			"sortable": true,
			"facetable": true
		},
		{
			"name": "Tags",
			"type": "Collection(Edm.String)",
			"searchable": true,
			"filterable": true,
			"sortable": false,
			"facetable": true
		},
		{
			"name": "ParkingIncluded",
			"type": "Edm.Boolean",
			"filterable": true,
			"sortable": true,
			"facetable": true
		},
		{
			"name": "LastRenovationDate",
			"type": "Edm.DateTimeOffset",
			"filterable": true,
			"sortable": true,
			"facetable": true
		},
		{
			"name": "Rating",
			"type": "Edm.Double",
			"filterable": true,
			"sortable": true,
			"facetable": true
		},
		{
			"name": "Address",
			"type": "Edm.ComplexType",
			"fields": [
				{
					"name": "StreetAddress",
					"type": "Edm.String" as SearchFieldDataType,
					"filterable": false,
					"sortable": false,
					"facetable": false,
					"searchable": true
				},
				{
					"name": "City",
					"type": "Edm.String" as SearchFieldDataType,
					"searchable": true,
					"filterable": true,
					"sortable": true,
					"facetable": true
				},
				{
					"name": "StateProvince",
					"type": "Edm.String" as SearchFieldDataType,
					"searchable": true,
					"filterable": true,
					"sortable": true,
					"facetable": true
				},
				{
					"name": "PostalCode",
					"type": "Edm.String" as SearchFieldDataType,
					"searchable": true,
					"filterable": true,
					"sortable": true,
					"facetable": true
				},
				{
					"name": "Country",
					"type": "Edm.String" as SearchFieldDataType,
					"searchable": true,
					"filterable": true,
					"sortable": true,
					"facetable": true
				}
			]
		}
	],
	"suggesters": [
		{
			"name": "sg",
			"searchMode": "analyzingInfixMatching",
			"sourceFields": [
				"HotelName"
			]
		}
	]
};

async function main() {

	// Your search service endpoint (from .env file)
	const searchServiceEndpoint = process.env.SEARCH_API_ENDPOINT || "";

	// Use the recommended keyless credential instead of the AzureKeyCredential credential.
	const credential = new DefaultAzureCredential();
	//const credential = new AzureKeyCredential(Your search service admin key);

	// Create a SearchIndexClient to send create/delete index commands
	const searchIndexClient: SearchIndexClient = new SearchIndexClient(
		searchServiceEndpoint,
		credential
	);

	// Creating a search client to upload documents and issue queries
	const indexName: string  = "hotels-quickstart";
    const searchClient: SearchClient<any> = searchIndexClient.getSearchClient(indexName);

    console.log('Checking if index exists...');
    await deleteIndexIfExists(searchIndexClient, indexName);

    console.log('Creating index...');
    let index: SearchIndex = await searchIndexClient.createIndex(indexDefinition);
    console.log(`Index named ${index.name} has been created.`);

    console.log('Uploading documents...');
    let indexDocumentsResult = await searchClient.mergeOrUploadDocuments(hotelData['value']);
    console.log(`Index operations succeeded: ${JSON.stringify(indexDocumentsResult.results[0].succeeded)} `);

    // waiting one second for indexing to complete (for demo purposes only)
    await sleep(1000);

    console.log('Querying the index...');
    console.log();
    await sendQueries(searchClient);
}

async function deleteIndexIfExists(searchIndexClient: SearchIndexClient, indexName: string) {
    try {
        await searchIndexClient.deleteIndex(indexName);
        console.log('Deleting index...');
    } catch {
        console.log('Index does not exist yet.');
    }
}

async function sendQueries(searchClient: SearchClient<any>) {
    // Query 1
    console.log('Query #1 - search everything:');
    let searchOptions: any = {
        includeTotalCount: true,
        select: ["HotelId", "HotelName", "Rating"]
    };

    let searchResults = await searchClient.search("*", searchOptions);
    for await (const result of searchResults.results) {
        console.log(`${JSON.stringify(result.document)}`);
    }
    console.log(`Result count: ${searchResults.count}`);
    console.log();


    // Query 2
    console.log('Query #2 - search with filter, orderBy, and select:');
    let state = 'FL';
    searchOptions = {
        filter: odata`Address/StateProvince eq ${state}`,
        orderBy: ["Rating desc"],
        select: ["HotelId", "HotelName", "Rating"]
    };

    searchResults = await searchClient.search("wifi", searchOptions);
    for await (const result of searchResults.results) {
        console.log(`${JSON.stringify(result.document)}`);
    }
    console.log();

    // Query 3
    console.log('Query #3 - limit searchFields:');
    searchOptions = {
        select: ["HotelId", "HotelName", "Rating"],
        searchFields: ["HotelName"]
    };

    searchResults = await searchClient.search("sublime palace", searchOptions);
    for await (const result of searchResults.results) {
        console.log(`${JSON.stringify(result.document)}`);
    }
    console.log();

    // Query 4
    console.log('Query #4 - limit searchFields and use facets:');
    searchOptions = {
        facets: ["Category"],
        select: ["HotelId", "HotelName", "Rating"],
        searchFields: ["HotelName"]
    };

    searchResults = await searchClient.search("*", searchOptions);
    for await (const result of searchResults.results) {
        console.log(`${JSON.stringify(result.document)}`);
    }
    console.log();

    // Query 5
    console.log('Query #5 - Lookup document:');
    let documentResult = await searchClient.getDocument('3');
    console.log(`HotelId: ${documentResult.HotelId}; HotelName: ${documentResult.HotelName}`);
    console.log();
}

function sleep(ms: number) {
    return new Promise(resolve => setTimeout(resolve, ms));
}

main().catch((err) => {
    console.error("The sample encountered an error:", err);
});

  3. TypeScript'ten JavaScript'e dönüştürme.

    npx tsc

  4. Uygulamayı çalıştırın.

    node index.js

Çıktı

Çıkış aşağıdakine benzer olmalıdır:

Checking if index exists...
Deleting index...
Creating index...
Index named hotels-quickstart has been created.
Uploading documents...
Index operations succeeded: true 
Querying the index...

Query #1 - search everything:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}
Result count: 4

Query #2 - search with filter, orderBy, and select:
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}

Query #3 - limit searchFields:
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}

Query #4 - limit searchFields and use facets:
{"HotelId":"3","HotelName":"Gastronomic Landscape Hotel","Rating":4.8}
{"HotelId":"2","HotelName":"Old Century Hotel","Rating":3.6}
{"HotelId":"4","HotelName":"Sublime Palace Hotel","Rating":4.6}
{"HotelId":"1","HotelName":"Stay-Kay City Hotel","Rating":3.6}

Query #5 - Lookup document:
HotelId: 3; HotelName: Gastronomic Landscape Hotel

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Arama istemcisi oluşturma
  2. Arama dizini oluşturma
  3. Belgeleri dizine yükleme
  4. Dizini sorgulama

Arama istemcisi oluşturma

içinde index.tsiki istemci oluşturursunuz:

Her iki istemci için de hizmet uç noktası ve kimlik doğrulaması için bir kimlik bilgisi gerekir. Bu hızlı başlangıçta, Microsoft Entra ID ile anahtarsız kimlik doğrulaması için DefaultAzureCredential kullanacaksınız.

const credential = new DefaultAzureCredential();
const searchIndexClient: SearchIndexClient = new SearchIndexClient(
    searchServiceEndpoint,
    credential
);

Arama dizini oluşturma

Bu hızlı başlangıçta, otel verileriyle birlikte yükleyip sorgular yürütdüğünüz bir otel dizini oluşturacaksınız. Bu adımda, dizindeki alanları tanımlarsınız.

indexDefinition nesnesi, Azure AI Search sonraki adımda yüklediğiniz belgelerle nasıl çalıştığını tanımlar. Her bir alan, bir name ile tanımlanır ve belirtilmiş bir type değerine sahiptir. Her bir alan, Azure AI Search tarafından alanda arama, filtreleme, sıralama ve faceting işlemleri yapılıp yapılamayacağını belirleyen bir dizi dizin özniteliğine sahiptir. Alanların çoğu basit veri türleridir, ancak bazıları gibi Address, dizininizde zengin veri yapıları oluşturmanıza olanak sağlayan karmaşık türlerdir. Dizin Oluşturma (REST) bölümünde açıklanan desteklenen veri türleri ve dizin öznitelikleri hakkında daha fazla bilgi edinebilirsiniz.

const indexDefinition: SearchIndex = {
    "name": "hotels-quickstart",
    "fields": [
        {
            "name": "HotelId",
            "type": "Edm.String" as SearchFieldDataType,
            "key": true,
            "filterable": true
        },
        {
            "name": "HotelName",
            "type": "Edm.String" as SearchFieldDataType,
            "searchable": true,
            "filterable": false,
            "sortable": true,
            "facetable": false
        },
        // REDACTED FOR BREVITY
    ],
    "suggesters": [
        {
            "name": "sg",
            "searchMode": "analyzingInfixMatching",
            "sourceFields": ["HotelName"]
        }
    ]
};

Bu hızlı başlangıç, zaten varsa dizini siler. Bu, test/tanıtım kodu için yaygın bir uygulamadır.

async function deleteIndexIfExists(searchIndexClient: SearchIndexClient, indexName: string) {
    try {
        await searchIndexClient.deleteIndex(indexName);
        console.log('Deleting index...');
    } catch {
        console.log('Index does not exist yet.');
    }
}

Bundan sonra, dizin createIndex() yöntemiyle oluşturulur.

let index: SearchIndex = await searchIndexClient.createIndex(indexDefinition);

Belgeleri dizine yükleme

Azure AI Search belgeler hem dizin oluşturmaya giriş hem de sorgulardan çıkışlar olan veri yapılarıdır. Bu tür verileri dizine gönderebilirsiniz veya dizin oluşturucu kullanabilirsiniz. Bu hızlı başlangıçta, belgeleri program aracılığıyla dizine gönderebilirsiniz.

Belge girişleri, bu hızlı başlangıçta olduğu gibi veritabanındaki satırlar, Azure Blob Storage bloblar veya diskteki JSON belgeleri olabilir. Otel verileri dosyanın en üstünde içeri aktarılır.

import hotelData from './hotels.json' with { type: "json" };

Verileri arama dizinine dizine almak için bir SearchClient oluşturursunuz. Dizin oluşturup yönetirken SearchIndexClient , SearchClient belgeleri karşıya yükler ve dizini sorgular.

Bu hızlı başlangıç, aynı kimlik bilgilerini yeniden kullanan SearchClient kullanılarak SearchIndexClient konumundan elde eder.

const searchClient: SearchClient<any> = searchIndexClient.getSearchClient(indexName);

Yöntemi, mergeOrUploadDocuments() aynı anahtara sahip bir belge zaten varsa belgeleri yükler veya belgeleri varolan bir belgeyle birleştirir.

let indexDocumentsResult = await searchClient.mergeOrUploadDocuments(hotelData['value']);

Dizini sorgulama

Bir dizin oluşturulduğunda ve belgeler karşıya yüklendiğinde, dizine sorgu göndermeye hazırsınız demektir. Bu bölüm, kullanabileceğiniz farklı sorgu işlevlerini göstermek için arama dizinine beş farklı sorgu gönderir.

Sorgular, ana işlevde çağrılan bir sendQueries() işlevde yazılır.

await sendQueries(searchClient);

Sorgular, search() yöntemi kullanılarak searchClient gönderilir. İlk parametre arama metnidir ve ikinci parametre arama seçeneklerini belirtir.

Sorgu örneği 1

İlk sorgu, her şeyi aramaya eşdeğer olan * arar ve dizindeki üç alanı seçer. Gereksiz verilerin geri çekilmesi sorgularınıza gecikme süresi kazandırabileceğinden, yalnızca select ihtiyacınız olan alanları kullanmak en iyi yöntemdir.

searchOptions Bu sorgu için, eşleşen sonuç sayısını döndüren includeTotalCount, true olarak ayarlanmış.

console.log('Query #1 - search everything:');
let searchOptions: any = {
    includeTotalCount: true,
    select: ["HotelId", "HotelName", "Rating"]
};

let searchResults = await searchClient.search("*", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}
console.log(`Result count: ${searchResults.count}`);

Sorgu örneği 2

Sonraki sorguda, arama terimi "wifi", 'FL' bir filtreyle belirtilerek yalnızca durum 'FL''e eşit olduğunda sonuç döndürülür. Sonuçlar ayrıca otelin Rating'e göre sıralanır.

console.log('Query #2 - search with filter, orderBy, and select:');
let state = 'FL';
searchOptions = {
    filter: odata`Address/StateProvince eq ${state}`,
    orderBy: ["Rating desc"],
    select: ["HotelId", "HotelName", "Rating"]
};

searchResults = await searchClient.search("wifi", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Sorgu örneği 3

Arama, parametresi kullanılarak tek bir aranabilir alanla searchFields sınırlıdır. Bu yaklaşım, yalnızca belirli alanlardaki eşleşmelerle ilgilendiğinizi biliyorsanız sorgunuzu daha verimli hale getirmek için harika bir seçenektir.

console.log('Query #3 - limit searchFields:');
searchOptions = {
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("sublime palace", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Sorgu örneği 4

Sorguya dahil etmek için sık kullanılan bir diğer seçenek de 'dir facets. Fasetler, kullanıcıların kendi kendine kullanıcı arabiriminizdeki sonuçlardan detaylı arama yapma imkanı sağlar. Faset sonuçları, sonuç bölmesinde onay kutularına dönüştürülebilir.

console.log('Query #4 - limit searchFields and use facets:');
searchOptions = {
    facets: ["Category"],
    select: ["HotelId", "HotelName", "Rating"],
    searchFields: ["HotelName"]
};

searchResults = await searchClient.search("*", searchOptions);
for await (const result of searchResults.results) {
    console.log(`${JSON.stringify(result.document)}`);
}

Sorgu örneği 5

Son sorgu, getDocument() öğesinin searchClient yöntemini kullanır. Bu, bir belgeyi anahtarına göre verimli bir şekilde almanıza olanak tanır.

console.log('Query #5 - Lookup document:');
let documentResult = await searchClient.getDocument('3');
console.log(`HotelId: ${documentResult.HotelId}; HotelName: ${documentResult.HotelName}`);

Sorguların özeti

Önceki sorgular, sorgudaki terimleri eşleştirmenin birden çok yolunu gösterir: tam metin araması, filtreler ve belge arama.

searchClient.search yöntemi tam metin araması ve filtreleri gerçekleştirir. Sınıfın searchText özelliğinde bir filtre ifadesi geçirirken filter dizesinde bir arama sorgusu geçirebilirsiniz. Arama yapmadan filtrelemek için "*" yönteminin searchText parametresi olarak search geçirin. Filtreleme olmadan arama yapmak için özellik filter ayarsız bırakın veya hiç SearchOptions örneği geçirmeyin.

Bu hızlı başlangıçta Azure AI Search REST API'lerini kullanarak anahtar sözcük arama olarak da bilinen full-text search için arama dizini oluşturur, yükler ve sorgularsınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-rest-samples

  2. Hızlı başlangıç klasörüne gidin ve Visual Studio Code açın.

    cd azure-search-rest-samples/Quickstart-keyword-search
code .

  3. az-search-quickstart.rest'da, @baseUrl yer tutucu değerini Get uç noktası içinde aldığınız URL ile değiştirin.

  4. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

  5. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için bir erişim belirteci oluşturun.

    az account get-access-token --scope https://search.azure.com/.default --query accessToken -o tsv

  6. için @token yer tutucu değerini önceki adımdaki belirteçle değiştirin.

Kodu çalıştır

  1. bağlantınızı doğrulamak için altında ### List existing indexes by nameİstek Gönder'i seçin.

    Bir yanıt bitişik bir bölmede görünmelidir. Mevcut dizinleriniz varsa, bunlar listelenir. Aksi takdirde, liste boş olur. HTTP kodu ise 200 OKdevam etmeye hazırsınız demektir.

  2. Dizin oluşturmak, belgeleri karşıya yüklemek ve dizini sorgulamak için kalan istekleri sırayla gönderin.

Çıktı

Her istek, işleme göre farklı JSON döndürür. Anahtar çıktı, ### Run a query öğesinden gelir ve aşağıdakine benzer şekilde görünmelidir:

{
  "value": [
    {
      "@search.score": 0.5575875,
      "HotelId": "3",
      "HotelName": "Gastronomic Landscape Hotel",
      "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
      "Tags": [
        "restaurant",
        "bar",
        "continental breakfast"
      ]
    }
  ]
}

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Arama dizini oluşturma
  2. Belgeleri dizine yükleme
  3. Dizini sorgulama

Arama dizini oluşturma

Azure AI Search içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir. Dizin kavramsal olarak ilişkisel veritabanındaki tabloya benzer, ancak tam metin araması gibi arama işlemleri için özel olarak tasarlanmıştır.

Bu hızlı başlangıçta Dizinler - Oluştur (REST API) çağrısı yapılarak arama hizmetinizde adlı hotels-quickstart bir arama dizini ve bu dizinin fiziksel veri yapıları oluşturulur.

Dizin şemasında fields koleksiyon, otel belgelerinin yapısını tanımlar. Her alanın dizin oluşturma ve sorgular sırasında davranışını belirleyen bir name, verileri typeve öznitelikleri vardır. HotelId alanı anahtar olarak işaretlenir ve Azure AI Search dizindeki her belgeyi benzersiz olarak tanımlaması gerekir.

### Create a new index
POST {{baseUrl}}/indexes?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "name": "hotels-quickstart",  
    "fields": [
        {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
        {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
        {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
        {"name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
        {"name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "sortable": false, "facetable": true},
        {"name": "ParkingIncluded", "type": "Edm.Boolean", "filterable": true, "sortable": true, "facetable": true},
        {"name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Rating", "type": "Edm.Double", "filterable": true, "sortable": true, "facetable": true},
        {"name": "Address", "type": "Edm.ComplexType", 
            "fields": [
            {"name": "StreetAddress", "type": "Edm.String", "filterable": false, "sortable": false, "facetable": false, "searchable": true},
            {"name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true},
            {"name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "facetable": true}
            ]
        }
    ]
}

Dizin şemasıyla ilgili önemli noktalar:

  • Sayısal verileri tam metin aranabilir hale getirmek için dize alanlarını (Edm.String) kullanın. gibi Edm.Int32 filtrelenebilir, sıralanabilir, modellenebilir ve alınabilir ancak aranamaz.

  • Alanların çoğu basit veri türleridir, ancak alan gibi Address iç içe verileri temsil etmek için karmaşık türler tanımlayabilirsiniz.

  • Alan öznitelikleri izin verilen eylemleri belirler. REST API'leri varsayılan olarak birçok eyleme izin verir. Örneğin, tüm dizeler aranabilir ve alınabilir. REST API'lerinde öznitelikleri yalnızca bir davranışı devre dışı bırakmanız gerekiyorsa kullanabilirsiniz.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure AI Search'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta satır içi JSON olarak örnek otel belgeleri sağlanır. Ancak üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

Bu hızlı başlangıçta, dizininize dört örnek otel belgesi eklemek için Belgeler - Dizin (REST API) çağrısı yapılır. Önceki istekle karşılaştırıldığında, URI docs koleksiyonu ve index işlemini içerecek şekilde genişletilir.

Dizideki value her belge bir oteli temsil eder ve dizin şemasıyla eşleşen alanlar içerir. @search.action parametresi, her belge için gerçekleştirilecek işlemi belirtir. Bu örnekte, eğer belge yoksa belgeyi ekleyen veya varsa belgeyi güncelleyen upload kullanılır.

### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "value": [
        {
            "@search.action": "upload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.",
            "Category": "Boutique",
            "Tags": [ "view", "air conditioning", "concierge" ],
            "ParkingIncluded": false,
            "LastRenovationDate": "2022-01-18T00:00:00Z",
            "Rating": 3.60,
            "Address": 
            {
                "StreetAddress": "677 5th Ave",
                "City": "New York",
                "StateProvince": "NY",
                "PostalCode": "10022",
                "Country": "USA"
            } 
        },
        {
            "@search.action": "upload",
            "HotelId": "2",
            "HotelName": "Old Century Hotel",
            "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
            "Category": "Boutique",
            "Tags": [ "pool", "free wifi", "concierge" ],
            "ParkingIncluded": false,
            "LastRenovationDate": "2019-02-18T00:00:00Z",
            "Rating": 3.60,
            "Address": 
            {
                "StreetAddress": "140 University Town Center Dr",
                "City": "Sarasota",
                "StateProvince": "FL",
                "PostalCode": "34243",
                "Country": "USA"
            } 
        },
        {
            "@search.action": "upload",
            "HotelId": "3",
            "HotelName": "Gastronomic Landscape Hotel",
            "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
            "Category": "Suite",
            "Tags": [ "restaurant", "bar", "continental breakfast" ],
            "ParkingIncluded": true,
            "LastRenovationDate": "2015-09-20T00:00:00Z",
            "Rating": 4.80,
            "Address": 
            {
                "StreetAddress": "3393 Peachtree Rd",
                "City": "Atlanta",
                "StateProvince": "GA",
                "PostalCode": "30326",
                "Country": "USA"
            } 
        },
        {
            "@search.action": "upload",
            "HotelId": "4",
            "HotelName": "Sublime Palace Hotel",
            "Description": "Sublime Palace Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.",
            "Tags": [ "concierge", "view", "air conditioning" ],
            "ParkingIncluded": true,
            "LastRenovationDate": "2020-02-06T00:00:00Z",
            "Rating": 4.60,
            "Address": 
            {
                "StreetAddress": "7400 San Pedro Ave",
                "City": "San Antonio",
                "StateProvince": "TX",
                "PostalCode": "78216",
                "Country": "USA"
            }
        }
    ]
}

Dizini sorgulama

Artık belgeler dizininize yüklendiğinden, alanları içinde belirli terimleri veya tümcecikleri bulmak için tam metin aramasını kullanabilirsiniz.

Bu hızlı başlangıçta arama ölçütlerinize uyan otel belgelerini bulmak için Belgeler - Arama Gönderisi (REST API) çağrısı yapılır. URI artık /docs/search işlemini hedefliyor.

Tam metin arama istekleri her zaman sorgu metnini içeren bir search parametre içerir. Sorgu metni bir veya daha fazla terim, tümcecik veya işleç içerebilir. 'a searchek olarak, arama davranışını ve sonuçlarını daraltmak için başka parametreler belirtebilirsiniz.

Sorgu, her otel belgesinin Description ve Tags alanlarında "bağlı restoran" terimlerini arar. parametresi, yanıtta döndürülen alanları select, HotelId, HotelName, Tags, ve Description ile sınırlar. parametresi eşleşen count belgelerin toplam sayısını istemektedir.

### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version={{api-version}}  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{token}}

{
    "search": "attached restaurant",
    "select": "HotelId, HotelName, Tags, Description",
    "searchFields": "Description, Tags",
    "count": true
}

Bu hızlı başlangıçta powershell ve Azure AI Search REST API'lerini kullanarak anahtar sözcük arama olarak da bilinen full-text araması arama dizinini oluşturur, yükler ve sorgularsınız.

Tam metin araması dizin oluşturma ve sorgular için Apache Lucene ve sonuçları puanlama için BM25 derecelendirme algoritmasını kullanır. Bu hızlı başlangıçta dizini doldurmak için azure-search-sample-data GitHub deposundaki kurgusal otel verileri kullanılmaktadır.

İpucu

Hemen başlamak ister misiniz? GitHub source kodunu indirin.

Önkoşullar

Erişimi yapılandırma

Başlamadan önce, Azure AI Search'daki içeriğe ve işlemlere erişim izinlerinizin olduğundan emin olun. Bu hızlı başlangıçta kimlik doğrulaması için Microsoft Entra ID ve yetkilendirme için rol tabanlı erişim kullanılır. Rolleri atamak için Sahip veya Kullanıcı Erişimi Yöneticisi olmanız gerekir. Roller uygun değilse bunun yerine anahtar tabanlı kimlik doğrulamayı kullanın.

Önerilen rol tabanlı erişimi yapılandırmak için:

  1. Arama hizmetiniz için rol tabanlı erişimi etkinleştirin.

  2. Kullanıcı hesabınıza aşağıdaki rolleri atayın .

    • Arama Hizmeti Katkıda Bulunanı

    • Arama Dizini Veri Katkısı Sağlayan

    • Arama Dizini Veri Okuyucusu

Uç noktayı alma

Her Azure AI Search hizmetinin bir endpoint vardır. Bu, hizmeti tanımlayan ve hizmete ağ erişimi sağlayan benzersiz bir URL'dir. Sonraki bir bölümde, arama hizmetinize program aracılığıyla bağlanmak için bu uç noktayı belirtirsiniz.

Uç noktayı almak için:

  1. Azure portalında oturum açın ve arama hizmetinizi seçin.

  2. Sol bölmeden Genel Bakış'ı seçin.

  3. https://my-service.search.windows.net gibi görünmesi gereken uç noktayı not edin.

Ortamı ayarlama

  1. Örnek depoyu kopyalamak için Git'i kullanın.

    git clone https://github.com/Azure-Samples/azure-search-powershell-samples

  2. Hızlı başlangıç klasörüne gidin.

    cd azure-search-powershell-samples/Quickstart

  3. Microsoft Entra ID ile anahtarsız kimlik doğrulaması için Azure hesabınızda oturum açın. Birden çok aboneliğiniz varsa, Azure AI Search hizmetinizi içeren aboneliği seçin.

    az login

  4. azure-search-quickstart.ps1'da, $baseUrl yer tutucu değerini Get uç noktası içinde aldığınız URL ile değiştirin.

Kodu çalıştır

Aynı terminalde, bu hızlı başlangıcı yürütmek için aşağıdaki PowerShell betiğini çalıştırın.

.\azure-search-quickstart.ps1

Çıktı

Betik mevcut tüm dizinleri siler, yeni bir dizin oluşturur, belgeleri karşıya yükler ve birden çok tam metin arama sorgusu çalıştırır. Çıkış, her işlem için tam HTTP isteklerini ve yanıtlarını gösterir. Aşağıdaki örnekte "restoran wifi" araması yaparken verilen yanıt gösterilmektedir.

{
  "value": [
    {
      "@search.score": 0.6931472,
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
      "Tags": ["pool", "free wifi", "concierge"]
    },
    {
      "@search.score": 0.5575875,
      "HotelName": "Gastronomic Landscape Hotel",
      "Description": "The Gastronomic Hotel stands out for its culinary excellence under the management of William Dough, who advises on and oversees all of the Hotel's restaurant services.",
      "Tags": ["restaurant", "bar", "continental breakfast"]
    }
  ]
}

Kodu anlama

Uyarı

Bu bölümdeki kod parçacıkları okunabilirlik için değiştirilmiş olabilir. Tam bir çalışma örneği için kaynak koduna bakın.

Artık kodu çalıştırdığınıza göre, temel adımları ayıralım:

  1. Arama dizini oluşturma
  2. Belgeleri dizine yükleme
  3. Dizini sorgulama

Arama dizini oluşturma

Azure AI Search içerik eklemeden önce, içeriğin nasıl depolandığını ve yapılandırıldığını tanımlamak için bir dizin oluşturmanız gerekir. Dizin kavramsal olarak ilişkisel veritabanındaki tabloya benzer, ancak tam metin araması gibi arama işlemleri için özel olarak tasarlanmıştır.

Bu hızlı başlangıçta ilk olarak aynı ada sahip tüm mevcut dizinler silinir. Bu, tekrar tekrar çalışan test/tanıtım kodu için yaygın bir uygulamadır.

Send-Request DELETE "$baseUrl/indexes/hotels-quickstart?api-version=2025-09-01" $headers

Bu hızlı başlangıçta, arama hizmetinizde bir arama dizini ve fiziksel veri yapıları oluşturmak için Dizinler - Oluştur (REST API) çağrısı yapılır.

$body = @"
{
    "name": "hotels-quickstart",
    "fields": [
        {"name": "HotelId", "type": "Edm.String", "key": true, "filterable": true},
        {"name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": true, "facetable": false},
        {"name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false, "analyzer": "en.lucene"},
        ...
    ]
}
"@

Send-RequestWithBody POST "$baseUrl/indexes?api-version=2025-09-01" $headers $body

Dizin şemasında fields koleksiyon, otel belgelerinin yapısını tanımlar. Her alanın dizin oluşturma ve sorgular sırasında davranışını belirleyen bir name, verileri typeve öznitelikleri vardır. HotelId alanı anahtar olarak işaretlenir ve Azure AI Search dizindeki her belgeyi benzersiz olarak tanımlaması gerekir.

Dizin şemasıyla ilgili önemli noktalar:

  • Sayısal verileri tam metin aranabilir hale getirmek için dize alanlarını (Edm.String) kullanın. gibi Edm.Int32 filtrelenebilir, sıralanabilir, modellenebilir ve alınabilir ancak aranamaz.

  • Alanların çoğu basit veri türleridir, ancak alan gibi Address iç içe verileri temsil etmek için karmaşık türler tanımlayabilirsiniz.

  • Alan öznitelikleri izin verilen eylemleri belirler. REST API'leri varsayılan olarak birçok eyleme izin verir. Örneğin, tüm dizeler aranabilir ve alınabilir. REST API'lerinde öznitelikleri yalnızca bir davranışı devre dışı bırakmanız gerekiyorsa kullanabilirsiniz.

Belgeleri dizine yükleme

Yeni oluşturulan dizinler boş. Bir dizini doldurmak ve aranabilir hale getirmek için dizin şemasına uygun JSON belgelerini karşıya yüklemeniz gerekir.

Azure AI Search'de belgeler hem dizin oluşturma için giriş hem de sorgu çıkışları görevi görür. Kolaylık olması için, bu hızlı başlangıçta satır içi JSON olarak örnek otel belgeleri sağlanır. Ancak üretim senaryolarında içerik genellikle bağlı veri kaynaklarından alınır ve dizin oluşturucular kullanılarak JSON'a dönüştürülür.

Bu hızlı başlangıçta, dizininize dört örnek otel belgesi eklemek için Belgeler - Dizin (REST API) çağrısı yapılır. Önceki istekle karşılaştırıldığında, URI docs koleksiyonu ve index işlemini içerecek şekilde genişletilir.

$body = @"
{
    "value": [
        {
            "@search.action": "upload",
            "HotelId": "1",
            "HotelName": "Stay-Kay City Hotel",
            "Description": "This classic hotel is...",
            ...
        },
        ...
    ]
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/index?api-version=2025-09-01" $headers $body

Dizideki value her belge bir oteli temsil eder ve dizin şemasıyla eşleşen alanlar içerir. @search.action parametresi, her belge için gerçekleştirilecek işlemi belirtir. Bu örnekte, eğer belge yoksa belgeyi ekleyen veya varsa belgeyi güncelleyen upload kullanılır.

Dizini sorgulama

Artık belgeler dizininize yüklendiğinden, alanları içinde belirli terimleri veya tümcecikleri bulmak için tam metin aramasını kullanabilirsiniz.

Bu hızlı başlangıçta arama ölçütlerinize uyan otel belgelerini bulmak için Belgeler - Arama Gönderisi (REST API) çağrısı yapılır. URI, /docs/search işlemini hedefler.

Tam metin arama istekleri, terimler, tümcecikler veya işleçler içerebilen sorgu metnini içeren bir search parametre içerir. Sorgu, her belgedeki tüm aranabilir alanlarda aramalar içerir. Aşağıdaki örneklerde yaygın sorgu desenleri gösterilmektedir.

Sorgu örneği 1

Aşağıdaki sorgu, tüm aranabilir alanlarda "restoran wifi" terimlerini arar. Varsayılan olarak, Azure AI Search arama terimlerinden herhangi biriyle eşleşen belgeleri döndürür.

$body = @"
{
    "search": "restaurant wifi",
    "select": "HotelName, Description, Tags"
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

select parametresi, yanıtta döndürülen alanları HotelName, Description ve Tags ile sınırlar.

Sorgu örneği 2

Aşağıdaki sorgu, yalnızca derecelendirmesi 4'ten büyük olan otelleri döndürmek için bir ifade kullanır filter .

$body = @"
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName,Rating"
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

search parametresi, tüm belgelerle eşleşen bir değer olarak * ayarlanır. parametresi, filter sonuçları daraltmak için bir Boole koşulu uygular.

Sorgu örneği 3

Aşağıdaki sorgu "butik" için arama yapar ve yalnızca ilk iki sonucu döndürmek için kullanır top .

$body = @"
{
    "search": "boutique",
    "select": "HotelName,Category",
    "top": 2
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

Sorgu örneği 4

Aşağıdaki sorgu "havuz" araması yapar ve orderby kullanarak sonuçları Rating azalan düzende sıralamak için kullanır.

$body = @"
{
    "search": "pool",
    "select": "HotelName,Description,Tags,Rating",
    "orderby": "Rating desc"
}
"@

Send-RequestWithBody POST "$baseUrl/indexes/hotels-quickstart/docs/search?api-version=2025-09-01" $headers $body

Kaynakları temizle

Kendi aboneliğinizde çalışırken, artık ihtiyacınız olmayan kaynakları kaldırarak bir projeyi tamamlamak iyi bir fikirdir. Çalışır durumda kalan kaynaklar size pahalıya mal olabilir.

Kaynakları bulmak ve yönetmek için Azure portalında Tüm kaynaklar veya Kaynak grupları seçin. Kaynakları tek tek silebilir veya tüm kaynakları aynı anda kaldırmak için kaynak grubunu silebilirsiniz.

Ücretsiz arama hizmeti kullanıyorsanız üç dizin, dizin oluşturucu ve veri kaynağıyla sınırlı olduğunuzu unutmayın. Sınırın altında kalmak için portaldaki tek tek öğeleri silebilirsiniz .

İlgili içerik

  • Last updated on