Cara menggunakan Microsoft.Azure.Search dalam aplikasi C# .NET

Artikel ini menjelaskan cara membuat dan mengelola objek pencarian menggunakan C# dan pustaka klien lama, Microsoft.Azure.Search (versi 10) di Azure SDK untuk .NET.

Versi 10 adalah versi terakhir dari paket Microsoft.Azure.Search. Ke depannya, fitur baru akan diluncurkan di Azure.Search.Documents dari tim Azure SDK.

Tentang versi 10

SDK terdiri dari beberapa pustaka klien yang memungkinkan Anda mengelola indeks, sumber data, pengindeks, dan peta sinonim, serta mengunggah dan mengelola dokumen, dan menjalankan kueri, semuanya tanpa harus berurusan dengan detail HTTP dan JSON. Pustaka klien ini semuanya didistribusikan sebagai paket NuGet.

Paket NuGet utama adalah Microsoft.Azure.Search, yang merupakan paket meta yang mencakup semua paket lain sebagai dependensi. Gunakan paket ini jika Anda baru saja memulai atau jika Anda tahu aplikasi Anda akan memerlukan semua fitur Azure Cognitive Search.

Paket NuGet lainnya dalam SDK adalah:

• Microsoft.Azure.Search.Data: Gunakan paket ini jika Anda mengembangkan aplikasi .NET menggunakan Azure Cognitive Search, dan Anda hanya perlu mengkueri atau memperbarui dokumen dalam indeks Anda. Jika Anda juga perlu membuat atau memperbarui indeks, peta sinonim, atau sumber daya tingkat layanan lainnya, gunakan paket Microsoft.Azure.Search sebagai gantinya.
• Microsoft.Azure.Search.Service: Gunakan paket ini jika Anda mengembangkan otomatisasi di .NET untuk mengelola indeks Azure Cognitive Search, peta sinonim, pengindeks, sumber data, atau sumber daya tingkat layanan lainnya. Jika Anda hanya perlu mengkueri atau memperbarui dokumen dalam indeks Anda, gunakan paket Microsoft.Azure.Search.Data sebagai gantinya. Jika Anda memerlukan semua fungsionalitas Azure Cognitive Search, gunakan paket sebagai gantinya Microsoft.Azure.Search .
• Microsoft.Azure.Search.Common: Jenis-jenis yang dibutuhkan oleh pustaka .NET Azure Cognitive Search. Anda tidak perlu menggunakan paket ini langsung di aplikasi Anda. Ini hanya dimaksudkan untuk digunakan sebagai dependensi.

Berbagai pustaka klien mendefinisikan kelas seperti Index, , Fielddan Document, serta operasi seperti Indexes.Create dan Documents.Search pada SearchServiceClient kelas dan SearchIndexClient . Kelas ini diatur ke namespace berikut:

• Microsoft.Azure.Search
• Microsoft.Azure.Search.Models

Jika Anda ingin memberikan umpan balik untuk pembaruan SDK di masa mendatang, lihat halaman umpan balik kami atau buat masalah di GitHub dan sebutkan "Azure Cognitive Search" dalam judul masalah.

.NET SDK menargetkan versi 2019-05-06 REST API Azure Cognitive Search. Versi ini mencakup dukungan untuk jenis kompleks, pengayaan AI, lengkapi otomatis, dan mode penguraian JsonLines saat mengindeks Azure Blobs.

SDK ini tidak mendukung Operasi Manajemen seperti membuat dan menskalakan layanan Pencarian dan mengelola kunci API. Jika Anda perlu mengelola sumber daya Pencarian dari aplikasi .NET, Anda dapat menggunakan Azure Cognitive Search .NET Management SDK.

Tingkatkan ke v10

Jika Anda sudah menggunakan versi azure Cognitive Search .NET SDK yang lebih lama dan Anda ingin meningkatkan ke versi terbaru yang tersedia secara umum, artikel ini menjelaskan caranya .

Persyaratan SDK

1. Visual Studio 2017 atau yang lebih baru.
2. Layanan Azure Cognitive Search Anda sendiri. Untuk menggunakan SDK, Anda akan memerlukan nama layanan Anda dan satu atau beberapa kunci API. Membuat layanan di portal akan membantu Anda melalui langkah-langkah ini.
3. Unduh paket NuGet Azure Cognitive Search .NET SDK dengan menggunakan "Kelola Paket NuGet" di Visual Studio. Cukup cari nama Microsoft.Azure.Search paket di NuGet.org (atau salah satu nama paket lainnya di atas jika Anda hanya memerlukan subset fungsionalitas).

Azure Cognitive Search .NET SDK mendukung aplikasi yang menargetkan .NET Framework 4.5.2 dan yang lebih tinggi, serta .NET Core 2.0 dan yang lebih tinggi.

Skenario inti

Ada beberapa hal yang perlu Anda lakukan di aplikasi pencarian Anda. Dalam tutorial ini, kita akan membahas skenario inti ini:

• Membuat indeks
• Mengisi indeks dengan dokumen
• Mencari dokumen menggunakan pencarian dan filter teks lengkap

Kode sampel berikut mengilustrasikan masing-masing skenario ini. Jangan ragu untuk menggunakan cuplikan kode di aplikasi Anda sendiri.

Gambaran Umum

Aplikasi sampel yang akan kita jelajahi membuat indeks baru bernama "hotel", mengisinya dengan beberapa dokumen, lalu menjalankan beberapa kueri pencarian. Berikut adalah program utama, yang menunjukkan alur keseluruhan:

// This sample shows how to delete, create, upload documents and query an index
static void Main(string[] args)
{
    IConfigurationBuilder builder = new ConfigurationBuilder().AddJsonFile("appsettings.json");
    IConfigurationRoot configuration = builder.Build();

    SearchServiceClient serviceClient = CreateSearchServiceClient(configuration);

    string indexName = configuration["SearchIndexName"];

    Console.WriteLine("{0}", "Deleting index...\n");
    DeleteIndexIfExists(indexName, serviceClient);

    Console.WriteLine("{0}", "Creating index...\n");
    CreateIndex(indexName, serviceClient);

    ISearchIndexClient indexClient = serviceClient.Indexes.GetClient(indexName);

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

    ISearchIndexClient indexClientForQueries = CreateSearchIndexClient(configuration);

    RunQueries(indexClientForQueries);

    Console.WriteLine("{0}", "Complete.  Press any key to end application...\n");
    Console.ReadKey();
}

Kami akan menelusuri langkah demi langkah ini. Pertama, kita perlu membuat sebuah SearchServiceClient baru. Objek ini memungkinkan Anda mengelola indeks. Untuk membangunnya, Anda perlu memberikan nama layanan Azure Cognitive Search serta kunci API admin. Anda dapat memasukkan informasi ini dalam appsettings.json file aplikasi sampel.

private static SearchServiceClient CreateSearchServiceClient(IConfigurationRoot configuration)
{
    string searchServiceName = configuration["SearchServiceName"];
    string adminApiKey = configuration["SearchServiceAdminApiKey"];

    SearchServiceClient serviceClient = new SearchServiceClient(searchServiceName, new SearchCredentials(adminApiKey));
    return serviceClient;
}

Beberapa baris berikutnya memanggil metode untuk membuat indeks bernama "hotel", menghapusnya terlebih dahulu jika sudah ada. Kita akan membahas metode ini sebentar lagi.

Console.WriteLine("{0}", "Deleting index...\n");
DeleteIndexIfExists(indexName, serviceClient);

Console.WriteLine("{0}", "Creating index...\n");
CreateIndex(indexName, serviceClient);

Selanjutnya, indeks perlu diisi. Untuk mengisi indeks, kita akan membutuhkan SearchIndexClient. Ada dua cara untuk mendapatkannya: dengan membangunnya, atau dengan memanggil Indexes.GetClient di SearchServiceClient. Kami menggunakan yang terakhir untuk kenyamanan.

ISearchIndexClient indexClient = serviceClient.Indexes.GetClient(indexName);

Sekarang setelah kita memiliki SearchIndexClient, kita dapat mengisi indeks. Populasi indeks dilakukan dengan metode lain yang akan kita telusuri nanti.

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

Terakhir, kami menjalankan beberapa kueri pencarian dan menampilkan hasilnya. Kali ini kita menggunakan yang berbeda SearchIndexClient:

ISearchIndexClient indexClientForQueries = CreateSearchIndexClient(indexName, configuration);

RunQueries(indexClientForQueries);

