Hızlı Başlangıç: REST API'Azure Bilişsel Arama bir dizin oluşturma

Bu makalede, Azure Bilişsel Arama REST API'leri ve istekleri gönderip almak için bir API istemcisi kullanarak REST API istekleri etkileşimli bir şekilde nasıl formüle etmek açıklanmıştır. Api istemcisi ve bu yönergelerle, herhangi bir kod yazmadan önce istek gönderebilir ve yanıtları görüntüebilirsiniz.

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

Makalede Postman masaüstü uygulaması lanmıştır. Önceden tanımlanmış istekleri kullanmayı tercih ediyorsanız Postman koleksiyonunu indirip içeri aktarabilirsiniz.

Önkoşullar

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

• Postman masaüstü uygulaması, Azure Bilişsel Arama'a istek göndermek için kullanılır.

• Bir Azure Bilişsel Arama hizmeti oluşturun veya geçerli aboneliğinizin altında var olan bir hizmeti bulun. Bu hızlı başlangıç için ücretsiz bir hizmet kullanabilirsiniz.

Anahtarı ve URL'yi kopyalama

REST çağrıları için her istekte hizmet URL'sinin ve bir erişim anahtarının iletilmesi gerekir. Her ikisinde de bir arama hizmeti oluşturulur, bu nedenle Azure Bilişsel Arama için aşağıdaki adımları izleyin:

1. Azure portaloturum Azure portal hizmeti genel bakış sayfasında URL'yi elde edin. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.

2. Bu > Ayarlar, hizmet üzerinde tam haklar için bir yönetici anahtarı edinin. İki değiştirilebilir yönetici anahtarı vardır ve bir anahtarın geçişinin gerekli olması durumunda iş sürekliliği için sağlanır. Nesne ekleme, değiştirme ve silme istekleri için birincil veya ikincil anahtarı kullanabilirsiniz.

Tüm istekler, hizmetinize gönderilen her istek için bir api anahtarı gerektirir. İstek başına geçerli bir anahtara sahip olmak, isteği gönderen uygulama ve bunu işleyen hizmet arasında güven oluşturur.

Bağlan Azure Bilişsel Arama

Bu bölümde, tercih edersiniz web aracını kullanarak web sitenize bağlantı Azure Bilişsel Arama. Her araç oturum için istek üst bilgisi bilgilerini kalıcı olarak bulundurarak api anahtarını ve Content-Type'i yalnızca bir kez girmeniz gerekir.

Her iki araç için de bir komut (GET, POST, PUT vb.) seçmeniz, bir URL uç noktası sağlamanız ve bazı görevler için isteğin gövdesinde JSON sağlamanız gerekir. Arama hizmeti adını (YOUR-SEARCH-SERVICE-NAME) geçerli bir değerle değiştirin. Yalnızca $select=name her dizinin adını geri dönmek için ekleyin.

https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes?api-version=2020-06-30&$select=name

HTTPS ön eki, hizmetin adı, bir nesnenin adı (bu durumda dizin koleksiyonu) ve api-version'a dikkat edin. API sürümü, geçerli sürüm için olarak belirtilen gerekli, küçük ?api-version=2020-06-30 harfli bir dizedir. API sürümleri düzenli olarak güncelleştirilir. api-version parametresini her isteğe dahil etmeniz hangisinin kullanıldığıyla ilgili tam denetim sahibi olmanızı sağlar.

İstek üst bilgisi bileşimi iki öğe içerir: Content-Type ve kimlik doğrulaması için kullanılan api-key Azure Bilişsel Arama. Yönetici API anahtarını (YOUR-AZURE-SEARCH-ADMIN-API-KEY) geçerli bir değerle değiştirin.

api-key: <YOUR-AZURE-SEARCH-ADMIN-API-KEY>
Content-Type: application/json

Postman'de aşağıdaki ekran görüntüsüne benzer bir istek formüle alın. Komut olarak GET'i seçin, URL'yi girin ve Gönder'e tıklayın. Bu komut Azure Bilişsel Arama, dizin koleksiyonunu okur ve başarılı bir bağlantıda 200 HTTP durum kodunu döndürür. Hizmetiniz zaten dizinlere sahipse yanıt dizin tanımlarını da içerir.

1 - Dizin oluşturma

Bu Azure Bilişsel Arama genellikle verileri yüklemeden önce dizini oluşturmanız gerekir. Bu görev REST API Dizin Oluştur dizini kullanılır.

URL, dizin adını içerecek şekilde hotels genişletildi.

Bunu Postman'de yapmak için:

1. Komutu PUT olarak değiştirme.

2. Bu URL'ye https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30 kopyalayın.

3. İsteğin gövdesinde dizin tanımını (kopyalamaya hazır kod aşağıda verilmiştir) girin.

4. Gönder’e tıklayın.

Dizin tanımı

Alanlar koleksiyonu belge yapısını tanımlar. Her belgede bu alanlar ve her alanın bir veri türü olması gerekir. Dize alanları tam metin aramalarında kullanılır. Aranabilir olması için sayısal verilere ihtiyacınız varsa sayısal verileri dize olarak dönüştürmelisiniz.

