Snabbstart: Skapa ett Azure Cognitive Search med hjälp av REST-API:er

Den här artikeln förklarar hur du formulerar REST API begäranden interaktivt med hjälp Azure Cognitive Search REST-API:er och en API-klient för att skicka och ta emot begäranden. Med en API-klient och de här instruktionerna kan du skicka begäranden och visa svar innan du skriver någon kod.

Om du inte har någon Azure-prenumeration kan du skapa ett kostnadsfritt konto innan du börjar.

Artikeln använder postman-skrivbordsprogrammet. Du kan ladda ned och importera en Postman-samling om du föredrar att använda fördefinierade begäranden.

Förutsättningar

Följande tjänster och verktyg krävs för den här snabbstarten.

• Postman-skrivbordsappen används för att skicka begäranden till Azure Cognitive Search.

• Skapa en Azure Cognitive Search-tjänst eller hitta en befintlig tjänst under din aktuella prenumeration. Du kan använda en kostnadsfri tjänst för den här snabbstarten.

Kopiera en nyckel och en URL

För att kunna göra REST-anrop behöver du tjänstens webbadress och en åtkomstnyckel för varje begäran. En söktjänst skapas med båda, så om du har lagt Azure Cognitive Search i din prenumeration följer du dessa steg för att få nödvändig information:

1. Logga in på Azure Portaloch hämta URL:en på översiktssidan för söktjänsten. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.

2. I Inställningar > keys(Nycklar) hämtar du en administratörsnyckel för fullständiga rättigheter till tjänsten. Det finns två utbytbara administratörsnycklar som tillhandahålls för affärskontinuhet om du behöver återställa en. Du kan använda antingen den primära eller sekundära nyckeln för begäranden för att lägga till, ändra och ta bort objekt.

Alla begäranden kräver en API-nyckel för varje begäran som skickas till din tjänst. En giltig nyckel upprättar förtroende, i varje begäran, mellan programmet som skickar begäran och tjänsten som hanterar den.

Anslut till Azure Cognitive Search

I det här avsnittet använder du val av webbverktyg för att konfigurera anslutningar till Azure Cognitive Search. Varje verktyg bevarar information om begärandehuvuden för sessionen, vilket innebär att du bara behöver ange API-nyckeln och Innehållstyp en gång.

För något av verktygen måste du välja ett kommando (GET, POST, PUT och så vidare), ange en URL-slutpunkt och för vissa uppgifter ange JSON i brödtexten i begäran. Ersätt söktjänstens namn (YOUR-SEARCH-SERVICE-NAME) med ett giltigt värde. Lägg $select=name till för att bara returnera namnet på varje index.

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

Observera HTTPS-prefixet, namnet på tjänsten, namnet på ett objekt (i det här fallet indexsamlingen) och API-versionen. API-versionen är en obligatorisk sträng med gemener angiven ?api-version=2020-06-30 som för den aktuella versionen. API-versionerna uppdateras regelbundet. När du inkluderar API-versionen för varje begäran får du fullständig kontroll över vilken version som används.

Sammansättningen av begärandehuvud innehåller två Content-Type element: och api-key används för att autentisera för Azure Cognitive Search. Ersätt admin API-nyckeln (YOUR-AZURE-SEARCH-ADMIN-API-KEY) med ett giltigt värde.

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

Formulera en begäran i Postman som ser ut som på följande skärmbild. Välj GET som kommando, ange URL:en och klicka på Skicka. Det här kommandot ansluter Azure Cognitive Search, läser indexsamlingen och returnerar HTTP-statuskod 200 vid en lyckad anslutning. Om din tjänst redan har index innehåller svaret även indexdefinitioner.

1 – Skapa ett index

I Azure Cognitive Search skapar du vanligtvis indexet innan du läser in det med data. Skapa index-REST API används för den här uppgiften.

URL:en utökas så att hotels indexnamnet inkluderas.

Så här gör du i Postman:

1. Ändra kommandot till PUT.

2. Kopiera in den här https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart?api-version=2020-06-30 URL:en.

3. Ange indexdefinitionen (kopieringsklar kod anges nedan) i brödtexten i begäran.

4. Klicka på Skicka.

Indexdefinition

Fältsamlingen definierar dokumentstrukturen. Varje dokument måste ha dessa fält och varje fält måste ha en datatyp. Strängfält används i fulltextsökning. Om du vill att numeriska data ska vara sökbara måste du använda numeriska data som strängar.

Vilka åtgärder som tillåts fastställs av fältattributen. Med REST API:er kan du använda standardåtgärder i stor utsträckning. Alla strängar blir till exempel sökbara, hämtningsbara, filtrerbara och fasettbara som standard. Ofta behöver du bara ange attribut när du behöver stänga av ett beteende.

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

När du skickar denna begäran får du ett HTTP 201-svar som anger att indexet har skapats. Du kan kontrollera detta i portalen, men observera att portalsidan uppdateras med bestämda intervall, så det kan dröja någon minut eller två innan informationen dyker upp.

2 – Läsa in dokument

Att skapa ett index och att fylla det, är två separata steg. I Azure Cognitive Search innehåller indexet alla sökbara data. I det här scenariot tillhandahålls data som JSON-dokument. Lägg till, uppdatera eller ta bort dokument REST API för den här uppgiften.

URL:en utökas så att den omfattar docs samlingarna och index åtgärden.

Så här gör du i Postman:

1. Ändra kommandot till POST.

2. Kopiera in den här https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs/index?api-version=2020-06-30 URL:en.

3. Ange JSON-dokumenten (kopieringsklar kod finns nedan) i brödtexten i begäran.

4. Klicka på Skicka.

JSON-dokument som ska läsas in i indexet

Begärandetexten innehåller fyra dokument som ska läggas till i hotellindexet.

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

Inom några sekunder bör du se ett HTTP 201-svar i sessionslistan. Detta anger att dokumenten har skapats.

Om ett 207-svar returneras misslyckades uppladdningen av minst ett dokument. Om ett 404-svar returneras beror det på ett syntaxfel i begärandehuvudet eller i begärandetexten. Kontrollera att du har ändrat slutpunkten så att den inkluderar följande: /docs/index.

3 – Söka i ett index

Nu när en index- och dokumentuppsättning har lästs in kan du skicka frågor mot dem med hjälp av sökdokument REST API.

URL:en utökas så att den innehåller ett frågeuttryck som anges med hjälp av sökoperatorn.

Så här gör du i Postman:

1. Ändra kommandot till GET.

2. Kopiera in den här https://<YOUR-SEARCH-SERVICE-NAME>.search.windows.net/indexes/hotels-quickstart/docs?search=*&$count=true&api-version=2020-06-30 URL:en.

3. Klicka på Skicka.

Den här frågan är tom och returnerar antalet dokument i sökresultaten. Begäran och svar bör se ut som skärmbilden från Postman nedan efter att du klickat på Skicka. Statuskoden ska vara 200.

Prova några andra frågeexempel för att få en känsla för syntaxen. Du kan göra en strängsökning, ordagranna $filter frågor, begränsa resultatuppsättningen, begränsa sökningen till specifika fält med mera.

Växla ut den aktuella URL:en med nedanstående och klicka på Skicka varje gång för att visa resultatet.

# 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

Hämta indexegenskaper

Du kan också använda Hämta statistik för att fråga efter antal dokument och indexstorlek:

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

Om du /stats lägger till i url:en returneras indexinformation. Din begäran i Postman borde se ut som på bilden nedan. Svaret innehåller ett dokumentantal och det diskutrymme som används uttryckt i byte.

Observera att syntaxen för API-versionen ser annorlunda ut här. Denna begäran använder ? för att lägga till API-versionen. separerar ? URL-sökvägen från frågesträngen, & avgränsar varje "name=value"-par i frågesträngen. I den här frågan är API-versionen det första och enda objektet i frågesträngen.

Rensa resurser

När du arbetar i din egen prenumeration kan det dock vara klokt att i slutet av ett projekt kontrollera om du fortfarande behöver de resurser som du skapade. Resurser som fortsätter att köras kostar pengar. Du kan ta bort resurser individuellt eller ta bort resursgruppen om du vill ta bort hela uppsättningen resurser.

Du kan hitta och hantera resurser i portalen med hjälp av länken Alla resurser eller Resursgrupper i det vänstra navigeringsfönstret.

Kom ihåg att du är begränsad till tre index, indexerare och datakällor om du använder en kostnadsfri tjänst. Du kan ta bort enskilda objekt i portalen för att hålla dig under gränsen.

Nästa steg

Nu när du vet hur du utför kärnuppgifter kan du gå vidare med ytterligare REST API-anrop för mer avancerade funktioner, till exempel indexerare eller att konfigurera en berikningspipeline som lägger till innehållstransformationer i indexeringen. För nästa steg rekommenderar vi följande länk: