Mulai cepat: Pencarian teks lengkap

Dalam pemanduan cepat ini, Anda menggunakan pustaka klien Azure AI Search untuk .NET untuk membuat, memuat, dan menjalankan kueri indeks pencarian untuk pencarian teks penuh (full-text search), juga dikenal sebagai pencarian kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

  • Akun Azure dengan langganan aktif. Buat akun secara gratis.

  • Layanan Azure AI Search. Anda dapat menggunakan layanan gratis untuk panduan memulai cepat ini.

  • .NET 8 atau yang lebih baru.

  • Git untuk mengkloning repositori sampel.

  • Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Navigasikan ke folder quickstart.

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

  3. Di Program.cs, ganti nilai tempat penampung untuk serviceEndpoint dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Pasang dependensi dari AzureSearchQuickstart.csproj.

    dotnet restore

    Ketika pemulihan selesai, verifikasi bahwa tidak ada kesalahan yang muncul dalam output.

  5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

Menjalankan kode

Bangun dan jalankan aplikasi.

dotnet run

Keluaran

Outputnya harus mirip dengan yang berikut ini:

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

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat klien pencarian
  2. Membuat indeks pencarian
  3. Mengunggah dokumen ke indeks
  4. Melakukan pencarian pada indeks

Membuat klien pencarian

Di Program.cs, Anda membuat dua klien:

Kedua klien memerlukan titik akhir layanan dan kredensial untuk autentikasi. Dalam panduan cepat ini, Anda menggunakan DefaultAzureCredential untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Membuat indeks pencarian

Panduan cepat ini membangun indeks hotel yang Anda muat dengan data hotel dan melakukan kueri terhadapnya. Dalam langkah ini, Anda menentukan bidang dalam indeks. Setiap definisi bidang menyertakan nama, tipe data, dan atribut yang menentukan cara bidang digunakan.

Contoh ini menggunakan metode sinkron kelas SearchIndexClient untuk kesederhanaan dan keterbacaan. Namun, untuk skenario produksi, gunakan metode asinkron untuk menjaga aplikasi Anda tetap dapat diskalakan dan responsif. Misalnya, gunakan CreateIndexAsync alih-alih CreateIndex.

Menentukan struktur

Anda membuat dua kelas pembantu, Hotel.cs dan Address.cs, untuk menentukan struktur dokumen hotel dan alamatnya. Kelas ini Hotel mencakup bidang untuk ID hotel, nama, deskripsi, kategori, tag, parkir, tanggal renovasi, peringkat, dan alamat. Kelas ini Address mencakup bidang untuk alamat jalan, kota, negara bagian/provinsi, kode pos, dan negara/wilayah.

Di pustaka klien Azure.Search.Documents, Anda dapat menggunakan SearchableField dan SimpleField untuk menyederhanakan definisi bidang. Keduanya adalah kelas pembantu yang menghasilkan SearchField dan berpotensi menyederhanakan kode Anda:

  • SimpleField dapat berupa tipe data apa pun, selalu tidak dapat dicari (diabaikan dalam kueri pencarian teks lengkap), dan dapat diambil kembali (tidak tersembunyi). Atribut lain tidak aktif secara default, tetapi dapat diaktifkan. Anda mungkin menggunakan SimpleField untuk ID dokumen atau bidang yang hanya digunakan dalam filter, faset, atau profil penilaian. Jika demikian, terapkan atribut apa pun yang diperlukan untuk skenario, seperti IsKey = true untuk ID dokumen.

  • SearchableField harus berupa string, dan selalu dapat dicari dan diambil. Atribut lain tidak aktif secara default, tetapi dapat diaktifkan. Karena jenis bidang ini dapat dicari, ia mendukung sinonim dan kelengkapan lengkap properti penganalisis.

Apakah Anda menggunakan dasar SearchField API atau salah satu model pembantu, Anda harus secara eksplisit mengaktifkan atribut filter, faset, dan sort. Misalnya, IsFilterable, IsSortable, dan IsFacetable harus dikaitkan secara eksplisit, seperti yang ditunjukkan pada sampel sebelumnya.

Membuat indeks pencarian

Di Program.cs, Anda membuat objek SearchIndex , lalu memanggil metode CreateOrUpdateIndex untuk mengekspresikan indeks di layanan pencarian Anda. Indeks juga termasuk SearchSuggester untuk mengaktifkan pelengkapan otomatis pada bidang yang ditentukan.

// 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);
}

Mengunggah dokumen ke indeks

Azure AI Search mencari konten yang disimpan dalam layanan. Dalam langkah ini, Anda memuat dokumen JSON yang sesuai dengan indeks hotel yang Anda buat.

Dalam Azure AI Search, dokumen pencarian adalah struktur data yang merupakan input ke pengindeksan dan output dari kueri. Seperti yang diperoleh dari sumber data eksternal, input dokumen mungkin berupa baris dalam database, blob di Azure Blob Storage, atau dokumen JSON pada disk. Dalam contoh ini, Anda mengambil pintasan dan menyematkan dokumen JSON untuk empat hotel secara langsung.

Saat mengunggah dokumen, Anda harus menggunakan obyek IndexDocumentsBatch. Objek IndexDocumentsBatch berisi kumpulan Actions, yang masing-masing berisi dokumen dan properti yang memberi tahu Azure AI Search tindakan apa yang harus dilakukan (upload, gabungkan, hapus, dan mergeOrUpload).

Di Program.cs, Anda membuat array dokumen dan tindakan indeks, lalu meneruskan array ke IndexDocumentsBatch. Dokumen berikut sesuai dengan indeks hotel-quickstart, sebagaimana didefinisikan oleh kelas hotel.

// 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
}

Metode ini UploadDocuments membuat IndexDocumentsBatch dan memanggil IndexDocuments pada SearchClient untuk mengunggah dokumen. Panduan memulai cepat ini memperoleh SearchClient dari SearchIndexClient dengan memanfaatkan GetSearchClient, yang memakai kembali kredensial yang sama.

SearchClient ingesterClient = searchIndexClient.GetSearchClient(indexName);

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

Karena aplikasi konsol ini menjalankan semua perintah secara berurutan, kode menambahkan waktu tunggu dua detik antara pengindeksan dan kueri.

// 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);

Penundaan dua detik mengkompensasi pengindeksan, yang asinkron, sehingga semua dokumen dapat diindeks sebelum kueri dijalankan. Pemrograman dengan keterlambatan biasanya hanya diperlukan dalam demo, pengujian, dan aplikasi sampel.

Melakukan pencarian pada indeks

Anda bisa mendapatkan hasil kueri segera setelah dokumen pertama diindeks, tetapi pengujian aktual indeks Anda harus menunggu hingga semua dokumen diindeks.

Bagian ini menambahkan dua bagian fungsionalitas: logika dan hasil kueri. Untuk pertanyaan, gunakan metode Cari. Metode ini mengambil teks pencarian (string kueri) dan opsi lainnya.

SearchResults kelas ini mewakili hasil.

Dalam Program.cs, metode WriteDocuments mencetak hasil pencarian ke konsol.

// 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();
}

Contoh kueri 1

Metode ini RunQueries menjalankan kueri dan mengembalikan hasil. Hasilnya merupakan objek Hotel. Sampel ini menunjukkan tanda tangan metode dan kueri pertama. Kueri ini menunjukkan Select parameter yang memungkinkan Anda menyusun hasil menggunakan bidang yang dipilih dari dokumen.

// 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
}

Contoh kueri 2

Di kueri kedua, lakukan pencarian berdasarkan istilah, tambahkan filter yang memilih dokumen di mana Rating lebih besar dari 4, lalu urutkan Rating secara menurun. Filter adalah ekspresi boolean yang dievaluasi melalui bidang IsFilterable dalam indeks. Filter kueri menyertakan atau mengecualikan nilai. Dengan demikian, tidak ada skor relevansi yang terkait dengan kueri filter.

// 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);

Contoh kueri 3

Kueri ketiga menunjukkan searchFields, digunakan untuk mencakup operasi pencarian teks lengkap ke bidang tertentu.

// 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);

Contoh kueri 4

Kueri keempat menunjukkan facets, yang dapat digunakan untuk menyusun struktur navigasi berfasis.

// 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);

Contoh kueri 5

Di permintaan kelima, kembalikan sebuah dokumen tertentu. Pencarian dokumen adalah respons umum terhadap peristiwa OnClick dalam set hasil.

// 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);

Contoh kueri 6

Kueri terakhir memperlihatkan sintaks untuk pelengkapan otomatis, mensimulasikan input pengguna parsial sa yang menyelesaikan dua kemungkinan kecocokan dalam sourceFields yang terkait dengan pemberi saran yang Anda tentukan dalam indeks.

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

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

Ringkasan kueri

Permintaan sebelumnya memperlihatkan beberapa cara pencocokan istilah dalam permintaan:pencarian teks lengkap, filter, dan kelengkapan otomatis.

Metode SearchClient.Search melakukan pencarian teks lengkap dan filter. Anda dapat meneruskan kueri pencarian dalam searchText string, saat Anda meneruskan ekspresi filter di properti Filter kelas SearchOptions . Untuk memfilter tanpa mencari, cukup lewati "*" untuk parameter searchText pada metode Pencarian. Untuk mencari tanpa pemfilteran, biarkan properti Filter tidak disetel, atau jangan melewatkan instans SearchOptions sama sekali.

Dalam panduan cepat ini, Anda menggunakan pustaka klien Azure AI Search untuk Java untuk membuat, memuat, dan mengkueri indeks pencarian untuk pencarian teks lengkap, juga dikenal sebagai pencarian-kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Navigasikan ke folder quickstart.

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

  3. Di src/main/java/azure/search/sample/App.java, ganti nilai tempat penampung untuk searchServiceEndpoint dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Pasang dependensi.

    mvn clean dependency:copy-dependencies

    Saat build selesai, verifikasi bahwa tidak ada kesalahan yang muncul dalam output.

  5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

Menjalankan kode

Kompilasi dan jalankan aplikasi.

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

Keluaran

Outputnya harus mirip dengan yang berikut ini:

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.

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat klien pencarian
  2. Membuat indeks pencarian
  3. Mengunggah dokumen ke indeks
  4. Melakukan pencarian pada indeks

Membuat klien pencarian

Di App.java, Anda membuat dua klien:

Kedua klien memerlukan titik akhir layanan dan kredensial untuk autentikasi. Dalam panduan cepat ini, Anda menggunakan DefaultAzureCredential untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Membuat indeks pencarian

Panduan cepat ini membangun indeks hotel yang Anda muat dengan data hotel dan melakukan kueri terhadapnya. Dalam langkah ini, Anda menentukan bidang dalam indeks. Setiap definisi bidang menyertakan nama, tipe data, dan atribut yang menentukan cara bidang digunakan.

Contoh ini menggunakan metode sinkron kelas SearchIndexClient untuk kesederhanaan dan keterbacaan. Namun, untuk skenario produksi, gunakan kelas SearchIndexAsyncClient untuk menjaga aplikasi Anda tetap dapat diskalakan dan responsif.

Menentukan struktur

Anda membuat dua kelas pembantu, Hotel.java dan Address.java, untuk menentukan struktur dokumen hotel dan alamatnya. Kelas ini Hotel mencakup bidang untuk ID hotel, nama, deskripsi, kategori, tag, parkir, tanggal renovasi, peringkat, dan alamat. Kelas ini Address mencakup bidang untuk alamat jalan, kota, negara bagian/provinsi, kode pos, dan negara/wilayah.

Di pustaka klien azure-search-documents, Anda dapat menggunakan SearchableField dan SimpleField untuk menyederhanakan definisi bidang. Keduanya adalah anotasi yang dapat Anda terapkan ke bidang atau metode untuk menghasilkan SearchField:

  • SimpleField dapat berupa tipe data apa pun, selalu tidak dapat dicari (diabaikan dalam kueri pencarian teks lengkap), dan dapat diambil kembali (tidak tersembunyi). Atribut lain tidak aktif secara default, tetapi dapat diaktifkan. Anda mungkin menggunakan SimpleField untuk ID dokumen atau bidang yang hanya digunakan dalam filter, faset, atau profil penilaian. Jika demikian, terapkan atribut apa pun yang diperlukan untuk skenario, seperti isKey = true untuk ID dokumen.
  • SearchableField harus berupa string, dan selalu dapat dicari dan diambil. Atribut lain tidak aktif secara default, tetapi dapat diaktifkan. Karena jenis bidang ini dapat dicari, ia mendukung sinonim dan kelengkapan lengkap properti penganalisis.

Apakah Anda menggunakan dasar SearchField API atau salah satu model pembantu, Anda harus secara eksplisit mengaktifkan atribut filter, faset, dan sort. Misalnya, isFilterable, isSortable, dan isFacetable harus diatribusikan secara eksplisit, seperti yang ditunjukkan pada sampel sebelumnya.

Membuat indeks pencarian

Di App.java, Anda membuat objek SearchIndex , lalu memanggil metode createOrUpdateIndex untuk mengekspresikan indeks di layanan pencarian Anda. Indeks juga termasuk SearchSuggester untuk mengaktifkan pelengkapan otomatis pada bidang yang ditentukan.

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

Mengunggah dokumen ke indeks

Azure AI Search mencari konten yang disimpan dalam layanan. Dalam langkah ini, Anda memuat dokumen JSON yang sesuai dengan indeks hotel yang Anda buat.

Dalam Azure AI Search, dokumen pencarian adalah struktur data yang merupakan input ke pengindeksan dan output dari kueri. Seperti yang diperoleh dari sumber data eksternal, input dokumen mungkin berupa baris dalam database, blob di Azure Blob Storage, atau dokumen JSON pada disk. Dalam contoh ini, Anda mengambil pintasan dan menyematkan dokumen JSON untuk empat hotel secara langsung.

Saat mengunggah dokumen, Anda harus menggunakan obyek IndexDocumentsBatch. Objek IndexDocumentsBatch berisi kumpulan IndexActions, yang masing-masing berisi dokumen dan properti yang memberi tahu Azure AI Search tindakan apa yang harus dilakukan (upload, gabungkan, hapus, dan mergeOrUpload).

Di App.java, Anda membuat array dokumen dan tindakan indeks, lalu meneruskan array ke IndexDocumentsBatch. Dokumen berikut sesuai dengan indeks hotel-quickstart, sebagaimana didefinisikan oleh kelas hotel.

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");
    }
}

Metode ini uploadDocuments membuat IndexDocumentsBatch dan memanggil indexDocuments pada SearchClient untuk mengunggah dokumen. Panduan cepat ini membangun SearchClient secara mandiri menggunakan SearchClientBuilder, yang memerlukan konfigurasi yang terpisah untuk endpoint dan kredensialnya.

uploadDocuments(searchClient);

Karena aplikasi konsol ini menjalankan semua perintah secara berurutan, kode menambahkan waktu tunggu dua detik antara pengindeksan dan kueri.

// 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)
{
}

Penundaan dua detik mengkompensasi pengindeksan, yang asinkron, sehingga semua dokumen dapat diindeks sebelum kueri dijalankan. Pemrograman dengan keterlambatan biasanya hanya diperlukan dalam demo, pengujian, dan aplikasi sampel.

Melakukan pencarian pada indeks

Anda bisa mendapatkan hasil kueri segera setelah dokumen pertama diindeks, tetapi pengujian aktual indeks Anda harus menunggu hingga semua dokumen diindeks.

Bagian ini menambahkan dua bagian fungsionalitas: logika dan hasil kueri. Untuk kueri, gunakan metode pencarian . Metode ini mengambil teks pencarian (string kueri) dan opsi lainnya.

Kelas SearchPagedIterable mewakili hasilnya.

Dalam App.java, metode WriteDocuments mencetak hasil pencarian ke konsol.

// 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();
}

Contoh kueri 1

Metode ini RunQueries menjalankan kueri dan mengembalikan hasil. Hasilnya merupakan objek Hotel. Sampel ini menunjukkan tanda tangan metode dan kueri pertama. Kueri ini menunjukkan Select parameter yang memungkinkan Anda menyusun hasil menggunakan bidang yang dipilih dari dokumen.

// 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));
}

Contoh kueri 2

Di kueri kedua, lakukan pencarian berdasarkan istilah, tambahkan filter yang memilih dokumen di mana Rating lebih besar dari 4, lalu urutkan Rating secara menurun. Filter adalah ekspresi boolean yang dievaluasi melalui bidang isFilterable dalam indeks. Filter kueri menyertakan atau mengecualikan nilai. Dengan demikian, tidak ada skor relevansi yang terkait dengan kueri filter.

// 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));

Contoh kueri 3

Kueri ketiga menunjukkan searchFields, digunakan untuk mencakup operasi pencarian teks lengkap ke bidang tertentu.

// 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));

Contoh kueri 4

Kueri keempat menunjukkan facets, yang dapat digunakan untuk menyusun struktur navigasi berfasis.

// 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));

Contoh kueri 5

Di permintaan kelima, kembalikan sebuah dokumen tertentu. Pencarian dokumen adalah respons umum terhadap peristiwa OnClick dalam set hasil.

// 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();

Contoh kueri 6

Kueri terakhir memperlihatkan sintaks untuk pelengkapan otomatis, mensimulasikan input pengguna parsial s yang menyelesaikan dua kemungkinan kecocokan dalam sourceFields yang terkait dengan pemberi saran yang Anda tentukan dalam indeks.

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

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

Ringkasan kueri

Permintaan sebelumnya memperlihatkan beberapa cara pencocokan istilah dalam permintaan:pencarian teks lengkap, filter, dan kelengkapan otomatis.

Metode SearchClient.search melakukan pencarian teks lengkap dan filter. Anda dapat meneruskan kueri pencarian dalam searchText string, saat Anda meneruskan ekspresi filter di properti filter kelas SearchOptions . Untuk memfilter tanpa mencari, cukup masukkan "*" untuk parameter searchText dari metode pencarian. Untuk mencari tanpa pemfilteran, biarkan properti filter tidak disetel, atau jangan melewatkan instans SearchOptions sama sekali.

Dalam panduan cepat ini, Anda menggunakan pustaka klien Azure AI Search untuk JavaScript untuk membuat, memuat, dan mengajukan kueri pada indeks pencarian untuk pencarian teks lengkap, juga dikenal sebagai pencarian kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Navigasikan ke folder quickstart.

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

  3. Di sample.env, ganti nilai tempat penampung untuk SEARCH_API_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ganti nama sample.env menjadi .env.

    mv sample.env .env

  5. Pasang dependensi.

    npm install

    Ketika penginstalan selesai, Anda akan melihat folder node_modules di direktori project.

  6. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

Menjalankan kode

Jalankan aplikasi.

node index.js

Keluaran

Outputnya harus mirip dengan yang berikut ini:

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

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat klien pencarian
  2. Membuat indeks pencarian
  3. Mengunggah dokumen ke indeks
  4. Melakukan pencarian pada indeks

Membuat klien pencarian

Di index.js, Anda membuat dua klien:

Kedua klien memerlukan titik akhir layanan dan kredensial untuk autentikasi. Dalam panduan cepat ini, Anda menggunakan DefaultAzureCredential untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

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

Membuat indeks pencarian

Panduan cepat ini membangun indeks hotel yang Anda muat dengan data hotel dan melakukan kueri terhadapnya. Dalam langkah ini, Anda mengimpor definisi indeks dari file JSON dan membuat indeks pada layanan pencarian Anda.

