Bagikan melalui

Mulai cepat: Pencarian kata kunci dengan menggunakan REST

  • Artikel

REST API di Azure AI Search menyediakan akses terprogram ke semua kemampuannya, termasuk fitur pratinjau, dan merupakan cara mudah untuk mempelajari cara kerja fitur. Dalam mulai cepat ini, pelajari cara memanggil REST API Pencarian untuk membuat, memuat, dan mengkueri indeks pencarian di Azure AI Search.

Jika Anda tidak memiliki langganan Azure, buat akun gratis sebelum Anda memulai.

Prasyarat

Mengunduh file

Unduh sampel REST dari GitHub untuk mengirim permintaan dalam mulai cepat ini. Instruksi dapat ditemukan di Mengunduh file dari GitHub.

Anda juga dapat memulai file baru di sistem lokal Anda dan membuat permintaan secara manual dengan menggunakan instruksi dalam artikel ini.

Mendapatkan titik akhir layanan pencarian

Anda dapat menemukan titik akhir layanan pencarian di portal Azure.

  1. Masuk ke portal Azure dan temukan layanan pencarian Anda.

  2. Pada beranda Gambaran Umum , temukan URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.

    Cuplikan layar properti URL pada halaman gambaran umum.

Anda menempelkan titik akhir ini ke .rest dalam file atau .http di langkah selanjutnya.

Mengonfigurasi akses

Permintaan ke titik akhir pencarian harus diautentikasi dan diotorisasi. Anda dapat menggunakan kunci atau peran API untuk tugas ini. Kunci lebih mudah dimulai, tetapi perannya lebih aman.

Untuk koneksi berbasis peran, instruksi berikut meminta Anda menyambungkan ke Azure AI Search di bawah identitas Anda, bukan identitas aplikasi klien.

Opsi 1: Gunakan kunci

Pilih Kunci Pengaturan>lalu salin kunci admin. Kunci admin digunakan untuk menambahkan, memodifikasi, dan menghapus objek. Ada dua kunci admin yang dapat dipertukarkan. Salin salah satu. Untuk informasi selengkapnya, lihat Menyambungkan ke Azure AI Search menggunakan autentikasi kunci.

Cuplikan layar yang memperlihatkan kunci API di portal Azure.

Anda menempelkan kunci ini ke .rest dalam file atau .http di langkah selanjutnya.

Opsi 2: Gunakan peran

Pastikan layanan pencarian Anda dikonfigurasi untuk akses berbasis peran. Anda harus memiliki penetapan peran yang telah dikonfigurasi sebelumnya untuk akses pengembang. Penetapan peran Anda harus memberikan izin untuk membuat, memuat, dan mengkueri indeks pencarian.

Di bagian ini, dapatkan token identitas pribadi Anda menggunakan Azure CLI, Azure PowerShell, atau portal Azure.

  1. Masuk ke Azure CLI.

    az login

  2. Dapatkan token identitas pribadi Anda.

    az account get-access-token --scope https://search.azure.com/.default

Anda menempelkan token identitas pribadi Anda ke .rest dalam file atau .http di langkah selanjutnya.

Catatan

Bagian ini mengasumsikan Anda menggunakan klien lokal yang tersambung ke Azure AI Search atas nama Anda. Pendekatan alternatif adalah mendapatkan token untuk aplikasi klien, dengan asumsi aplikasi Anda terdaftar dengan ID Microsoft Entra.

Menyiapkan Visual Studio Code