Alan öznitelikleri izin verilen eylemi belirler. REST API'leri varsayılan olarak birçok eyleme izin verir. Örneğin tüm dizelerde arama, getirme, filtreleme ve modelleme özellikleri varsayılan olarak etkindir. Genellikle, öznitelikleri yalnızca bir davranışı kapatmaya ihtiyacınız olduğunda ayarlayabilirsiniz.

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

Bu isteği gönderdiğinizde dizinin başarıyla oluşturulduğunu belirten HTTP 201 yanıtı almanız gerekir. Bu eylemi portaldan doğrulayabilirsiniz ancak portal sayfasındaki yenileme aralıkları nedeniyle bilgilerin güncellenmesi bir-iki dakika sürebilir.

2 - Belgeleri yükleme

Dizini oluşturma ve dizini doldurma ayrı adımlardır. Dizinde Azure Bilişsel Arama tüm aranabilir verileri içerir. Bu senaryoda veriler JSON belgeleri olarak sağlanır. Bu görev için Belge Ekle, Güncelleştir REST API Sil bilgileri kullanılır.

URL, koleksiyonları ve işlemi docs içerecek şekilde index genişletildi.

Bunu Postman'de yapmak için:

1. komutunu POST olarak değiştirme.

2. Bu URL'ye https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2020-06-30 kopyalayın.

3. İsteğin gövdesinde JSON belgelerini (kopyalamaya hazır kod aşağıda verilmiştir) girin.

4. Gönder’e tıklayın.

Dizine yüklenmek için JSON belgeleri

İstek Gövdesi, oteller dizinine eklenecek dört belge içerir.

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

Birkaç saniye içinde, oturum listesinde bir HTTP 201 yanıtı görüyor gerekir. Bu, belgelerin başarıyla oluşturulduğunu belirtir.

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 vardır. Uç noktayı /docs/index içerecek şekilde değiştirdiğinizden emin olun.

3 - Dizin arama

Artık bir dizin ve belge kümesi yüklensin, bu dizinler için Arama Belgeleri'REST API.

URL, arama işleci kullanılarak belirtilen bir sorgu ifadesi içerecek şekilde genişletildi.

Bunu Postman'de yapmak için:

1. Komutunu GET olarak değiştirme.

2. Bu URL'ye https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2020-06-30 kopyalayın.

3. Gönder’e tıklayın.

Bu sorgu boştur ve arama sonuçlarında belgelerin sayısını döndürür. Gönder'e tıklarken Postman için istek ve yanıt aşağıdaki ekran görüntüsüne benzer şekilde görüntü gerekir. Durum kodu 200 olmalıdır.

Söz dizimi hakkında daha fazla bilgi almak için birkaç sorgu örneği daha deneyin. Bir dize araması, sorgularda ayrıntılı $filter, sonuç kümesi sınırlaması, arama kapsamını belirli alanlara göre sınırlama ve daha fazlasını gerçekleştirebilirsiniz.

Geçerli URL'yi aşağıdakilerle değiştirin ve sonuçları görüntülemek için Her zaman gönder'e tıklayın.

# Query example 1 - Search on restaurant and wifi
# Return only the HotelName, Description, and Tags fields
https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?search=restaurant wifi&$count=true&$select=HotelName,Description,Tags&api-version=2020-06-30

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

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

# Query example 4 - Sort by a specific field (Address/City) in ascending order
https://<YOUR-SEARCH-SERVICE>.search.windows.net/indexes/hotels-quickstart/docs?search=pool&$orderby=Address/City asc&$select=HotelName, Address/City, Tags, Rating&api-version=2020-06-30

Dizin özelliklerini al

Belge sayılarını ve dizin boyutunu sorgulamak için İstatistik Al'ın da kullanabilirsiniz:

https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/stats?api-version=2020-06-30

/statsURL'nize eklemek dizin bilgilerini döndürür. Postman uygulamasında isteğinizin aşağıdakine benzer olması ve yanıtta belge sayısı ile kullanılan alanın bayt cinsinden değerinin belirtilmesi gerekir.

api-version söz diziminin farklı olduğuna dikkat edin. Bu istek için api-version parametresine ? ekleyin. , URL yolunu sorgu dizesinden, & ise sorgu dizesinde ? her bir 'name=value' çiftini birbirinden ayırıyor. Bu sorgu için api-version, sorgu dizesindeki ilk ve tek öğedir.

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.

Sol gezinti bölmesindeki Tüm kaynaklar veya Kaynak grupları bağlantısını kullanarak portalda kaynakları bulabilir ve yönetebilirsiniz.

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

Sonraki adımlar

Artık temel görevleri nasıl gerçekleştireceklerini bildiğinize göre, dizin oluşturma REST API daha gelişmiş özellikler için ek çağrılar veya dizin oluşturmaya içerik dönüşümleri ekleyen bir zenginleştirme işlem hattı ayarlama gibi ek çağrılarla devam edersiniz. Sonraki adımınız için aşağıdaki bağlantıyı öneririz: