Mulai cepat: Membuat indeks pencarian di PowerShell dengan menggunakan REST API

Artikel
03/27/2024

Dalam mulai cepat Pencarian Azure AI ini, pelajari cara membuat, memuat, dan mengkueri indeks pencarian dengan menggunakan PowerShell dan REST API Azure AI Search. Artikel ini menjelaskan cara menjalankan perintah PowerShell secara interaktif. Sebagai alternatif, Anda dapat mengunduh dan menjalankan skrip PowerShell yang melakukan operasi yang sama.

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

Prasyarat

Layanan dan alat berikut diperlukan untuk mulai cepat ini:

PowerShell 7.3 atau yang lebih baru, menggunakan Invoke-RestMethod untuk langkah-langkah berurutan dan interaktif.
Buat azure AI layanan Pencarian atau temukan layanan yang sudah ada di bawah langganan Anda saat ini. Anda dapat menggunakan layanan gratis untuk mulai cepat ini.

Menyalin kunci layanan pencarian dan URL

Dalam mulai cepat ini, panggilan REST menyertakan URL layanan dan kunci akses pada setiap permintaan. Layanan pencarian dibuat dengan keduanya, jadi jika Anda menambahkan Azure AI Search ke langganan Anda, ikuti langkah-langkah ini untuk mendapatkan informasi yang diperlukan.

Masuk ke portal Azure. Pada halaman Gambaran Umum layanan pencarian Anda, dapatkan URL. Contoh titik akhir mungkin terlihat sepertihttps://mydemo.search.windows.net.
Pilih Pengaturan> Keys lalu dapatkan kunci admin untuk hak penuh pada layanan. Dua kunci admin yang dapat dipertukarkan disediakan untuk kelangsungan bisnis jika Anda perlu melakukan rollover. Anda dapat menggunakan kunci utama atau sekunder pada permintaan untuk menambahkan, memodifikasi, dan menghapus objek.

Semua permintaan memerlukan kunci API pada setiap permintaan yang dikirim ke layanan Anda. Memiliki kunci yang valid menetapkan kepercayaan, berdasarkan per permintaan, antara aplikasi yang mengirim permintaan dan layanan yang menanganinya.

Koneksi ke Azure AI Search

Di PowerShell, buat $headers objek untuk menyimpan jenis konten dan kunci API. Ganti kunci API admin (YOUR-ADMIN-API-KEY) dengan kunci yang valid untuk layanan pencarian Anda. Anda hanya perlu mengatur header ini sekali selama durasi sesi, tetapi Anda menambahkannya ke setiap permintaan.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Buat $url objek yang menentukan koleksi indeks layanan. Ganti nama layanan (YOUR-SEARCH-SERVICE-NAME) dengan layanan pencarian yang valid.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Jalankan Invoke-RestMethod untuk mengirim permintaan GET ke layanan dan verifikasi koneksi. Tambahkan ConvertTo-Json sehingga Anda dapat melihat respons yang dikirim kembali dari layanan.
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Jika layanan kosong dan tidak memiliki indeks, hasilnya akan mirip dengan contoh berikut. Jika tidak, Anda akan melihat representasi JSON dari definisi indeks.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Buat indeks

Kecuali Anda menggunakan portal, indeks harus ada di layanan sebelum Anda dapat memuat data. Langkah ini mendefinisikan indeks dan mendorongnya ke layanan. Buat REST API Indeks digunakan untuk langkah ini.

Elemen indeks yang diperlukan mencakup nama dan koleksi bidang. Kumpulan bidang menentukan struktur dokumen. Setiap bidang memiliki nama, jenis, dan atribut yang menentukan bagaimana bidang digunakan (misalnya, apakah teks lengkap dapat dicari, dapat difilter, atau diambil dalam hasil pencarian). Dalam indeks, salah satu bidang jenis Edm.String harus ditetapkan sebagai kunci untuk identitas dokumen.

Indeks ini diberi nama hotels-quickstart dan memiliki definisi bidang yang Anda lihat dalam kode berikut. Ini adalah subset dari indeks Hotel yang lebih besar yang digunakan dalam artikel panduan lainnya. Definisi bidang dipangkas dalam mulai cepat ini untuk brevity.

Tempelkan contoh ini ke PowerShell untuk membuat $body objek yang berisi skema indeks.

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

Atur URI ke koleksi indeks pada layanan Anda dan hotels-quickstart indeks.

$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart?api-version=2023-11-01"

Jalankan perintah dengan $url, $headers, dan $body untuk membuat indeks pada layanan.

Invoke-RestMethod -Uri $url -Headers $headers -Method Put -Body $body | ConvertTo-Json

Hasilnya akan terlihat mirip dengan contoh ini, yang hanya menunjukkan dua bidang pertama untuk brevity:

{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes/$entity",
    "@odata.etag":  "\"0x8D6EDE28CFEABDA\"",
    "name":  "hotels-quickstart",
    "defaultScoringProfile":  null,
    "fields":  [
                {
                    "name":  "HotelId",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  true,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  true,
                    "key":  true,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                {
                    "name":  "HotelName",
                    "type":  "Edm.String",
                    "searchable":  true,
                    "filterable":  false,
                    "retrievable":  true,
                    "sortable":  true,
                    "facetable":  false,
                    "key":  false,
                    "indexAnalyzer":  null,
                    "searchAnalyzer":  null,
                    "analyzer":  null,
                    "synonymMaps":  ""
                },
                . . .
    ]
}

Tip

Untuk verifikasi, Anda juga dapat memeriksa daftar Indeks di portal.

Muat dokumen

Untuk mendorong dokumen, gunakan permintaan HTTP POST ke titik akhir URL indeks Anda. REST API untuk tugas ini adalah Tambahkan, Perbarui, atau Hapus Dokumen.

Tempelkan contoh ini ke PowerShell untuk membuat $body objek yang berisi dokumen yang ingin Anda unggah.

Permintaan ini mencakup dua rekaman lengkap dan satu rekaman parsial. Rekaman parsial menunjukkan bahwa Anda dapat mengunggah dokumen yang tidak lengkap. Parameter @search.action menentukan bagaimana pengindeksan dilakukan. Nilai yang valid meliputi upload, merge, mergeOrUpload, dan delete. Perilaku mergeOrUpload membuat dokumen baru untuk hotelId = 3 atau memperbarui konten jika sudah ada.

$body = @"
{
    "value": [
    {
    "@search.action": "upload",
    "HotelId": "1",
    "HotelName": "Secret Point Motel",
    "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": "Twin Dome Motel",
    "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": "Triple 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 Cliff Hotel",
    "Description": "Sublime Cliff 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 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"
        }
    }
]
}
"@

Atur titik akhir ke hotels-quickstart koleksi dokumen dan sertakan operasi indeks (indexes/hotels-quickstart/docs/index).

$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"

Jalankan perintah dengan $url, $headers, dan $body untuk memuat dokumen ke hotels-quickstart dalam indeks.

Invoke-RestMethod -Uri $url -Headers $headers -Method Post -Body $body | ConvertTo-Json

Hasil akan terlihat serupa dengan contoh berikut. Anda akan melihat kode status 201.

{
    "@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#Collection(Microsoft.Azure.Search.V2019_05_06.IndexResult)",
    "value":  [
                {
                    "key":  "1",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "2",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "3",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                },
                {
                    "key":  "4",
                    "status":  true,
                    "errorMessage":  null,
                    "statusCode":  201
                }
            ]
}

Mencari indeks

Langkah ini memperlihatkan kepada Anda cara mengkueri indeks dengan menggunakan SEARCH Documents API.

Pastikan untuk menggunakan tanda kutip tunggal pada pencarian $urls. String kueri menyertakan $ karakter, dan Anda dapat menghilangkannya jika seluruh string diapit dalam tanda kutip tunggal.

Atur titik akhir ke hotels-quickstart koleksi dokumen dan tambahkan search parameter untuk meneruskan string kueri.

String ini menjalankan pencarian kosong (search=*), mengembalikan daftar yang tidak tertangani (skor pencarian = 1,0) dari dokumen arbitrer. Secara default, Azure AI Search mengembalikan 50 kecocokan dalam satu waktu. Sebagai terstruktur, kueri ini mengembalikan seluruh struktur dan nilai dokumen. Tambahkan $count=true untuk mendapatkan hitungan semua dokumen dalam hasil.
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

Jalankan perintah untuk mengirim ke $url layanan.

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

Anda akan melihat hasil yang mirip dengan output berikut:

{
"@odata.context":  "https://mydemo.search.windows.net/indexes(\u0027hotels-quickstart\u0027)/$metadata#docs(*)",
"@odata.count":  4,
"value":  [
              {
                  "@search.score":  0.1547872,
                  "HotelId":  "2",
                  "HotelName":  "Twin Dome Motel",
                  "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.6,
                  "Address":  "@{StreetAddress=140 University Town Center Dr; City=Sarasota; StateProvince=FL; PostalCode=34243; Country=USA}"
              },
              {
                  "@search.score":  0.009068266,
                  "HotelId":  "3",
                  "HotelName":  "Triple 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\u0027s restaurant services.",
                  "Category":  "Resort and Spa",
                  "Tags":  "air conditioning bar continental breakfast",
                  "ParkingIncluded":  true,
                  "LastRenovationDate":  "2015-09-20T00:00:00Z",
                  "Rating":  4.8,
                  "Address":  "@{StreetAddress=3393 Peachtree Rd; City=Atlanta; StateProvince=GA; PostalCode=30326; Country=USA}"
              },
            . . .
    ]
}

Coba beberapa contoh kueri lainnya untuk memahami sintaksnya. Anda dapat melakukan pencarian string, kueri verbatim $filter , membatasi kumpulan hasil, mencakup pencarian ke bidang tertentu, dan banyak lagi.

# Query example 1
# Search the entire index for the terms 'restaurant' and 'wifi'
# Return only the HotelName, Description, and Tags fields
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=restaurant wifi&$count=true&$select=HotelName,Description,Tags'

# Query example 2 
# Apply a filter to the index to find hotels rated 4 or higher
# Returns the HotelName and Rating. Two documents match.
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$filter=Rating gt 4&$select=HotelName,Rating'

# Query example 3
# Take the top two results, and show only HotelName and Category in the results
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=boutique&$top=2&$select=HotelName,Category'

# Query example 4
# Sort by a specific field (Address/City) in ascending order

$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating'

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 dengan menggunakan tautan Semua sumber daya atau Grup sumber daya di panel paling kiri.

Jika Anda menggunakan layanan gratis, ingatlah bahwa Anda terbatas pada tiga indeks, pengindeks, dan sumber data. Anda dapat menghapus item individu di portal agar tetap berada dalam batasan.

Langkah berikutnya

Dalam mulai cepat ini, Anda menggunakan PowerShell untuk menelusuri alur kerja dasar untuk membuat dan mengakses konten di Azure AI Search. Dengan mempertimbangkan konsep, kami sarankan Anda beralih ke skenario yang lebih canggih, seperti pengindeksan dari sumber data Azure:

Tutorial REST: Mengindeks dan mencari data semi terstruktur (blob JSON) di Azure AI Search