Hızlı başlangıç: REST API 'Leri kullanarak Postman 'da Azure Bilişsel Arama dizini oluşturmaQuickstart: Create an Azure Cognitive Search index in Postman using REST APIs

Azure BILIŞSEL arama REST API 'lerini keşfetmeye yönelik en kolay yollarından bırı, http isteklerini oluşturmak ve yanıtları Incelemek Için Postman veya başka bir Web testi aracı kullanmaktır.One of the easiest ways to explore the Azure Cognitive Search REST APIs is using Postman or another web testing tool to formulate HTTP requests and inspect the responses. Doğru araçlar ve bu yönergelerden yararlanarak herhangi bir kod yazmadan önce istek gönderebilir ve yanıtları görüntüleyebilirsiniz.With the right tools and these instructions, you can send requests and view responses before writing any code.

Bu makalede, isteklerin etkileşimli olarak nasıl formülleneceği açıklanır.This article explains how to formulate requests interactively. Alternatif olarak, önceden tanımlanmış istekleri kullanmak için bir Postman koleksiyonunu indirebilir ve içeri aktarabilirsiniz .Alternatively, you can download and import a Postman collection to use predefined requests.

Azure aboneliğiniz yoksa başlamadan önce ücretsiz bir hesap oluşturun.If you don't have an Azure subscription, create a free account before you begin.

ÖnkoşullarPrerequisites

Bu hızlı başlangıç için aşağıdaki hizmetler ve araçlar gereklidir.The following services and tools are required for this quickstart.

Anahtar ve URL alGet a key and URL

REST çağrıları için her istekte hizmet URL'sinin ve bir erişim anahtarının iletilmesi gerekir.REST calls require the service URL and an access key on every request. Her ikisiyle de bir arama hizmeti oluşturulur. bu nedenle, aboneliğinize Azure Bilişsel Arama eklediyseniz, gerekli bilgileri almak için aşağıdaki adımları izleyin:A search service is created with both, so if you added Azure Cognitive Search to your subscription, follow these steps to get the necessary information:

  1. Azure Portal oturum açınve arama hizmetine genel bakış sayfasında URL 'yi alın.Sign in to the Azure portal, and in your search service Overview page, get the URL. Örnek uç nokta https://mydemo.search.windows.net şeklinde görünebilir.An example endpoint might look like https://mydemo.search.windows.net.

  2. Ayarlar > anahtarlar' da, hizmette tam haklar için bir yönetici anahtarı alın.In Settings > Keys, get an admin key for full rights on the service. Üzerinde bir tane almanız gereken iş sürekliliği için iki adet değiştirilebilir yönetici anahtarı vardır.There are two interchangeable admin keys, provided for business continuity in case you need to roll one over. Nesneleri eklemek, değiştirmek ve silmek için isteklerde birincil veya ikincil anahtarı kullanabilirsiniz.You can use either the primary or secondary key on requests for adding, modifying, and deleting objects.

HTTP uç noktası ve erişim anahtarı alGet an HTTP endpoint and access key

Tüm istekler hizmetinize gönderilen her istekte bir API anahtarı gerektirir.All requests require an api-key on every request sent to your service. İ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.Having a valid key establishes trust, on a per request basis, between the application sending the request and the service that handles it.

Bu bölümde, Azure Bilişsel Arama bağlantıları kurmak için tercih ettiğiniz Web aracını kullanın.In this section, use your web tool of choice to set up connections to Azure Cognitive Search. Her araç oturum için istek üst bilgisi bilgilerini sürdürür, bu da yalnızca API anahtarı ve Içerik türü bir kez girmeniz gereken anlamına gelir.Each tool persists request header information for the session, which means you only have to enter the api-key and Content-Type once.

Her iki araç için de bir komut seçmeniz gerekir (GET, POST, PUT, vb.), bir URL uç noktası sağlamanız ve bazı görevler için isteğin gövdesinde JSON sağlamalısınız.For either tool, you need to choose a command (GET, POST, PUT, and so forth), provide a URL endpoint, and for some tasks, provide JSON in the body of the request. Arama hizmeti adı 'nı (-SEARCH-SERVICE-NAME) geçerli bir değerle değiştirin.Replace the search service name (YOUR-SEARCH-SERVICE-NAME) with a valid value. Yalnızca her bir dizinin adını döndürmek için $select=name ekleyin.Add $select=name to return just the name of each index.

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