File hotels_quickstart_index.json menentukan skema indeks, termasuk bidang dan atributnya. Setiap bidang diidentifikasi oleh name dan memiliki type. Setiap bidang juga memiliki serangkaian atribut indeks yang menentukan apakah Azure AI Search dapat mencari, memfilter, mengurutkan, dan faset pada bidang . Sebagian besar bidang adalah jenis data sederhana, tetapi beberapa, seperti Address, adalah jenis kompleks yang memungkinkan Anda membuat struktur data yang kaya dalam indeks Anda. Anda dapat membaca selengkapnya tentang tipe data dan atribut indeks yang didukung yang dijelaskan dalam Create Index (REST).

Kode berikut mengimpor hotels_quickstart_index.json di bagian index.js atas sehingga fungsi utama dapat mengakses definisi indeks.

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

Panduan cepat ini menghapus indeks jika sudah ada, yang merupakan praktik yang umum dilakukan untuk kode pengujian/demo. Fungsi berikut mencoba menghapus indeks.

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

Kode berikut mengekstrak nama indeks dari definisi indeks dan meneruskan indexName bersama dengan indexClient ke fungsi deleteIndexIfExists().

const indexName = indexDefinition["name"];

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

Setelah itu, Anda membuat indeks dengan createIndex() metode .

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

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

Mengunggah dokumen ke indeks

Dalam Azure AI Search, dokumen adalah struktur data yang merupakan input ke pengindeksan dan output dari kueri. Anda dapat mendorong data tersebut ke indeks atau menggunakan pengindeks. Dalam panduan cepat ini, Anda menggunakan program untuk mengirim dokumen ke indeks.

Input dokumen dapat berupa baris dalam database, blob dalam Azure Blob Storage, atau dokumen JSON di disk, sebagaimana ditunjukkan dalam pendahuluan singkat ini. Mirip dengan indexDefinition, Anda mengimpor hotels.json di bagian atas dari index.js sehingga data dapat diakses dalam fungsi utama.

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

Untuk mengindeks data ke dalam indeks pencarian, Anda membuat SearchClient. Saat SearchIndexClient membuat dan mengelola indeks, SearchClient mengunggah dokumen dan mengkueri indeks.

Panduan memulai cepat ini mendapatkan SearchClient dari SearchIndexClient menggunakan getSearchClient, yang menggunakan kembali kredensial yang sama.

const searchClient = indexClient.getSearchClient(indexName);

Kode berikut mengunggah dokumen ke dalam indeks pencarian menggunakan mergeOrUploadDocuments() metode , yang mengunggah dokumen atau menggabungkannya dengan dokumen yang ada jika dokumen dengan kunci yang sama sudah ada.

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

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

Melakukan pencarian pada indeks

Dengan indeks dibuat dan dokumen diunggah, Anda siap untuk mengirim kueri ke indeks. Bagian ini mengirimkan lima kueri berbeda ke indeks pencarian untuk menunjukkan berbagai bagian fungsionalitas kueri yang tersedia untuk Anda.

Kueri ditulis dalam fungsi yang disebut sendQueries() dalam fungsi utama sebagai berikut:

await sendQueries(searchClient);

Metode search()searchClient mengirimkan kueri. Parameter pertama adalah teks pencarian dan parameter kedua menentukan opsi pencarian.

Contoh kueri 1

Kueri pertama menelusuri *, yang setara dengan menelusuri semua hal dan memilih tiga bidang di dalam indeks. Sebaiknya select hanya bidang yang Anda butuhkan karena mengambil data yang tidak diperlukan dapat meningkatkan latensi kueri Anda.

searchOptions untuk kueri ini juga telah includeTotalCount diatur ke true, yang mengembalikan jumlah hasil yang cocok yang ditemukan.

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
}

Kueri tersisa yang diuraikan di bawah ini juga harus ditambahkan ke fungsi sendQueries(). Mereka dipisahkan di sini untuk kemudahan membaca.

Contoh kueri 2

Kueri berikutnya menentukan istilah "wifi" pencarian dan menyertakan filter untuk hanya mengembalikan hasil di mana statusnya sama dengan 'FL'. Hasil juga diurutkan berdasarkan Rating Hotel. Filter adalah ekspresi boolean yang dievaluasi melalui bidang yang dapat difilter dalam indeks. Filter kueri menyertakan atau mengecualikan nilai. Dengan demikian, tidak ada skor relevansi yang terkait dengan kueri filter.

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)}`);
}

Contoh kueri 3

Kueri ketiga membatasi pencarian ke satu bidang yang dapat dicari menggunakan searchFields parameter . Pendekatan ini adalah opsi yang bagus untuk membuat kueri Anda lebih efisien jika Anda tahu bahwa Anda hanya tertarik pada kecocokan di bidang tertentu.

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)}`);
}

Contoh kueri 4

Opsi umum lain untuk disertakan dalam kueri adalah facets. Faset memungkinkan Anda membangun filter pada antarmuka pengguna (UI) Anda untuk memudahkan pengguna melihat nilai-nilai yang dapat mereka filter. Kueri ini juga membatasi pencarian ke HotelName bidang .

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)}`);
}

Contoh kueri 5

Kueri akhir menggunakan metode getDocument() dari searchClient. Ini memungkinkan Anda untuk secara efisien mengambil dokumen berdasarkan kuncinya.

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

Ringkasan kueri

Kueri sebelumnya memperlihatkan beberapa cara mencocokkan istilah dalam kueri: pencarian teks lengkap, filter, dan pencarian dokumen.

Metode ini searchClient.search mengadakan pencarian teks lengkap dan melakukan filter. Anda dapat meneruskan kueri pencarian dalam string searchText, sedangkan Anda meneruskan ekspresi filter di properti filter dalam kelas SearchOptions. Untuk memfilter tanpa mencari, cukup berikan "*" untuk parameter searchText dari metode search. Untuk mencari tanpa pemfilteran, biarkan properti filter tidak disetel, atau jangan melewatkan instans SearchOptions sama sekali.

Dalam panduan cepat ini, Anda menggunakan pustaka klien Azure AI Search untuk Python untuk membuat, memuat, dan menjalankan kueri pada indeks pencarian untuk mencari full-text (pencarian teks lengkap), juga dikenal sebagai pencarian kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Buka folder quickstart dan buka di Visual Studio Code.

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

  3. Buka azure-search-quickstart.ipynb.

  4. Tekan Ctrl+Shift+P, pilih Notebook: Pilih Notebook Kernel, dan ikuti perintah untuk membuat lingkungan virtual.

    Setelah selesai, Anda akan melihat folder .venv di direktori project.

  5. Jalankan sel kode pertama untuk menginstal paket yang diperlukan.

  6. Di sel kode kedua, ganti nilai tempat penampung untuk search_endpoint dengan URL yang Anda peroleh di Dapatkan titik akhir, dan jalankan sel.

  7. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

Menjalankan kode

Jalankan sel kode yang tersisa secara berurutan untuk membuat indeks, mengunggah dokumen, dan mengkueri indeks.

Keluaran

Setiap sel kode mencetak outputnya ke buku catatan. Contoh berikut adalah output kueri pertama, pencarian kosong yang mengembalikan semua dokumen dalam indeks.

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.

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat klien
  2. Membuat indeks pencarian
  3. Mengunggah dokumen ke indeks
  4. Melakukan pencarian pada indeks
  5. Menghapus indeks

Membuat klien

Buku catatan membuat dua klien:

Kedua klien memerlukan titik akhir layanan dan kredensial. Dalam panduan cepat ini, Anda menggunakan DefaultAzureCredential untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Membuat indeks pencarian

Quickstart ini membangun indeks hotel yang Anda isi dengan data hotel dan menjalankan kueri terhadapnya. Dalam langkah ini, Anda menentukan bidang dalam indeks. Setiap definisi bidang menyertakan nama, tipe data, dan atribut yang menentukan cara bidang digunakan.

Notebook menggunakan SimpleField, SearchableField, dan ComplexField dari paket model untuk menentukan skema. Anda dapat membaca selengkapnya tentang tipe data dan atribut indeks yang didukung yang dijelaskan dalam Create Index (REST).

# 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')

Mengunggah dokumen ke indeks

Azure AI Search mencari konten yang disimpan dalam layanan. Dalam langkah ini, Anda memuat dokumen JSON yang sesuai dengan indeks hotel yang Anda buat.

Dalam Azure AI Search, dokumen adalah struktur data yang merupakan input ke pengindeksan dan output dari kueri. Notebook mendefinisikan payload dokumen sebagai daftar kamus yang berisi data hotel.

# 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"
        }
    }
]

Metode upload_documents menambahkan dokumen ke indeks, membuatnya jika tidak ada atau memperbaruinya jika ada.

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)

Melakukan pencarian pada indeks

Anda bisa mendapatkan hasil kueri segera setelah dokumen pertama diindeks, tetapi pengujian aktual indeks Anda harus menunggu hingga semua dokumen diindeks.

search Gunakan metode SearchClient untuk menjalankan kueri.

Kueri sampel di notebook menunjukkan pola umum:

  • Pencarian kosong: Menjalankan pencarian kosong (search_text="*"), mengembalikan daftar yang tidak dirankit (skor pencarian = 1,0) dari dokumen arbitrer. Karena tidak ada kriteria, semua dokumen disertakan dalam hasil.

  • Pencarian istilah: Menambahkan seluruh istilah ke ekspresi pencarian (search_text="wifi"). Kueri ini menentukan bahwa hasil hanya berisi bidang-bidang tersebut dalam parameter select. Membatasi bidang yang kembali akan meminimalkan jumlah data yang dikirim kembali melalui kabel dan mengurangi latensi pencarian.

  • Pencarian yang difilter: Menambahkan ekspresi filter, hanya menampilkan hotel-hotel dengan peringkat yang lebih besar dari empat, diurutkan dalam urutan menurun.

  • Pencarian berbidang: Menambahkan search_fields untuk membatasi eksekusi kueri ke bidang tertentu.

  • Pencarian berfaset: Menghasilkan faset pada kecocokan positif yang ditemukan dalam hasil pencarian. Tidak ada kecocokan nol. Jika hasil pencarian tidak menyertakan istilah "wifi", maka "wifi" tidak muncul dalam struktur navigasi tersaring.

  • Pencarian dokumen: Mengembalikan dokumen berdasarkan kuncinya. Operasi ini berguna jika Anda ingin memberikan fungsi drillthrough saat pengguna memilih item dalam hasil pencarian.

  • Pelengkapan otomatis: Menyediakan kecocokan yang potensial saat pengguna mengetik ke dalam kotak pencarian. Pelengkapan otomatis menggunakan pemberi saran (sg) untuk mengetahui bidang mana yang berisi potensi kecocokan dengan permintaan pemberi saran. Dalam panduan memulai cepat ini, bidang tersebut adalah Tags, Address/City, dan Address/Country. Untuk mensimulasikan pelengkapan otomatis, berikan huruf "sa" sebagai string parsial. Metode autocompleteSearchClient mengembalikan kemungkinan kecocokan istilah.

Menghapus indeks

Jika Anda sudah selesai dengan indeks ini, Anda dapat menghapusnya dengan menjalankan Clean up sel kode. Menghapus indeks yang tidak perlu dapat mengosongkan ruang untuk menjalankan lebih banyak panduan cepat dan tutorial.

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

Dalam panduan mulai cepat ini, Anda menggunakan pustaka klien Azure AI Search untuk JavaScript (kompatibel dengan TypeScript) untuk membuat, mengisi, dan melakukan kueri pada indeks pencarian untuk pencarian teks lengkap, juga dikenal sebagai pencarian kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

  • Akun Azure dengan langganan aktif. Buat akun secara gratis.

  • Layanan Azure AI Search. Anda dapat menggunakan layanan gratis untuk panduan memulai cepat ini.

  • Node.js 20 LTS atau yang lebih baru untuk menjalankan kode yang dikompilasi.

  • TypeScript untuk mengkompilasi TypeScript ke JavaScript.

  • Git untuk mengkloning repositori sampel.

  • Azure CLI untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Navigasikan ke folder quickstart.

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

  3. Di sample.env, ganti nilai tempat penampung untuk SEARCH_API_ENDPOINT dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Ganti nama sample.env menjadi .env.

    mv sample.env .env

  5. Pasang dependensi.

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

    Ketika penginstalan selesai, Anda akan melihat folder node_modules di direktori project.

  6. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

Menjalankan kode

Kode sampel menggunakan JavaScript secara default. Untuk menjalankan kode dengan TypeScript:

  1. Buat file bernama tsconfig.json, lalu tempelkan kode berikut ke dalamnya.

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

  2. Ganti nama index.js file menjadi index.ts, lalu ganti konten dengan kode berikut. Kode ini mengonversi sintaks CommonJS ke impor modul ES, yang diperlukan untuk kompilasi TypeScript.

    // 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. Transpile dari TypeScript ke JavaScript.

    npx tsc

  4. Jalankan aplikasi.

    node index.js

Keluaran

Outputnya harus mirip dengan yang berikut ini:

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

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat klien pencarian
  2. Membuat indeks pencarian
  3. Mengunggah dokumen ke indeks
  4. Melakukan pencarian pada indeks

Membuat klien pencarian

Di index.ts, Anda membuat dua klien:

Kedua klien memerlukan titik akhir layanan dan kredensial untuk autentikasi. Dalam panduan cepat ini, Anda menggunakan DefaultAzureCredential untuk autentikasi tanpa kunci dengan Microsoft Entra ID.

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

Membuat indeks pencarian

Panduan cepat ini membangun indeks hotel yang Anda muat dengan data hotel dan melakukan kueri terhadapnya. Dalam langkah ini, Anda menentukan bidang dalam indeks.

Objek indexDefinition menentukan cara kerja Azure AI Search dengan dokumen yang Anda muat di langkah berikutnya. Setiap bidang diidentifikasi oleh name dan memiliki type. Setiap bidang juga memiliki serangkaian atribut indeks yang menentukan apakah Azure AI Search dapat mencari, memfilter, mengurutkan, dan faset pada bidang . Sebagian besar bidang adalah jenis data sederhana, tetapi beberapa, seperti Address, adalah jenis kompleks yang memungkinkan Anda membuat struktur data yang kaya dalam indeks Anda. Anda dapat membaca selengkapnya tentang tipe data dan atribut indeks yang didukung yang dijelaskan dalam Create Index (REST).

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"]
        }
    ]
};

Panduan cepat ini menghapus indeks jika sudah ada, yang merupakan praktik yang umum dilakukan untuk kode pengujian/demo.

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

Setelah itu, indeks dibuat dengan createIndex() metode .

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

Mengunggah dokumen ke indeks

Dalam Azure AI Search, dokumen adalah struktur data yang merupakan input ke pengindeksan dan output dari kueri. Anda dapat mendorong data tersebut ke indeks atau menggunakan pengindeks. Dalam panduan cepat ini, Anda menggunakan program untuk mengirim dokumen ke indeks.

Input dokumen dapat berupa baris dalam database, blob dalam Azure Blob Storage, atau dokumen JSON di disk, sebagaimana ditunjukkan dalam pendahuluan singkat ini. Data hotel diimpor di bagian atas file.

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

Untuk mengindeks data ke dalam indeks pencarian, Anda membuat SearchClient. Saat SearchIndexClient membuat dan mengelola indeks, SearchClient mengunggah dokumen dan mengkueri indeks.

Panduan memulai cepat ini mendapatkan SearchClient dari SearchIndexClient menggunakan getSearchClient, yang menggunakan kembali kredensial yang sama.

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

Metode mergeOrUploadDocuments() mengunggah dokumen atau menggabungkannya dengan dokumen yang sudah ada jika dokumen dengan kunci yang sama sudah ada.

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

Melakukan pencarian pada indeks

Dengan indeks dibuat dan dokumen diunggah, Anda siap untuk mengirim kueri ke indeks. Bagian ini mengirimkan lima kueri berbeda ke indeks pencarian untuk menunjukkan berbagai bagian fungsionalitas kueri yang tersedia untuk Anda.

Kueri ditulis dalam fungsi sendQueries() yang dipanggil di fungsi utama.

await sendQueries(searchClient);

Kueri dikirim menggunakan metode search()searchClient. Parameter pertama adalah teks pencarian dan parameter kedua menentukan opsi pencarian.

Contoh kueri 1

Kueri pertama mencari *, yang setara dengan mencari semuanya, dan memilih tiga bidang dalam indeks. Sebaiknya select hanya bidang yang Anda butuhkan karena mengambil data yang tidak diperlukan dapat meningkatkan latensi kueri Anda.

searchOptions untuk kueri ini juga telah includeTotalCount diatur ke true, yang mengembalikan jumlah hasil yang cocok yang ditemukan.

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}`);

Contoh kueri 2

Dalam kueri berikutnya, istilah pencarian "wifi" ditetapkan dengan filter agar hanya mengembalikan hasil di mana statusnya sama dengan 'FL'. Hasil juga diurutkan berdasarkan Rating Hotel.

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)}`);
}

Contoh kueri 3

Pencarian terbatas pada satu bidang yang dapat dicari menggunakan searchFields parameter . Pendekatan ini adalah opsi yang bagus untuk membuat kueri Anda lebih efisien jika Anda tahu bahwa Anda hanya tertarik pada kecocokan di bidang tertentu.

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)}`);
}

Contoh kueri 4

Opsi umum lain untuk disertakan dalam kueri adalah facets. Faset memungkinkan Anda melakukan penelusuran mandiri dari hasil di antarmuka pengguna Anda. Hasil faset dapat diubah menjadi kotak centang pada panel hasil.

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)}`);
}

Contoh kueri 5

Kueri akhir menggunakan metode getDocument() dari searchClient. Ini memungkinkan Anda untuk secara efisien mengambil dokumen berdasarkan kuncinya.

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

Ringkasan kueri

Kueri sebelumnya memperlihatkan beberapa cara mencocokkan istilah dalam kueri: pencarian teks lengkap, filter, dan pencarian dokumen.

Metode ini searchClient.search mengadakan pencarian teks lengkap dan melakukan filter. Anda dapat meneruskan kueri pencarian dalam string searchText, sedangkan Anda meneruskan ekspresi filter di properti filter dalam kelas SearchOptions. Untuk memfilter tanpa mencari, cukup berikan "*" untuk parameter searchText dari metode search. Untuk mencari tanpa pemfilteran, biarkan properti filter tidak disetel, atau jangan melewatkan instans SearchOptions sama sekali.

Dalam mulai cepat ini, Anda menggunakan REST API Azure AI Search untuk membuat, memuat, dan melakukan kueri pada indeks pencarian untuk pencarian teks lengkap, juga dikenal sebagai pencarian kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Buka folder quickstart dan buka di Visual Studio Code.

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

  3. Di az-search-quickstart.rest, ganti nilai tempat penampung untuk @baseUrl dengan URL yang Anda peroleh di Dapatkan titik akhir.

  4. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

  5. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, buat token akses.

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

  6. Ganti nilai placeholder untuk @token dengan token hasil dari langkah sebelumnya.

Menjalankan kode

  1. Di bawah ### List existing indexes by name, pilih Kirim Permintaan untuk memverifikasi koneksi Anda.

    Respons akan muncul di panel yang berdekatan. Jika Anda memiliki indeks yang sudah ada, indeks tersebut akan dicantumkan. Jika tidak, daftar kosong. Jika kode HTTP adalah 200 OK, Anda siap untuk melanjutkan.

  2. Kirim permintaan yang tersisa secara berurutan untuk membuat indeks, mengunggah dokumen, dan mengkueri indeks.

Keluaran

Setiap permintaan mengembalikan JSON yang berbeda berdasarkan operasi. Keluaran utamanya berasal dari ### Run a query, yang seharusnya terlihat serupa dengan berikut ini:

{
  "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"
      ]
    }
  ]
}

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat indeks pencarian
  2. Mengunggah dokumen ke indeks
  3. Melakukan pencarian pada indeks

Membuat indeks pencarian

Sebelum menambahkan konten ke Azure AI Search, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur. Indeks secara konseptual mirip dengan tabel dalam database relasional, tetapi dirancang khusus untuk operasi pencarian, seperti pencarian teks lengkap.

Panduan cepat ini memanggil Indeks - Buat (REST API) untuk membuat indeks pencarian bernama hotels-quickstart dan struktur data fisiknya di layanan pencarian Anda.

Dalam skema indeks, fields koleksi menentukan struktur dokumen hotel. Setiap bidang memiliki name, data type dan atribut yang menentukan perilakunya selama pengindeksan dan kueri. Bidang HotelId ditandai sebagai kunci, yang Azure AI Search perlu mengidentifikasi setiap dokumen secara unik dalam indeks.

### 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}
            ]
        }
    ]
}

Poin-poin penting tentang skema indeks:

  • Gunakan bidang string (Edm.String) untuk membuat data numerik teks lengkap dapat dicari. Jenis data lain yang didukung, seperti Edm.Int32, dapat difilter, dapat diurutkan, dapat difaset, dan dapat diambil tetapi tidak dapat dicari.

  • Sebagian besar bidang adalah jenis data sederhana, tetapi Anda dapat menentukan jenis kompleks untuk mewakili data berlapis, seperti Address bidang .

  • Atribut bidang menentukan tindakan yang diizinkan. REST API memungkinkan banyak tindakan secara default. Misalnya, semua string dapat dicari dan dapat diambil. Dengan REST API, Anda mungkin hanya menggunakan atribut jika Anda perlu menonaktifkan perilaku.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Azure AI Search, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kesederhanaan, panduan cepat ini menyediakan contoh dokumen hotel dalam format JSON sebaris. Namun, dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Mulai cepat ini memanggil Dokumen - Indeks (REST API) untuk menambahkan empat contoh dokumen hotel ke indeks Anda. Dibandingkan dengan permintaan sebelumnya, URI diperluas untuk menyertakan docs koleksi dan index operasi.

Setiap dokumen dalam value array mewakili hotel dan berisi bidang yang cocok dengan skema indeks. Parameter @search.action menentukan operasi yang akan dilakukan untuk setiap dokumen. Contoh ini menggunakan upload, yang menambahkan dokumen jika tidak ada atau memperbarui dokumen jika memang ada.

### 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"
            }
        }
    ]
}

Melakukan pencarian pada indeks

Setelah dokumen dimuat ke dalam indeks, Anda dapat menggunakan pencarian teks lengkap untuk menemukan istilah atau frasa tertentu dalam bidangnya.

Panduan cepat ini menggunakan Dokumen - Pos Pencarian (REST API) untuk menemukan dokumen hotel yang sesuai dengan kriteria pencarian Anda. URI sekarang menargetkan operasi /docs/search.

Permintaan pencarian teks lengkap selalu menyertakan search parameter yang berisi teks kueri. Teks kueri dapat menyertakan satu atau beberapa istilah, frasa, atau operator. Selain search, Anda dapat menentukan parameter lain untuk menyempurnakan perilaku dan hasil pencarian.

Kueri mencari istilah "restoran terlampir" di bidang Description dan Tags dari setiap dokumen hotel. Parameter select membatasi bidang yang dikembalikan dalam respons terhadap HotelId, , HotelNameTags, dan Description. Parameter count meminta jumlah total dokumen yang cocok.

### 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
}

Dalam panduan cepat ini, Anda menggunakan PowerShell dan Azure AI Search REST API untuk membuat, memuat, dan melakukan kueri indeks pencarian untuk pencarian teks lengkap, juga dikenal sebagai pencarian kata kunci.

Pencarian teks lengkap menggunakan Apache Lucene untuk pengindeksan dan kueri dan algoritma peringkat BM25 untuk hasil penilaian. Panduan memulai cepat ini menggunakan data hotel fiksi dari repositori GitHub azure-search-sample-data untuk populasi indeks.

Petunjuk / Saran

Ingin segera memulai? Unduh kode source di GitHub.

Prasyarat

Mengonfigurasi akses

Sebelum memulai, pastikan Anda memiliki izin untuk mengakses konten dan operasi di Azure AI Search. Mulai cepat ini menggunakan Microsoft Entra ID untuk autentikasi dan akses berbasis peran untuk otorisasi. Anda harus menjadi Pemilik atau Administrator Akses Pengguna untuk menetapkan peran. Jika fungsi peran tidak dapat digunakan, gunakan autentikasi berbasis kunci sebagai gantinya.

Untuk mengonfigurasi akses berbasis peran yang direkomendasikan:

  1. Aktifkan akses berbasis peran untuk layanan pencarian Anda.

  2. Tetapkan peran berikut ke akun pengguna Anda.

    • Kontributor Layanan Pencarian

    • Kontributor Data Indeks Pencarian

    • Pembaca Data Indeks Pencarian

Dapatkan titik akhir

Setiap layanan Azure AI Search memiliki endpoint, yang merupakan URL unik yang mengidentifikasi dan menyediakan akses jaringan ke layanan. Di bagian selanjutnya, Anda menentukan titik akhir ini untuk menyambungkan ke layanan pencarian Anda secara terprogram.

Untuk mendapatkan titik akhir:

  1. Buka layanan pencarian Anda di portal Microsoft Azure.

  2. Dari panel kiri, pilih Gambaran Umum.

  3. Catat titik akhir, yang akan terlihat seperti https://my-service.search.windows.net.

Menyiapkan lingkungan kerja

  1. Gunakan Git untuk mengkloning repositori sampel.

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

  2. Navigasikan ke folder quickstart.

    cd azure-search-powershell-samples/Quickstart

  3. Untuk autentikasi tanpa kunci dengan Microsoft Entra ID, masuk ke akun Azure Anda. Jika Anda memiliki beberapa langganan, pilih langganan yang berisi layanan Azure AI Search Anda.

    az login

  4. Di azure-search-quickstart.ps1, ganti nilai tempat penampung untuk $baseUrl dengan URL yang Anda peroleh di Dapatkan titik akhir.

Menjalankan kode

Di terminal yang sama, jalankan skrip PowerShell berikut untuk menjalankan mulai cepat ini.

.\azure-search-quickstart.ps1

Keluaran

Skrip menghapus indeks yang ada, membuat indeks baru, mengunggah dokumen, dan menjalankan beberapa kueri pencarian teks lengkap. Output menunjukkan permintaan dan respons HTTP lengkap untuk setiap operasi. Contoh berikut menunjukkan respons saat mencari "wifi restoran".

{
  "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"]
    }
  ]
}

Memahami kode

Nota

Cuplikan kode di bagian ini mungkin telah dimodifikasi untuk keterbacaan. Untuk contoh kerja lengkap, lihat kode sumber.

Sekarang setelah Anda menjalankan kode, mari kita uraikan langkah-langkah kunci:

  1. Membuat indeks pencarian
  2. Mengunggah dokumen ke indeks
  3. Melakukan pencarian pada indeks

Membuat indeks pencarian

Sebelum menambahkan konten ke Azure AI Search, Anda harus membuat indeks untuk menentukan bagaimana konten disimpan dan terstruktur. Indeks secara konseptual mirip dengan tabel dalam database relasional, tetapi dirancang khusus untuk operasi pencarian, seperti pencarian teks lengkap.

Panduan memulai cepat ini pertama-tama menghapus indeks yang sudah ada dengan nama yang sama, yang merupakan praktik umum untuk kode pengujian/demo yang dijalankan berulang kali.

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

Mulai cepat ini kemudian memanggil Indeks - Buat (REST API) untuk membangun indeks pencarian bernama hotels-quickstart dan struktur data fisiknya di layanan pencarian Anda.

$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

Dalam skema indeks, fields koleksi menentukan struktur dokumen hotel. Setiap bidang memiliki name, data type dan atribut yang menentukan perilakunya selama pengindeksan dan kueri. Bidang HotelId ditandai sebagai kunci, yang Azure AI Search perlu mengidentifikasi setiap dokumen secara unik dalam indeks.

Poin-poin penting tentang skema indeks:

  • Gunakan bidang string (Edm.String) untuk membuat data numerik teks lengkap dapat dicari. Jenis data lain yang didukung, seperti Edm.Int32, dapat difilter, dapat diurutkan, dapat difaset, dan dapat diambil tetapi tidak dapat dicari.

  • Sebagian besar bidang adalah jenis data sederhana, tetapi Anda dapat menentukan jenis kompleks untuk mewakili data berlapis, seperti Address bidang .

  • Atribut bidang menentukan tindakan yang diizinkan. REST API memungkinkan banyak tindakan secara default. Misalnya, semua string dapat dicari dan dapat diambil. Dengan REST API, Anda mungkin hanya menggunakan atribut jika Anda perlu menonaktifkan perilaku.

Mengunggah dokumen ke indeks

Indeks yang baru dibuat kosong. Untuk mengisi indeks dan membuatnya dapat dicari, Anda harus mengunggah dokumen JSON yang sesuai dengan skema indeks.

Dalam Azure AI Search, dokumen berfungsi sebagai input untuk pengindeksan dan output untuk kueri. Untuk kesederhanaan, panduan cepat ini menyediakan contoh dokumen hotel dalam format JSON sebaris. Namun, dalam skenario produksi, konten sering ditarik dari sumber data yang terhubung dan diubah menjadi JSON menggunakan pengindeks.

Mulai cepat ini memanggil Dokumen - Indeks (REST API) untuk menambahkan empat contoh dokumen hotel ke indeks Anda. Dibandingkan dengan permintaan sebelumnya, URI diperluas untuk menyertakan docs koleksi dan index operasi.

$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

Setiap dokumen dalam value array mewakili hotel dan berisi bidang yang cocok dengan skema indeks. Parameter @search.action menentukan operasi yang akan dilakukan untuk setiap dokumen. Contoh ini menggunakan upload, yang menambahkan dokumen jika tidak ada atau memperbarui dokumen jika memang ada.

Melakukan pencarian pada indeks

Setelah dokumen dimuat ke dalam indeks, Anda dapat menggunakan pencarian teks lengkap untuk menemukan istilah atau frasa tertentu dalam bidangnya.

Panduan cepat ini menggunakan Dokumen - Pos Pencarian (REST API) untuk menemukan dokumen hotel yang sesuai dengan kriteria pencarian Anda. URI menargetkan operasi /docs/search.

Permintaan pencarian teks lengkap menyertakan search parameter dengan teks kueri, yang dapat berisi istilah, frasa, atau operator. Kueri mencari di semua bidang yang dapat dicari di setiap dokumen. Contoh berikut menunjukkan pola kueri umum.

Contoh kueri 1

Kueri berikut mencari istilah "wifi restoran" di semua bidang yang dapat dicari. Secara default, Azure AI Search mengembalikan dokumen yang cocok dengan salah satu istilah pencarian.

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

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

Parameter select membatasi bidang yang dikembalikan dalam respons terhadap HotelName, Description, dan Tags.

Contoh kueri 2

Kueri berikut menggunakan filter ekspresi untuk mengembalikan hanya hotel dengan peringkat lebih besar dari 4.

$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

Parameter search diatur ke *, yang cocok dengan semua dokumen. Parameter filter menerapkan kondisi Boolean untuk mempersempit hasilnya.

Contoh kueri 3

Kueri berikut mencari "butik" dan menggunakan top untuk mengembalikan hanya dua hasil pertama.

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

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

Contoh kueri 4

Kueri berikut mencari "kolam" dan menggunakan orderby untuk mengurutkan hasil menurut Rating dalam urutan menurun.

$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

Membersihkan sumber daya

Saat Anda bekerja di langganan Anda sendiri, ada baiknya untuk menyelesaikan proyek dengan menghapus sumber daya yang tidak lagi Anda butuhkan. Sumber daya yang dibiarkan berjalan dapat dikenakan biaya.

Di portal Azure, pilih Semua sumber daya atau Kelompok sumber daya dari panel kiri untuk menemukan dan mengelola sumber daya. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus semua sumber daya sekaligus.

Jika Anda menggunakan layanan pencarian gratis, ingatlah bahwa Anda terbatas pada tiga indeks, pengindeks, dan sumber data. Anda dapat menghapus item individual di portal agar tetap di bawah batas.

Konten terkait

  • Last updated on