Hızlı Başlangıç: REST kullanarak anahtar sözcük araması
Azure AI Search'teki REST API'leri, önizleme özellikleri de dahil olmak üzere tüm özelliklerine programlı erişim sağlar ve özelliklerin nasıl çalıştığını öğrenmenin kolay bir yoludur. Bu hızlı başlangıçta, Azure AI Search'te arama dizini oluşturmak, yüklemek ve sorgulamak için Search REST API'lerini çağırmayı öğrenin.
Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.
Önkoşullar
REST istemcisi ile Visual Studio Code.
Azure AI Arama. Geçerli aboneliğinizin altında mevcut bir Azure AI Search kaynağı oluşturun veya bulun. Bu hızlı başlangıç için ücretsiz bir hizmet kullanabilirsiniz.
Dosyaları indirme
Bu hızlı başlangıçta istekleri göndermek için GitHub'dan bir REST örneği indirin. Yönergeler GitHub'dan dosya indirme başlığında bulunabilir.
Ayrıca, bu makaledeki yönergeleri kullanarak yerel sisteminizde yeni bir dosya başlatabilir ve istekleri el ile oluşturabilirsiniz.
Arama hizmeti uç noktası alma
Arama hizmeti uç noktasını Azure portalında bulabilirsiniz.
Azure portalında oturum açın ve arama hizmetinizi bulun.
Genel Bakış giriş sayfasında URL'yi bulun. Örnek uç nokta
https://mydemo.search.windows.net
şeklinde görünebilir.
Bu uç noktayı .rest
sonraki bir adımda veya .http
dosyasına yapıştıracaksınız.
Erişimi yapılandırma
Arama uç noktasına yönelik isteklerin kimliği doğrulanmış ve yetkilendirilmiş olmalıdır. Bu görev için API anahtarlarını veya rollerini kullanabilirsiniz. Anahtarları kullanmaya başlamak daha kolaydır, ancak roller daha güvenlidir.
Rol tabanlı bir bağlantı için aşağıdaki yönergeler, istemci uygulamasının kimliğiyle değil, kimliğinizin altında Azure AI Search'e bağlanmanızı içerir.
1. Seçenek: Tuşları kullanma
Ayarlar>Anahtarları'nı seçin ve ardından bir yönetici anahtarı kopyalayın. Yönetici anahtarları nesneleri eklemek, değiştirmek ve silmek için kullanılır. Değiştirilebilir iki yönetici anahtarı vardır. İkisini de kopyalayın. Daha fazla bilgi için bkz . Anahtar kimlik doğrulaması kullanarak Azure AI Search'e bağlanma.
Bu anahtarı .rest
sonraki bir adımda veya .http
dosyasına yapıştıracaksınız.
2. Seçenek: Rolleri kullanma
Arama hizmetinizin rol tabanlı erişim için yapılandırıldığından emin olun. Geliştirici erişimi için önceden yapılandırılmış rol atamalarınız olmalıdır. Rol atamalarınızın arama dizini oluşturma, yükleme ve sorgulama izni vermesi gerekir.
Bu bölümde Azure CLI, Azure PowerShell veya Azure portalını kullanarak kişisel kimlik belirtecinizi alın.
Azure CLI'da oturum açın.
az login
Kişisel kimlik belirtecinizi alın.
az account get-access-token --scope https://search.azure.com/.default
Kişisel kimlik belirtecinizi .rest
sonraki bir adımda veya .http
dosyasına yapıştırıyorsunuz.
Not
Bu bölümde, sizin yerinize Azure AI Search'e bağlanan yerel bir istemci kullandığınız varsayılır. Alternatif bir yaklaşım, uygulamanızın Microsoft Entra ID'ye kayıtlı olduğu varsayılarak istemci uygulaması için belirteç almaktır.
Visual Studio Code'u ayarlama
Visual Studio Code için REST istemcisi hakkında bilginiz yoksa, bu bölüm bu hızlı başlangıçta görevleri tamamlayabilmeniz için kurulumu içerir.
Visual Studio Code'ı başlatın ve Uzantılar kutucuğunu seçin.
REST istemcisini arayın ve Yükle'yi seçin.
veya dosya uzantısıyla adlı yeni bir
.rest
dosya açın veya.http
oluşturun.API anahtarları kullanıyorsanız aşağıdaki örneği yapıştırın.
@baseUrl
ve@apiKey
yer tutucularını daha önce kopyaladığınız değerlerle değiştirin.@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}}
Veya rolleri kullanıyorsanız bu örneği yapıştırın.
@baseUrl
ve@token
yer tutucularını daha önce kopyaladığınız değerlerle değiştirin.@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}}
İstek gönder’i seçin. Bir yanıt bitişik bir bölmede görünmelidir. Mevcut dizinleriniz varsa, bunlar listelenir. Aksi takdirde, liste boş olur. HTTP kodu ise
200 OK
, sonraki adımlara hazırsınız demektir.Önemli noktalar:
- Parametreler bir
@
ön ek kullanılarak belirtilir. ###
bir REST çağrısı oluşturur. Sonraki satır, içermesi gerekenHTTP/1.1
isteği içerir.Send request
isteğin üzerinde görünmelidir.
- Parametreler bir
Dizin oluşturma
Dosyanıza .rest
ikinci bir istek ekleyin. Dizin Oluştur (REST), bir arama dizini oluşturur ve arama hizmetinizdeki fiziksel veri yapılarını ayarlar.
Arama hizmetinizde dizini oluşturmak
hotels-quickstart
için aşağıdaki örneği yapıştırın.### 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} ] } ] }
İstek gönder’i seçin. Bir
HTTP/1.1 201 Created
yanıtınız olmalıdır ve yanıt gövdesi dizin şemasının JSON gösterimini içermelidir.Hata
Header name must be a valid HTTP token ["{"]
alırsanız, isteğin gövdesiyle arasındaapi-key
boş bir satır olduğundan emin olun. HTTP 504 alırsanız, URL'nin HTTPS belirttiğini doğrulayın. HTTP 400 veya 404 yanıtı görürseniz kopyala-yapıştır hatası olmadığını doğrulamak için istek gövdesini kontrol edin. HTTP 403 genellikle API anahtarıyla ilgili bir sorun olduğunu gösterir. Bu geçersiz bir anahtar veya API anahtarının nasıl belirtildiğiyle ilgili bir söz dizimi sorunudur.Artık dosyanızda birkaç istek var. Yeni bir istek başlattığını ve her isteğin
###
bağımsız olarak çalıştığını hatırlayın.
Dizin tanımı hakkında
Dizin şemasında alanlar koleksiyonu belge yapısını tanımlar. Karşıya yüklediğiniz her belgede bu alanlar olmalıdır. Her alan bir Varlık Veri Modeli (EDM) veri türüne atanmalıdır. Dize alanları tam metin aramasında kullanılır. Sayısal verilerin aranabilir olmasını istiyorsanız, veri türünün olduğundan Edm.String
emin olun. Gibi Edm.Int32
diğer veri türleri filtrelenebilir, sıralanabilir, modellenebilir ve alınabilir ancak tam metin aranabilir değildir.
Alandaki öznitelikler, izin verilen eylemleri belirler. REST API'leri varsayılan olarak birçok eyleme izin verir. Örneğin, tüm dizeler varsayılan olarak aranabilir ve alınabilir. REST API'leri için öznitelikleriniz yalnızca bir davranışı kapatmanız gerekiyorsa olabilir.
{
"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}
]
}
]
}
Belge yükleme
Dizini oluşturma ve yükleme ayrı adımlardır. Azure AI Search'te dizin, arama hizmetinde çalıştırılacak tüm aranabilir verileri ve sorguları içerir. REST çağrıları için veriler JSON belgeleri olarak sağlanır. Bu görev için Belgeler- Dizin REST API'sini kullanın.
URI, koleksiyonları ve index
işlemi içerecek şekilde docs
genişletilir.
JSON belgelerini arama dizinine yüklemek için aşağıdaki örneği yapıştırın.
### 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": "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" } } ] }
İstek gönder’i seçin. Birkaç saniye içinde, bitişik bölmede bir HTTP 201 yanıtı görmeniz gerekir.
207 yanıtı alırsanız en az bir belge karşıya yüklenemedi. 404 yanıtı alırsanız üst bilgi veya istek gövdesinde söz dizimi hatanız var. Uç noktayı içerecek
/docs/index
şekilde değiştirdiğinizden emin olun.
Sorgu çalıştırma
Belgeler yüklendiklerine göre, Belgeler - Arama Gönderisi (REST) kullanarak bunlara yönelik sorgular gönderebilirsiniz.
URI, işleci kullanılarak belirtilen bir sorgu ifadesi içerecek şekilde /docs/search
genişletilir.
Arama dizinini sorgulamak için aşağıdaki örneği yapıştırın. Ardından İstek gönder'i seçin. Metin arama isteği her zaman bir
search
parametre içerir. Bu örnek, metin aramasını belirli alanlarla kısıtlayan isteğe bağlısearchFields
bir parametre içerir.### 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 }
Bitişik bölmedeki yanıtı gözden geçirin. Dizinde bulunan eşleşme sayısını, ilgiyi gösteren bir arama puanını ve deyiminde listelenen her alanın değerlerini gösteren bir sayınız
select
olmalıdır.{ "@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 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.", "Tags": [ "concierge", "view", "24-hour front desk service" ] } ] }
Dizin özelliklerini alma
Belge sayılarını ve dizin boyutunu sorgulamak için İstatistik Al'ı da kullanabilirsiniz.
Arama dizinini sorgulamak için aşağıdaki örneği yapıştırın. Ardından İstek gönder'i seçin.
### Get index statistics GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}
Yanıtı gözden geçirin. Bu işlem, dizin depolama hakkında ayrıntılı bilgi edinmenin kolay bir yoludur.
{ "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics", "documentCount": 4, "storageSize": 34707, "vectorIndexSize": 0 }
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.
Şu komutu da deneyebilirsiniz DELETE
:
### Delete an index
DELETE {{baseUrl}}/indexes/hotels-quickstart?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{apiKey}}
Sonraki adım
ARTıK REST istemcisini bildiğinize ve Azure AI Search'e REST çağrıları yaptığınıza göre vektör desteğini gösteren başka bir hızlı başlangıç deneyin.