Kita akan melihat lebih dekat metodenya RunQueries nanti. Berikut adalah kode untuk membuat yang baru SearchIndexClient:

private static SearchIndexClient CreateSearchIndexClient(string indexName, IConfigurationRoot configuration)
{
    string searchServiceName = configuration["SearchServiceName"];
    string queryApiKey = configuration["SearchServiceQueryApiKey"];

    SearchIndexClient indexClient = new SearchIndexClient(searchServiceName, indexName, new SearchCredentials(queryApiKey));
    return indexClient;
}

Kali ini kita menggunakan kunci kueri karena kita tidak perlu menulis akses ke indeks. Anda dapat memasukkan informasi ini dalam appsettings.json file aplikasi sampel.

Jika Anda menjalankan aplikasi ini dengan nama layanan dan kunci API yang valid, output akan terlihat seperti contoh ini: (Beberapa output konsol telah diganti dengan "..." untuk tujuan ilustrasi.)

Deleting index...

Creating index...

Uploading documents...

Waiting for documents to be indexed...

Search the entire index for the term 'motel' and return only the HotelName field:

Name: Secret Point Motel

Name: Twin Dome Motel


Apply a filter to the index to find hotels with a room cheaper than $100 per night, and return the hotelId and description:

HotelId: 1
Description: The hotel is 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.

HotelId: 2
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.


Search the entire index, order by a specific field (lastRenovationDate) in descending order, take the top two results, and show only hotelName and lastRenovationDate:

Name: Triple Landscape Hotel
Last renovated on: 9/20/2015 12:00:00 AM +00:00

Name: Twin Dome Motel
Last renovated on: 2/18/1979 12:00:00 AM +00:00


Search the hotel names for the term 'hotel':

HotelId: 3
Name: Triple Landscape Hotel
...

Complete.  Press any key to end application... 

Kode sumber lengkap aplikasi disediakan di akhir artikel ini.

Selanjutnya, kita akan melihat lebih dekat pada masing-masing metode yang dipanggil oleh Main.

Membuat indeks

Setelah membuat SearchServiceClient, Main menghapus indeks "hotel" jika sudah ada. Penghapusan tersebut dilakukan dengan metode berikut:

private static void DeleteIndexIfExists(string indexName, SearchServiceClient serviceClient)
{
    if (serviceClient.Indexes.Exists(indexName))
    {
        serviceClient.Indexes.Delete(indexName);
    }
}

Metode ini menggunakan yang diberikan SearchServiceClient untuk memeriksa apakah indeks ada, dan jika demikian, hapus.

Selanjutnya, Main membuat indeks "hotel" baru dengan memanggil metode ini:

private static void CreateIndex(string indexName, SearchServiceClient serviceClient)
{
    var definition = new Index()
    {
        Name = indexName,
        Fields = FieldBuilder.BuildForType<Hotel>()
    };
    
    serviceClient.Indexes.Create(definition);
}

Metode ini membuat objek baru Index dengan daftar Field objek yang menentukan skema indeks baru. Setiap bidang memiliki nama, jenis data, dan beberapa atribut yang menentukan perilaku pencariannya. Kelas FieldBuilder menggunakan refleksi untuk membuat daftar objek Field untuk indeks dengan menguji properti dan atribut publik dari kelas model Hotel yang diberikan. Kita akan melihat lebih dekat kelas Hotel di lain waktu.

Selain bidang, Anda juga dapat menambahkan profil penilaian, penyaran, atau opsi CORS pada Indeks (parameter ini dihilangkan dari sampel untuk kesederhanaan). Anda dapat menemukan informasi selengkapnya tentang objek Indeks dan bagian konstituennya dalam referensi SDK, serta dalam referensi REST API Azure Cognitive Search.

Memasukkan data ke dalam indeks

Langkah selanjutnya dalam Main mengisi indeks yang baru dibuat. Populasi indeks ini dilakukan dalam metode berikut: (Beberapa kode diganti dengan "..." untuk tujuan ilustrasi. Lihat solusi sampel lengkap untuk kode populasi data lengkap.)

private static void UploadDocuments(ISearchIndexClient indexClient)
{
    var hotels = new Hotel[]
    {
        new Hotel()
        {
            HotelId = "1",
            HotelName = "Secret Point Motel",
            ...
            Address = new Address()
            {
                StreetAddress = "677 5th Ave",
                ...
            },
            Rooms = new Room[]
            {
                new Room()
                {
                    Description = "Budget Room, 1 Queen Bed (Cityside)",
                    ...
                },
                new Room()
                {
                    Description = "Budget Room, 1 King Bed (Mountain View)",
                    ...
                },
                new Room()
                {
                    Description = "Deluxe Room, 2 Double Beds (City View)",
                    ...
                }
            }
        },
        new Hotel()
        {
            HotelId = "2",
            HotelName = "Twin Dome Motel",
            ...
            {
                StreetAddress = "140 University Town Center Dr",
                ...
            },
            Rooms = new Room[]
            {
                new Room()
                {
                    Description = "Suite, 2 Double Beds (Mountain View)",
                    ...
                },
                new Room()
                {
                    Description = "Standard Room, 1 Queen Bed (City View)",
                    ...
                },
                new Room()
                {
                    Description = "Budget Room, 1 King Bed (Waterfront View)",
                    ...
                }
            }
        },
        new Hotel()
        {
            HotelId = "3",
            HotelName = "Triple Landscape Hotel",
            ...
            Address = new Address()
            {
                StreetAddress = "3393 Peachtree Rd",
                ...
            },
            Rooms = new Room[]
            {
                new Room()
                {
                    Description = "Standard Room, 2 Queen Beds (Amenities)",
                    ...
                },
                new Room ()
                {
                    Description = "Standard Room, 2 Double Beds (Waterfront View)",
                    ...
                },
                new Room()
                {
                    Description = "Deluxe Room, 2 Double Beds (Cityside)",
                    ...
                }
            }
        }
    };

    var batch = IndexBatch.Upload(hotels);

    try
    {
        indexClient.Documents.Index(batch);
    }
    catch (IndexBatchException e)
    {
        // Sometimes when your Search service is under load, indexing will fail for some of the documents in
        // the batch. Depending on your application, you can take compensating actions like delaying and
        // retrying. For this simple demo, we just log the failed document keys and continue.
        Console.WriteLine(
            "Failed to index some of the documents: {0}",
            String.Join(", ", e.IndexingResults.Where(r => !r.Succeeded).Select(r => r.Key)));
    }

    Console.WriteLine("Waiting for documents to be indexed...\n");
    Thread.Sleep(2000);
}

Metode ini memiliki empat bagian. Yang pertama membuat sebuah array berisi 3 objek Hotel yang masing-masing berisi 3 objek Room dan akan berfungsi sebagai data masukan untuk diunggah ke indeks. Data ini dikodekan secara permanen untuk kesederhanaan. Dalam aplikasi Anda sendiri, data Anda kemungkinan akan berasal dari sumber data eksternal seperti database SQL.

Bagian kedua membuat IndexBatch yang berisi dokumen. Anda menentukan operasi yang ingin Anda terapkan ke batch pada saat Anda membuatnya, dalam hal ini dengan memanggil IndexBatch.Upload. Batch kemudian diunggah ke indeks Azure Cognitive Search dengan Documents.Index metode .

Bagian ketiga dari metode ini adalah blok tangkapan yang menangani kasus kesalahan penting untuk pengindeksan. Jika layanan Azure Cognitive Search Anda gagal mengindeks beberapa dokumen dalam batch, maka IndexBatchException akan dilemparkan oleh Documents.Index. Pengecualian ini dapat terjadi jika Anda mengindeks dokumen saat layanan Anda berada di bawah beban berat. Sangat direkomendasikan untuk menangani kasus ini secara eksplisit dalam kode Anda. Anda dapat menunda lalu mencoba mengindeks dokumen yang gagal, atau Anda dapat mencatat dan melanjutkan seperti sampel, atau Anda dapat melakukan hal lain tergantung pada persyaratan konsistensi data aplikasi Anda.

Terakhir, metode UploadDocuments akan tertunda selama dua detik. Pengindeksan terjadi secara asinkron di layanan Azure Cognitive Search Anda, sehingga aplikasi sampel perlu menunggu waktu singkat untuk memastikan bahwa dokumen tersedia untuk dicari. Penundaan seperti ini biasanya hanya diperlukan dalam demo, pengujian, dan aplikasi contoh.

Cara .NET SDK menangani dokumen

Anda mungkin bertanya-tanya bagaimana Azure Cognitive Search .NET SDK dapat mengunggah instans kelas yang ditentukan pengguna seperti Hotel ke indeks. Untuk membantu menjawab pertanyaan tersebut, mari kita lihat kelas Hotel.

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Microsoft.Spatial;
using Newtonsoft.Json;

public partial class Hotel
{
    [System.ComponentModel.DataAnnotations.Key]
    [IsFilterable]
    public string HotelId { get; set; }

    [IsSearchable, IsSortable]
    public string HotelName { get; set; }

    [IsSearchable]
    [Analyzer(AnalyzerName.AsString.EnLucene)]
    public string Description { get; set; }

    [IsSearchable]
    [Analyzer(AnalyzerName.AsString.FrLucene)]
    [JsonProperty("Description_fr")]
    public string DescriptionFr { get; set; }

    [IsSearchable, IsFilterable, IsSortable, IsFacetable]
    public string Category { get; set; }

    [IsSearchable, IsFilterable, IsFacetable]
    public string[] Tags { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public bool? ParkingIncluded { get; set; }

    // SmokingAllowed reflects whether any room in the hotel allows smoking.
    // The JsonIgnore attribute indicates that a field should not be created 
    // in the index for this property and it will only be used by code in the client.
    [JsonIgnore]
    public bool? SmokingAllowed => (Rooms != null) ? Array.Exists(Rooms, element => element.SmokingAllowed == true) : (bool?)null;

    [IsFilterable, IsSortable, IsFacetable]
    public DateTimeOffset? LastRenovationDate { get; set; }

    [IsFilterable, IsSortable, IsFacetable]
    public double? Rating { get; set; }

    public Address Address { get; set; }

    [IsFilterable, IsSortable]
    public GeographyPoint Location { get; set; }

    public Room[] Rooms { get; set; }
}

Hal pertama yang perlu diperhatikan adalah bahwa nama setiap properti publik di Hotel kelas akan dipetakan ke bidang dengan nama yang sama dalam definisi indeks. Jika Anda ingin setiap bidang dimulai dengan huruf kecil ("kasus camel"), Anda dapat memberi tahu SDK untuk memetakan nama properti ke camel-case secara otomatis dengan [SerializePropertyNamesAsCamelCase] atribut pada kelas . Skenario ini umum dalam aplikasi .NET yang melakukan pengikatan data di mana skema target berada di luar kendali pengembang aplikasi tanpa harus melanggar pedoman penamaan "Kasus Pascal" di .NET.

Hal kedua yang perlu diperhatikan adalah setiap properti dihiasi dengan atribut seperti IsFilterable, , IsSearchableKey, dan Analyzer. Atribut ini memetakan langsung ke atribut bidang yang sesuai dalam indeks Azure Cognitive Search. Kelas FieldBuilder menggunakan properti ini untuk membuat definisi bidang untuk indeks.

Hal penting ketiga tentang Hotel kelas adalah jenis data properti publik. Jenis tipe .NET dari properti ini memetakan ke tipe bidang yang setara dalam definisi indeks. Misalnya, properti string Category dipetakan ke bidang category, yang berjenis Edm.String. Ada pemetaan jenis yang sama antara bool?, Edm.Boolean, DateTimeOffset?, Edm.DateTimeOffset dan sebagainya. Aturan khusus untuk pemetaan tipe didokumentasikan menggunakan metode Documents.Get dalam referensi "Azure Cognitive Search .NET SDK". Kelas FieldBuilder mengurus pemetaan ini untuk Anda, tetapi tetap penting untuk memahami apabila Anda perlu memecahkan masalah serialisasi apa pun.

Apakah Anda kebetulan memperhatikan properti SmokingAllowed?

[JsonIgnore]
public bool? SmokingAllowed => (Rooms != null) ? Array.Exists(Rooms, element => element.SmokingAllowed == true) : (bool?)null;

Atribut JsonIgnore pada properti ini memberitahukan kepada pihak FieldBuilder untuk tidak menserialisasikannya ke indeks sebagai bidang. Ini adalah cara yang bagus untuk membuat properti yang dihitung di sisi klien, yang dapat Anda gunakan sebagai pendukung dalam aplikasi Anda. Dalam hal ini, properti SmokingAllowed mencerminkan apakah ada Room dalam koleksi Rooms yang memperbolehkan merokok. Jika semua salah, itu menunjukkan bahwa seluruh hotel tidak mengizinkan merokok.

Beberapa properti seperti Address dan Rooms merupakan instans kelas .NET. Properti ini mewakili struktur data yang lebih kompleks dan, sebagai hasilnya, memerlukan bidang dengan jenis data yang kompleks dalam indeks.

Properti Address mewakili sekumpulan nilai ganda di Address kelas , yang ditentukan di bawah ini:

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Newtonsoft.Json;

namespace AzureSearch.SDKHowTo
{
    public partial class Address
    {
        [IsSearchable]
        public string StreetAddress { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string City { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string StateProvince { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string PostalCode { get; set; }

        [IsSearchable, IsFilterable, IsSortable, IsFacetable]
        public string Country { get; set; }
    }
}

Kelas ini berisi nilai standar yang digunakan untuk menjelaskan alamat di Amerika Serikat atau Kanada. Anda dapat menggunakan jenis seperti ini untuk mengelompokkan bidang logis bersama-sama dalam indeks.

Properti Rooms mewakili array dari objek Room.

using System;
using Microsoft.Azure.Search;
using Microsoft.Azure.Search.Models;
using Newtonsoft.Json;

namespace AzureSearch.SDKHowTo
{
    public partial class Room
    {
        [IsSearchable]
        [Analyzer(AnalyzerName.AsString.EnMicrosoft)]
        public string Description { get; set; }

        [IsSearchable]
        [Analyzer(AnalyzerName.AsString.FrMicrosoft)]
        [JsonProperty("Description_fr")]
        public string DescriptionFr { get; set; }

        [IsSearchable, IsFilterable, IsFacetable]
        public string Type { get; set; }

        [IsFilterable, IsFacetable]
        public double? BaseRate { get; set; }

        [IsSearchable, IsFilterable, IsFacetable]
        public string BedOptions { get; set; }

        [IsFilterable, IsFacetable]
        public int SleepsCount { get; set; }

        [IsFilterable, IsFacetable]
        public bool? SmokingAllowed { get; set; }

        [IsSearchable, IsFilterable, IsFacetable]
        public string[] Tags { get; set; }
    }
}

Model data Anda di .NET dan skema indeks yang sesuai harus dirancang untuk mendukung pengalaman pencarian yang ingin Anda berikan kepada pengguna akhir Anda. Setiap objek tingkat atas di .NET, yaitu dokumen dalam indeks, sesuai dengan hasil pencarian yang akan Anda sajikan di antarmuka pengguna Anda. Misalnya, dalam aplikasi pencarian hotel, pengguna akhir Anda mungkin ingin mencari berdasarkan nama hotel, fitur hotel, atau karakteristik kamar tertentu. Kita akan membahas beberapa contoh kueri beberapa saat kemudian.

Kemampuan untuk menggunakan kelas Anda sendiri untuk berinteraksi dengan dokumen dalam indeks berfungsi di kedua arah; Anda juga dapat mengambil hasil pencarian dan meminta SDK secara otomatis mendeserialisasinya ke jenis pilihan Anda, seperti yang akan kita lihat di bagian berikutnya.

Mengapa Anda harus menggunakan jenis data yang dapat diubah ke null

Saat merancang kelas model Anda sendiri untuk memetakan ke indeks Azure Cognitive Search, sebaiknya deklarasikan properti jenis nilai seperti bool dan int dapat diubah ke null (misalnya, bool? bukan bool). Jika Anda menggunakan properti yang tidak dapat diubah ke null, Anda harus menjamin bahwa tidak ada dokumen dalam indeks Anda yang berisi nilai null untuk bidang yang sesuai. Baik SDK maupun layanan Azure Cognitive Search tidak akan membantu Anda memberlakukan ini.

Ini bukan hanya masalah hipotetis: Bayangkan skenario di mana Anda menambahkan bidang baru ke indeks yang ada yang berjenis Edm.Int32. Setelah memperbarui definisi indeks, semua dokumen akan memiliki nilai null untuk bidang baru tersebut (karena semua jenis dapat diubah ke null di Azure Cognitive Search). Jika Anda kemudian menggunakan kelas model dengan properti int yang tidak dapat diubah ke null untuk bidang tersebut, Anda akan mendapatkan JsonSerializationException seperti ini saat mencoba mengambil dokumen:

Error converting value {null} to type 'System.Int32'. Path 'IntValue'.

Oleh karena itu, kami sarankan Anda menggunakan tipe data yang dapat bernilai null di kelas model Anda sebagai praktik terbaik.

Serialisasi Kustom dengan JSON.NET

SDK menggunakan JSON.NET untuk menserialisasikan dan mendeserialisasi dokumen. Anda dapat menyesuaikan serialisasi dan deserialisasi jika diperlukan dengan mendefinisikan milik Anda sendiri JsonConverter atau IContractResolver. Untuk informasi selengkapnya, lihat dokumentasi JSON.NET. Ini dapat berguna ketika Anda ingin menyesuaikan kelas model yang ada dari aplikasi Anda untuk digunakan dengan Azure Cognitive Search, dan skenario lain yang lebih canggih. Misalnya, dengan serialisasi kustom Anda dapat:

• Sertakan atau kecualikan properti tertentu dari kelas model Anda agar tidak disimpan sebagai bidang dokumen.
• Petakan antara nama properti dalam kode dan nama bidang Anda dalam indeks Anda.
• Buat atribut kustom yang dapat digunakan untuk memetakan properti ke bidang dokumen.

Anda dapat menemukan contoh penerapan serialisasi kustom dalam pengujian unit untuk Azure Cognitive Search .NET SDK di GitHub. Titik awal yang baik adalah folder ini. Ini berisi kelas yang digunakan oleh pengujian serialisasi kustom.

Mencari dokumen dalam indeks

Langkah terakhir dalam aplikasi sampel adalah mencari beberapa dokumen dalam indeks:

private static void RunQueries(ISearchIndexClient indexClient)
{
    SearchParameters parameters;
    DocumentSearchResult<Hotel> results;

    Console.WriteLine("Search the entire index for the term 'motel' and return only the HotelName field:\n");

    parameters =
        new SearchParameters()
        {
            Select = new[] { "HotelName" }
        };

    results = indexClient.Documents.Search<Hotel>("motel", parameters);

    WriteDocuments(results);

    Console.Write("Apply a filter to the index to find hotels with a room cheaper than $100 per night, ");
    Console.WriteLine("and return the hotelId and description:\n");

    parameters =
        new SearchParameters()
        {
            Filter = "Rooms/any(r: r/BaseRate lt 100)",
            Select = new[] { "HotelId", "Description" }
        };

    results = indexClient.Documents.Search<Hotel>("*", parameters);

    WriteDocuments(results);

    Console.Write("Search the entire index, order by a specific field (lastRenovationDate) ");
    Console.Write("in descending order, take the top two results, and show only hotelName and ");
    Console.WriteLine("lastRenovationDate:\n");

    parameters =
        new SearchParameters()
        {
            OrderBy = new[] { "LastRenovationDate desc" },
            Select = new[] { "HotelName", "LastRenovationDate" },
            Top = 2
        };

    results = indexClient.Documents.Search<Hotel>("*", parameters);

    WriteDocuments(results);

    Console.WriteLine("Search the entire index for the term 'hotel':\n");

    parameters = new SearchParameters();
    results = indexClient.Documents.Search<Hotel>("hotel", parameters);

    WriteDocuments(results);
}

Setiap kali menjalankan kueri, metode ini terlebih dahulu membuat objek baru SearchParameters . Obyek ini digunakan untuk menentukan opsi tambahan untuk kueri seperti pengurutan, pemfilteran, penomoran halaman, dan faseting. Dalam metode ini, kita mengatur properti Filter, Select, OrderBy, dan Top untuk kueri yang berbeda. Semua properti tercatat SearchParametersdi sini.

Langkah selanjutnya adalah benar-benar menjalankan kueri pencarian. Menjalankan pencarian dilakukan menggunakan metode Documents.Search. Untuk setiap kueri, kita meneruskan teks pencarian untuk digunakan sebagai string (atau "*" jika tidak ada teks pencarian), ditambah parameter pencarian yang dibuat sebelumnya. Kami juga menentukan Hotel sebagai parameter jenis untukDocuments.Search, yang memberitahu SDK untuk mendeserialisasi dokumen dalam hasil pencarian menjadi objek jenis Hotel.

Terakhir, setelah setiap kueri, metode ini melakukan iterasi melalui semua kecocokan dalam hasil pencarian, mencetak setiap dokumen ke konsol:

private static void WriteDocuments(DocumentSearchResult<Hotel> searchResults)
{
    foreach (SearchResult<Hotel> result in searchResults.Results)
    {
        Console.WriteLine(result.Document);
    }

    Console.WriteLine();
}

Mari kita lihat lebih dekat pada setiap pertanyaan secara satu per satu. Berikut adalah kode untuk menjalankan kueri pertama:

parameters =
    new SearchParameters()
    {
        Select = new[] { "HotelName" }
    };

results = indexClient.Documents.Search<Hotel>("motel", parameters);

WriteDocuments(results);

Dalam hal ini, kami mencari seluruh indeks untuk kata "motel" di bidang apa pun yang dapat dicari dan kami hanya ingin mengambil nama hotel, seperti yang ditentukan oleh Select parameter . Berikut hasilnya:

Name: Secret Point Motel

Name: Twin Dome Motel

Kueri berikutnya sedikit lebih menarik. Kami ingin menemukan hotel apa pun yang memiliki kamar dengan tarif per malam kurang dari $ 100 dan hanya mengembalikan ID dan deskripsi hotel:

parameters =
    new SearchParameters()
    {
        Filter = "Rooms/any(r: r/BaseRate lt 100)",
        Select = new[] { "HotelId", "Description" }
    };

results = indexClient.Documents.Search<Hotel>("*", parameters);

WriteDocuments(results);

Kueri ini menggunakan ekspresi $filter OData, Rooms/any(r: r/BaseRate lt 100), untuk memfilter dokumen dalam indeks. Ini menggunakan operator apa pun untuk menerapkan 'BaseRate lt 100' ke setiap item dalam koleksi Kamar. Anda dapat mengetahui selengkapnya tentang sintaks OData yang didukung Azure Cognitive Search di sini.

Berikut adalah hasil kueri:

HotelId: 1
Description: The hotel is ideally located on the main commercial artery of the city in the heart of New York...

HotelId: 2
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to...

Selanjutnya, kami ingin menemukan dua hotel teratas yang baru saja direnovasi, dan menunjukkan nama hotel dan tanggal renovasi terakhir. Berikut adalah kodenya:

parameters =
    new SearchParameters()
    {
        OrderBy = new[] { "LastRenovationDate desc" },
        Select = new[] { "HotelName", "LastRenovationDate" },
        Top = 2
    };

results = indexClient.Documents.Search<Hotel>("*", parameters);

WriteDocuments(results);

Dalam hal ini, kita kembali menggunakan sintaks OData untuk menentukan OrderBy parameter sebagai lastRenovationDate desc. Kami juga mengatur Top ke 2 untuk memastikan kami hanya mendapatkan dua dokumen teratas. Seperti sebelumnya, kita mengatur Select untuk menentukan bidang mana yang harus dikembalikan.

Berikut hasilnya:

Name: Fancy Stay        Last renovated on: 6/27/2010 12:00:00 AM +00:00
Name: Roach Motel       Last renovated on: 4/28/1982 12:00:00 AM +00:00

Akhirnya, kami ingin menemukan semua nama hotel yang cocok dengan kata "hotel":

parameters = new SearchParameters()
{
    SearchFields = new[] { "HotelName" }
};
results = indexClient.Documents.Search<Hotel>("hotel", parameters);

WriteDocuments(results);

Dan berikut adalah hasilnya, yang mencakup semua bidang karena kami tidak menentukan Select properti:

	HotelId: 3
	Name: Triple Landscape Hotel
	...

Langkah ini menyelesaikan tutorial, tetapi jangan berhenti di sini. **Langkah berikutnya menyediakan sumber daya tambahan untuk mempelajari selengkapnya tentang Azure Cognitive Search.

Langkah berikutnya

• Telusuri referensi untuk .NET SDK dan REST API.
• Tinjau konvensi penamaan untuk mempelajari aturan penamaan berbagai objek.
• Tinjau jenis data yang didukung di Azure Cognitive Search.