HTTPS ön ekine, hizmetin adına, bir nesnenin adına (Bu durumda, dizinler koleksiyonuna) ve api sürümünedikkat edin.Notice the HTTPS prefix, the name of the service, the name of an object (in this case, the indexes collection), and the api-version. Api sürümü, geçerli sürüm için ?api-version=2019-05-06 olarak belirtilen, küçük harfli bir dizedir.The api-version is a required, lowercase string specified as ?api-version=2019-05-06 for the current version. API sürümleri düzenli olarak güncelleştirilir.API versions are updated regularly. api-version parametresini her isteğe dahil etmeniz hangisinin kullanıldığıyla ilgili tam denetim sahibi olmanızı sağlar.Including the api-version on each request gives you full control over which one is used.

İstek üst bilgisi bileşimi iki öğe, içerik türü ve Azure Bilişsel Arama kimlik doğrulaması için kullanılan API anahtarını içerir.Request header composition includes two elements, content type, plus the api-key used to authenticate to Azure Cognitive Search. Yönetici API anahtarını (-AZURE-SEARCH-ADMIN-API-KEY) geçerli bir değerle değiştirin.Replace the admin API key (YOUR-AZURE-SEARCH-ADMIN-API-KEY) with a valid value.

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

Postman 'da, aşağıdaki ekran görüntüsü gibi görünen bir istek girin.In Postman, formulate a request that looks like the following screenshot. Fiil olarak Al ' ı SEÇIN, URL 'yi sağlayın ve Gönder' e tıklayın.Choose GET as the verb, provide the URL, and click Send. Bu komut Azure Bilişsel Arama bağlanır, dizinler koleksiyonunu okur ve başarılı bir bağlantıda HTTP durum kodu 200 döndürür.This command connects to Azure Cognitive Search, reads the indexes collection, and returns HTTP status code 200 on a successful connection. Hizmetiniz zaten dizinler içeriyorsa, yanıt Dizin tanımlarını da içerir.If your service has indexes already, the response will also include index definitions.

Postman istek URL 'SI ve üstbilgisiPostman request URL and header

1 - Dizin oluşturma1 - Create an index

Azure Bilişsel Arama, genellikle dizini verilerle yüklemeden önce oluşturursunuz.In Azure Cognitive Search, you usually create the index before loading it with data. Create ındex REST API , bu görev için kullanılır.The Create Index REST API is used for this task.

URL, hotels dizin adını içerecek şekilde genişletilir.The URL is extended to include the hotels index name.

Bunu Postman 'da yapmak için:To do this in Postman:

  1. Fiili öğesini koymakiçin değiştirin.Change the verb to PUT.

  2. Bu URL 'de kopyalama https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart?api-version=2019-05-06.Copy in this URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart?api-version=2019-05-06.

  3. İsteğin gövdesinde Dizin tanımını (aşağıda, kopyalama öncesi kod verilmiştir) sağlayın.Provide the index definition (copy-ready code is provided below) in the body of the request.

  4. Gönder' e tıklayın.Click Send.

İstek gövdesinde JSON belgesi dizini oluşturIndex JSON document in request body

Dizin tanımıIndex definition

Alanlar koleksiyonu belge yapısını tanımlar.The fields collection defines document structure. Her belge bu alanlara sahip olmalıdır ve her bir alan bir veri türüne sahip olmalıdır.Each document must have these fields, and each field must have a data type. Dize alanları tam metin araması için kullanılır. Bu nedenle içerikte arama yapılabilmesini istiyorsanız sayısal verileri dize olarak ayarlamak isteyebilirsiniz.String fields are used in full text search, so you might want to cast numeric data as strings if you need that content to be searchable.