Jika Anda tidak terbiasa dengan klien REST untuk Visual Studio Code, bagian ini menyertakan penyiapan sehingga Anda dapat menyelesaikan tugas dalam mulai cepat ini.

  1. Mulai Visual Studio Code dan pilih petak ekstensi .

  2. Cari klien REST dan pilih Instal.

    Cuplikan layar yang memperlihatkan tombol Instal klien REST.

  3. Buka atau buat file baru bernama dengan .rest ekstensi file atau .http .

  4. Tempelkan dalam contoh berikut jika Anda menggunakan kunci API. @baseUrl Ganti tempat penampung dan @apiKey dengan nilai yang Anda salin sebelumnya, tanpa tanda kutip.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@apiKey = PUT-YOUR-SEARCH-SERVICE-API-KEY-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. Atau, tempelkan dalam contoh ini jika Anda menggunakan peran. @baseUrl Ganti tempat penampung dan @token dengan nilai yang Anda salin sebelumnya, tanpa tanda kutip.

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

 ### List existing indexes by name
 GET  {{baseUrl}}/indexes?api-version=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  6. Pilih Kirim Permintaan. 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 langkah-langkah berikutnya.

    Cuplikan layar yang memperlihatkan klien REST yang dikonfigurasi untuk permintaan layanan pencarian.

    Jika Anda mendapatkan WWW-Authenticate: Bearer realm="Azure Cognitive Search" error="invalid_token" error_description="Authentication token failed validation.", hapus tanda kutip di sekitar token, simpan file, dan coba lagi permintaan Anda.

    Poin utama:

    • Parameter ditentukan dengan menggunakan awalan @ .
    • ### menunjuk panggilan REST. Baris berikutnya berisi permintaan, yang harus menyertakan HTTP/1.1.
    • Send request akan muncul di atas permintaan.

Buat indeks

Tambahkan permintaan kedua ke file Anda .rest . Buat Indeks (REST) membuat indeks pencarian dan menyiapkan struktur data fisik di layanan pencarian Anda.

  1. Tempelkan dalam contoh berikut untuk membuat hotels-quickstart indeks di layanan pencarian Anda.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2024-07-01  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}
                ]
            }
        ]
    }

  2. Pilih Kirim Permintaan. Anda harus memiliki HTTP/1.1 201 Created respons dan isi respons harus menyertakan representasi JSON dari skema indeks.

    Jika Anda mendapatkan Header name must be a valid HTTP token ["{"] kesalahan, pastikan ada baris kosong antara api-key dan isi permintaan. Jika Anda mendapatkan HTTP 504, verifikasi bahwa URL menentukan HTTPS. Jika Anda melihat HTTP 400 atau 404, periksa isi permintaan untuk memverifikasi tidak ada kesalahan salin-tempel. HTTP 403 biasanya menunjukkan masalah dengan kunci API. Ini adalah kunci yang tidak valid atau masalah sintaks dengan bagaimana kunci API ditentukan.

    Anda sekarang memiliki beberapa permintaan dalam file Anda. Ingat bahwa ### memulai permintaan baru dan setiap permintaan berjalan secara independen.

    Cuplikan layar yang memperlihatkan klien REST dengan beberapa permintaan.

Tentang definisi indeks

Dalam skema indeks, kumpulan bidang menentukan struktur dokumen. Setiap dokumen yang Anda unggah harus memiliki bidang ini. Setiap bidang harus ditetapkan ke jenis data Model Data Entitas (EDM). Bidang string digunakan dalam pencarian teks lengkap. Jika Anda ingin data numerik dapat dicari, pastikan jenis datanya adalah Edm.String. Jenis data lain seperti Edm.Int32 dapat difilter, dapat diurutkan, dapat difaset, dan dapat diambil tetapi tidak dapat dicari teks lengkap.

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

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

Muat dokumen

Membuat dan memuat indeks adalah langkah-langkah terpisah. Di Pencarian Azure AI, indeks berisi semua data dan kueri yang dapat dicari yang dijalankan pada layanan pencarian. Untuk panggilan REST, data disediakan sebagai dokumen JSON. Gunakan Dokumen- Indeks REST API untuk tugas ini.

URI diperluas untuk menyertakan docs koleksi dan index operasi.

  1. Tempelkan contoh berikut untuk mengunggah dokumen JSON ke indeks pencarian.

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

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "Description": "The hotel is ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Time's 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": [ "pool", "air conditioning", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1970-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.",
        "Category": "Boutique",
        "Tags": [ "pool", "free wifi", "concierge" ],
        "ParkingIncluded": false,
        "LastRenovationDate": "1979-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 Hotel stands out for its gastronomic excellence under the management of William Dough, who advises on and oversees all of the Hotel’s restaurant services.",
        "Category": "Resort and Spa",
        "Tags": [ "air conditioning", "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 Palace is part of a lovingly restored 1800 palace.",
        "Category": "Boutique",
        "Tags": [ "concierge", "view", "24-hour front desk service" ],
        "ParkingIncluded": true,
        "LastRenovationDate": "1960-02-06T00:00:00Z",
        "Rating": 4.60,
        "Address": 
            {
            "StreetAddress": "7400 San Pedro Ave",
            "City": "San Antonio",
            "StateProvince": "TX",
            "PostalCode": "78216",
            "Country": "USA"
            }
        }
      ]
    }

  2. Pilih Kirim Permintaan. Dalam beberapa detik, Anda akan melihat respons HTTP 201 di panel yang berdekatan.

    Jika Anda mendapatkan 207, setidaknya satu dokumen gagal diunggah. Jika Anda mendapatkan 404, Anda memiliki kesalahan sintaks di header atau isi permintaan. Verifikasi bahwa Anda mengubah titik akhir untuk menyertakan /docs/index.

Jalankan Kueri

Setelah dokumen dimuat, Anda dapat mengeluarkan kueri terhadapnya dengan menggunakan Dokumen - Pos Pencarian (REST).

URI diperluas untuk menyertakan ekspresi kueri, yang ditentukan dengan menggunakan /docs/search operator.

  1. Tempelkan dalam contoh berikut untuk mengkueri indeks pencarian. Lalu pilih Kirim permintaan. Permintaan pencarian teks selalu menyertakan search parameter. Contoh ini mencakup parameter opsional searchFields yang membatasi pencarian teks ke bidang tertentu.

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

  {
      "search": "lake view",
      "select": "HotelId, HotelName, Tags, Description",
      "searchFields": "Description, Tags",
      "count": true
  }

  2. Tinjau respons di panel yang berdekatan. Anda harus memiliki hitungan yang menunjukkan jumlah kecocokan yang ditemukan dalam indeks, skor pencarian yang menunjukkan relevansi, dan nilai untuk setiap bidang yang select tercantum dalam pernyataan.

    {
  "@odata.context": "https://my-demo.search.windows.net/indexes('hotels-quickstart')/$metadata#docs(*)",
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 0.6189728,
      "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 Palace is part of a lovingly restored 1800 palace.",
      "Tags": [
        "concierge",
        "view",
        "24-hour front desk service"
      ]
    }
  ]
}

Dapatkan properti indeks

Anda juga bisa menggunakan Dapatkan Statistik untuk mengkueri jumlah dokumen dan ukuran indeks.

  1. Tempelkan dalam contoh berikut untuk mengkueri indeks pencarian. Lalu pilih Kirim permintaan.

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  2. Tinjau responsnya. Operasi ini adalah cara mudah untuk mendapatkan detail tentang penyimpanan indeks.

    {
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

Membersihkan sumber daya

Saat bekerja dengan langganan Anda sendiri, sebaiknya identifikasi apakah Anda masih membutuhkan sumber daya yang Anda buat di akhir proyek. Sumber daya yang dibiarkan berjalan dapat menghabiskan uang Anda. Anda dapat menghapus sumber daya satu per satu atau menghapus grup sumber daya untuk menghapus seluruh rangkaian sumber daya.

Anda dapat menemukan dan mengelola sumber daya di portal Azure dengan menggunakan tautan Semua sumber daya atau Grup sumber daya di panel paling kiri.

Anda juga dapat mencoba perintah ini DELETE :

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Langkah selanjutnya

Sekarang setelah Anda terbiasa dengan klien REST dan melakukan panggilan REST ke Azure AI Search, coba mulai cepat lain yang menunjukkan dukungan vektor.

Mulai cepat: Pencarian vektor menggunakan REST