Hızlı Başlangıç: REST API'lerini kullanarak PowerShell'de arama dizini oluşturma

Makale
03/27/2024

Bu Azure AI Search hızlı başlangıcında PowerShell ve Azure AI Search REST API'lerini kullanarak arama dizini oluşturmayı, yüklemeyi ve sorgulamayı öğrenin. Bu makalede PowerShell komutlarının etkileşimli olarak nasıl çalıştırılacakları açıklanmaktadır. Alternatif olarak, aynı işlemleri gerçekleştiren bir PowerShell betiğini indirip çalıştırabilirsiniz.

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.

Önkoşullar

Bu hızlı başlangıç için aşağıdaki hizmetler ve araçlar gereklidir:

Sıralı ve etkileşimli adımlar için Invoke-RestMethod kullanarak PowerShell 7.3 veya üzeri.
Azure AI Arama hizmeti oluşturun veya geçerli aboneliğinizin altında mevcut bir hizmeti bulun. Bu hızlı başlangıç için ücretsiz bir hizmet kullanabilirsiniz.

Arama hizmeti anahtarını ve URL'sini kopyalama

Bu hızlı başlangıçta REST çağrıları, hizmet URL'sini ve her istekte bir erişim anahtarını içerir. Her ikisiyle de bir arama hizmeti oluşturulur, bu nedenle aboneliğinize Azure AI Search eklediyseniz gerekli bilgileri almak için bu adımları izleyin.

Azure Portal’ında oturum açın. Arama hizmetine Genel Bakış sayfanızda URL'yi alın. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.
Ayarlar> Keys'i seçin ve ardından hizmette tam haklar için bir yönetici anahtarı alın. Bir tane yuvarlamanız gerekirse iş sürekliliği için iki değiştirilebilir yönetici anahtarı sağlanır. Nesneleri ekleme, değiştirme ve silme isteklerinde birincil veya ikincil anahtarı kullanabilirsiniz.

Tüm istekler, hizmetinize gönderilen her istekte bir API anahtarı gerektirir. Geçerli bir anahtara sahip olmak, isteği gönderen uygulama ile bunu işleyen hizmet arasında istek başına güven oluşturur.

Azure AI Search'e Bağlan

PowerShell'de içerik türünü ve API anahtarını depolamak için bir $headers nesne oluşturun. Yönetici API anahtarını (YOUR-ADMIN-API-KEY) arama hizmetiniz için geçerli bir anahtarla değiştirin. Bu üst bilgiyi oturum süresi boyunca yalnızca bir kez ayarlamanız gerekir, ancak her isteğe eklersiniz.
```
$headers = @{
'api-key' = '<YOUR-ADMIN-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }
```
Hizmetin dizin koleksiyonunu belirten bir $url nesne oluşturun. Hizmet adını (YOUR-SEARCH-SERVICE-NAME) geçerli bir arama hizmetiyle değiştirin.
```
$url = "https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2023-11-01&`$select=name"
```
Komutunu çalıştırarak Invoke-RestMethod hizmete bir GET isteği gönderin ve bağlantıyı doğrulayın. Hizmetten geri gönderilen yanıtları görüntüleyebilmeniz için ekleyin ConvertTo-Json .
```
Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json
```
Hizmet boşsa ve dizin yoksa, sonuçlar aşağıdaki örneğe benzer. Aksi takdirde, dizin tanımlarının JSON gösterimini görürsünüz.
```
{
    "@odata.context":  "https://mydemo.search.windows.net/$metadata#indexes",
    "value":  [

            ]
}
```

Dizin oluşturma

Portalı kullanmıyorsanız, verileri yükleyebilmeniz için önce hizmette bir dizin bulunmalıdır. Bu adım dizini tanımlar ve hizmete yönlendirir. Bu adım için Dizin Oluşturma REST API'si kullanılır.

Bir dizinin gerekli öğeleri bir ad ve alan koleksiyonu içerir. Alanlar koleksiyonu bir belgenin yapısını tanımlar. Her alanın nasıl kullanıldığını belirleyen bir adı, türü ve öznitelikleri vardır (örneğin, arama sonuçlarında tam metin aranabilir, filtrelenebilir veya alınabilir). Dizin içinde, tür Edm.String alanlarından biri belge kimliği için anahtar olarak belirlenmelidir.

Bu dizin adlandırılmıştır hotels-quickstart ve aşağıdaki kodda gördüğünüz alan tanımlarına sahiptir. Bu, diğer izlenecek yol makalelerinde kullanılan daha büyük bir Oteller dizininin bir alt kümesidir. Bu hızlı başlangıçta alan tanımları kısa olması için kırpılmıştır.

Dizin şemasını içeren bir $body nesne oluşturmak için bu örneği PowerShell'e yapıştırın.

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

URI'yi hizmetinizdeki dizinler koleksiyonuna ve dizine hotels-quickstart ayarlayın.

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

hizmetindeki dizini oluşturmak için komutunu , $headersve $body ile $urlçalıştırın.

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

Sonuçlar, kısa süre için yalnızca ilk iki alanı gösteren bu örneğe benzer görünmelidir:

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

İpucu

Doğrulama için portalda Dizinler listesini de kontrol edebilirsiniz.

Belge yükleme

Belgeleri göndermek için dizininizin URL uç noktasına bir HTTP POST isteği kullanın. Bu görevin REST API'si Belge Ekle, Güncelleştir veya Sil'dir.

Karşıya yüklemek istediğiniz belgeleri içeren bir $body nesne oluşturmak için bu örneği PowerShell'e yapıştırın.

Bu istek iki tam kayıt ve bir kısmi kayıt içerir. Kısmi kayıt, eksik belgeleri karşıya yükleyebildiğinizi gösterir. @search.action parametresi dizin oluşturma işleminin nasıl yapıldığını belirtir. Geçerli değerler , , mergemergeOrUploadve deletedeğerlerini içerirupload. Davranış mergeOrUpload , için hotelId = 3 yeni bir belge oluşturur veya zaten varsa içeriği güncelleştirir.

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

Uç noktayı docs koleksiyonuna hotels-quickstart ayarlayın ve dizin işlemini (indexes/hotels-quickstart/docs/index) ekleyin.
```
$url = "https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2023-11-01"
```

Belgeleri hotels-quickstart dizine yüklemek için komutunu , $headersve $body ile $urlçalıştırın.

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

Sonuçlar aşağıdaki örneğe benzer görünmelidir. 201 durum kodunu görmeniz gerekir.

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

Dizin arama

Bu adım, Belgeleri Ara API'sini kullanarak bir dizini nasıl sorgulayabileceğinizi gösterir.

aramada $urlstek tırnak işaretlerini kullandığınızdan emin olun. Sorgu dizeleri karakter içerir $ ve dizenin tamamı tek tırnak içine alınmışsa, bu dizelerden kaçış yapmak zorunda olmayı atlayabilirsiniz.

Uç noktayı docs koleksiyonuna hotels-quickstart ayarlayın ve sorgu dizesini geçirmek için bir search parametre ekleyin.

Bu dize boş bir arama yürütür (search=* ) ve rastgele belgelerden oluşan bir unranked list (arama puanı = 1.0) döndürür. Varsayılan olarak, Azure AI Search bir kerede 50 eşleşme döndürür. Yapılandırılmış olarak, bu sorgu belge yapısının ve değerlerinin tamamını döndürür. Sonuçlardaki tüm belgelerin sayısını almak için ekleyin $count=true .
```
$url = 'https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?api-version=2023-11-01&search=*&$count=true'
```

komutunu çalıştırarak hizmetine gönderin $url .

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

Sonuçlar aşağıdaki çıkışa benzer görünmelidir:

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

Söz dizimine yönelik bir his elde etmek için birkaç sorgu örneğini daha deneyin. Dize araması yapabilir, ayrıntılı sorgular yapabilir, $filter sonuç kümesini sınırlayabilir, aramanın kapsamını belirli alanlarla sınırlandırabilir ve daha fazlasını yapabilirsiniz.

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

Kaynakları temizleme

Kendi aboneliğinizde çalışırken, projenin sonunda oluşturduğunuz kaynaklara hala ihtiyacınız olup olmadığını belirlemek iyi bir fikirdir. Çalışır durumda bırakılan kaynaklar maliyetlerin artmasına neden olabilir. Kaynakları teker teker silebilir veya tüm kaynak grubunu silerek kaynak kümesinin tamamını kaldırabilirsiniz.

En soldaki bölmedeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak portaldaki kaynakları bulabilir ve yönetebilirsiniz.

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

Sonraki adımlar

Bu hızlı başlangıçta PowerShell'i kullanarak Azure AI Search'te içerik oluşturmaya ve içeriğe erişmeye yönelik temel iş akışında adım adım ilerleyebilirsiniz. Kavramları göz önünde bulundurarak Azure veri kaynaklarından dizin oluşturma gibi daha gelişmiş senaryolara geçmenizi öneririz:

REST öğreticisi: Azure AI Search'te yarı yapılandırılmış verileri (JSON blobları) dizine alma ve arama