Alan öznitelikleri izin verilen eylemi belirler.Attributes on the field determine allowed action. REST API'leri varsayılan olarak birçok eyleme izin verir.The REST APIs allow many actions by default. Örneğin tüm dizelerde arama, getirme, filtreleme ve modelleme özellikleri varsayılan olarak etkindir.For example, all strings are searchable, retrievable, filterable, and facetable by default. Genellikle, öznitelikleri yalnızca bir davranışı kapatmanız gerektiğinde ayarlamanız gerekir.Often, you only have to set attributes when you need to turn off a behavior.

{
    "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.When you submit this request, you should get an HTTP 201 response, indicating the index was created successfully. Bu eylemi portaldan doğrulayabilirsiniz ancak portal sayfasındaki yenileme aralıkları nedeniyle bilgilerin güncellenmesi bir-iki dakika sürebilir.You can verify this action in the portal, but note that the portal page has refresh intervals so it could take a minute or two to catch up.

İpucu

HTTP 504 yanıtı alırsanız HTTPS'yi belirten URL'yi doğrulayın.If you get HTTP 504, verify the URL specifies HTTPS. 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.If you see HTTP 400 or 404, check the request body to verify there were no copy-paste errors. HTTP 403 genelde api anahtarı ile ilgili bir sorunu gösterir (geçersiz anahtar veya api anahtarının nasıl belirtildiğine ilişkin söz dizimi sorunu).An HTTP 403 typically indicates a problem with the api-key (either an invalid key or a syntax problem with how the api-key is specified).

2-belge yükleme2 - Load documents

Dizini oluşturma ve dizini doldurma ayrı adımlardır.Creating the index and populating the index are separate steps. Azure Bilişsel Arama, dizin, JSON belgeleri olarak sağlayabilmeniz için tüm aranabilir verileri içerir.In Azure Cognitive Search, the index contains all searchable data, which you can provide as JSON documents. Bu görev için REST API belge ekleme, güncelleştirme veya silme işlemi kullanılıyor.The Add, Update, or Delete Documents REST API is used for this task.

URL, docs koleksiyonlarını ve index işlemini içerecek şekilde genişletilir.The URL is extended to include the docs collections and index operation.

Bunu Postman 'da yapmak için:To do this in Postman:

  1. Fiili POST olarak değiştirin.Change the verb to POST.

  2. Bu URL 'de kopyalama https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2019-05-06.Copy in this URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2019-05-06.

  3. İsteğin gövdesinde JSON belgelerini (kopya-Ready kodu aşağıda bulunur) sağlayın.Provide the JSON documents (copy-ready code is below) in the body of the request.

  4. Gönder' e tıklayın.Click Send.

İstek gövdesinde JSON belgeleriJSON documents in request body

Dizine yüklenecek JSON belgeleriJSON documents to load into the index

İstek Gövdesi, oteller dizinine eklenecek dört belge içerir.The Request Body contains four documents to be added to the hotels index.

{
    "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örmeniz gerekir.In a few seconds, you should see an HTTP 201 response in the session list. Bu, belgelerin başarıyla oluşturulduğunu belirtir.This indicates the documents were created successfully.

207 yanıtı alırsanız en az bir belge karşıya yüklenemedi.If you get a 207, at least one document failed to upload. 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.If you get a 404, you have a syntax error in either the header or body of the request: verify you changed the endpoint to include /docs/index.

İpucu

Seçili veri kaynaklarında dizin oluşturma için gerekli kodları sadeleştiren ve miktarını azaltan alternatif dizin oluşturucu yaklaşımını kullanabilirsiniz.For selected data sources, you can choose the alternative indexer approach which simplifies and reduces the amount of code required for indexing. Daha fazla bilgi için bkz. Dizin oluşturucu işlemleri.For more information, see Indexer operations.

3 - Dizin arama3 - Search an index

Artık bir dizin ve belge yüklendikten sonra, arama belgelerinikullanarak bunlara yönelik sorgular verebilirsiniz REST API.Now that an index and documents are loaded, you can issue queries against them using Search Documents REST API.

URL, arama işleci kullanılarak belirtilen bir sorgu ifadesi içerecek şekilde genişletilir.The URL is extended to include a query expression, specified using the search operator.

Bunu Postman 'da yapmak için:To do this in Postman:

  1. Alınacakfiili ' i değiştirin.Change the verb to GET.

  2. Bu URL 'de kopyalama https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2019-05-06.Copy in this URL https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2019-05-06.

  3. Gönder' e tıklayın.Click Send.

Bu sorgu boş ve arama sonuçlarındaki belgelerin sayısını döndürüyor.This query is an empty and returns a count of the documents in the search results. Gönder' e tıkladıktan sonra istek ve yanıt, Postman için aşağıdaki ekran görüntüsüne benzer görünmelidir.The request and response should look similar to the following screenshot for Postman after you click Send. Durum kodu 200 olmalıdır.The status code should be 200.

URL 'de arama dizesiyle alGET with search string on the URL

Söz dizimi için bir fikir almak üzere birkaç başka sorgu örneği deneyin.Try a few other query examples to get a feel for the syntax. Dize araması yapabilir, tam $filter sorgular yapabilir, sonuç kümesini sınırlayabilir, aramanın belirli alanlarla kapsamını ve daha fazlasını yapabilirsiniz.You can do a string search, verbatim $filter queries, limit the results set, scope the search to specific fields, and more.

Geçerli URL 'yi aşağıdaki gibi değiştirin ve sonuçları görüntülemek için her seferinde Gönder ' e tıklayın.Swap out the current URL with the ones below, clicking Send each time to view the results.

# 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=2019-05-06

# 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=2019-05-06

# 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=2019-05-06

# 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=2019-05-06

Dizin özelliklerini alGet index properties

Belge sayılarını ve dizin boyutunu sorgulamak için de Istatistikleri al ' da kullanabilirsiniz:You can also use Get Statistics to query for document counts and index size:

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

URL 'nize /stats eklemek dizin bilgilerini döndürür.Adding /stats to your URL returns index information. 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.In Postman, your request should look similar to the following, and the response includes a document count and space used in bytes.

Dizin bilgilerini alGet index information

api-version söz diziminin farklı olduğuna dikkat edin.Notice that the api-version syntax differs. Bu istek için api-version parametresine ? ekleyin.For this request, use ? to append the api-version. ?, URL yolunu sorgu dizesinden ayırır, & her bir ' name = value ' çiftini sorgu dizesinde ayırır.The ? separates the URL path from the query string, while & separates each 'name=value' pair in the query string. Bu sorgu için api-version, sorgu dizesindeki ilk ve tek öğedir.For this query, api-version is the first and only item in the query string.

Kaynakları temizlemeClean up resources

Kendi aboneliğinizde çalışırken, sizin oluşturduğunuz kaynaklara hala ihtiyacınız olup olmadığını belirlemek için bir projenin sonunda iyi bir fikir olur.When you're working in your own subscription, it's a good idea at the end of a project to identify whether you still need the resources you created. Çalışan kaynaklar sizin için ücret verebilir.Resources left running can cost you money. Kaynakları tek tek silebilir veya kaynak grubunu silerek tüm kaynak kümesini silebilirsiniz.You can delete resources individually or delete the resource group to delete the entire set of resources.

Sol gezinti bölmesindeki tüm kaynaklar veya kaynak grupları bağlantısını kullanarak portalda kaynakları bulabilir ve yönetebilirsiniz.You can find and manage resources in the portal, using the All resources or Resource groups link in the left-navigation pane.

Ücretsiz bir hizmet kullanıyorsanız, üç Dizin, Dizin Oluşturucu ve veri kaynağı ile sınırlı olduğunu unutmayın.If you are using a free service, remember that you are limited to three indexes, indexers, and data sources. Sınırın altında kalmak için portalda ayrı ayrı öğeleri silebilirsiniz.You can delete individual items in the portal to stay under the limit.

Sonraki adımlarNext steps

Temel görevlerin nasıl gerçekleştirileceğini öğrenmiş olduğunuza göre, Dizin oluşturucular veya bilişsel Arama işlem hattı ayarlamagibi daha gelişmiş özellikler için ek REST API çağrılarıyla ileriye geçebilirsiniz.Now that you know how to perform core tasks, you can move forward with additional REST API calls for more advanced features, such as indexers or setting up a cognitive search pipeline. Sonraki adımınız için aşağıdaki bağlantıyı öneririz:For your next step, we recommend the following link: