Snabbstart: Textsökning med hjälp av REST

  • Artikel

REST-API:erna i Azure AI Search ger programmatisk åtkomst till alla dess funktioner, inklusive förhandsversionsfunktioner, och de är ett enkelt sätt att lära sig hur funktioner fungerar. I den här snabbstarten får du lära dig hur du anropar REST API:er för sökning för att skapa, läsa in och köra frågor mot ett sökindex i Azure AI Search.

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

Förutsättningar

Ladda ned filer

Ladda ned ett REST-exempel från GitHub för att skicka begäranden i den här snabbstarten. Mer information finns i Ladda ned filer från GitHub.

Du kan också starta en ny fil i det lokala systemet och skapa begäranden manuellt med hjälp av anvisningarna i den här artikeln.

Kopiera en söktjänstnyckel och URL

REST-anrop kräver slutpunkten för söktjänsten och en API-nyckel för varje begäran. Du kan hämta dessa värden från Azure-portalen.

  1. Logga in på Azure-portalen. Gå sedan till sidan Översikt för söktjänsten och kopiera URL:en. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.

  2. Välj Inställningar> Nycklar och kopiera sedan en administratörsnyckel. Administratörsnycklar används för att lägga till, ändra och ta bort objekt. Det finns två utbytbara administratörsnycklar. Kopiera någon av dem.

    Skärmbild som visar URL:en och API-nycklarna i Azure-portalen.

Konfigurera Visual Studio Code

Om du inte är bekant med REST-klienten för Visual Studio Code innehåller det här avsnittet konfiguration så att du kan slutföra uppgifterna i den här snabbstarten.

  1. Starta Visual Studio Code och välj panelen Tillägg .

  2. Sök efter REST-klienten och välj Installera.

    Skärmbild som visar rest-klientens installationsknapp.

  3. Öppna eller skapa en ny fil med namnet med antingen ett .rest filnamnstillägg eller .http filnamnstillägg.

  4. Klistra in i följande exempel. Ersätt bas-URL:en och API-nyckeln med de värden som du kopierade tidigare.

    @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=2023-11-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. Välj Skicka begäran. Ett svar bör visas i ett intilliggande fönster. Om du har befintliga index visas de. Annars är listan tom. Om HTTP-koden är 200 OKär du redo för nästa steg.

    Skärmbild som visar en REST-klient som har konfigurerats för en söktjänstbegäran.

    Viktiga punkter:

    • Parametrar anges med hjälp av ett @ prefix.
    • ### anger ett REST-anrop. Nästa rad innehåller begäran, som måste innehålla HTTP/1.1.
    • Send request bör visas ovanför begäran.

Skapa ett index

Lägg till en andra begäran i filen .rest . Skapa index (REST) skapar ett sökindex och konfigurerar de fysiska datastrukturerna i söktjänsten.

  1. Klistra in följande exempel för att skapa indexet för hotels-quickstart söktjänsten.

    ### Create a new index
POST {{baseUrl}}/indexes?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

  2. Välj Skicka begäran. Du bör ha ett HTTP/1.1 201 Created svar och svarstexten bör innehålla JSON-representationen av indexschemat.

    Om du får ett Header name must be a valid HTTP token ["{"] fel kontrollerar du att det finns en tom rad mellan api-key och brödtexten i begäran. Om du får HTTP 504 kontrollerar du att URL:en anger HTTPS. Om HTTP 400 eller 404 returneras kontrollerar du att alla fält har kopierats och klistrats in korrekt i begärandetexten. En HTTP 403 indikerar vanligtvis ett problem med API-nyckeln. Det är antingen en ogiltig nyckel eller ett syntaxproblem med hur API-nyckeln anges.

    Nu har du flera begäranden i filen. Kom ihåg att ### startar en ny begäran och varje begäran körs separat.

    Skärmbild som visar REST-klienten med flera begäranden.

Om indexdefinitionen

I indexschemat definierar fältsamlingen dokumentstruktur. Varje dokument som du laddar upp måste ha dessa fält. Varje fält måste tilldelas en datatyp för entitetsdatamodell (EDM). Strängfält används i fulltextsökning. Om du vill att numeriska data ska vara sökbara kontrollerar du att datatypen är Edm.String. Andra datatyper som Edm.Int32 är filterbara, sorterbara, fasettbara och hämtningsbara men inte sökbara i fulltext.

Attribut i fältet avgör tillåtna åtgärder. REST-API:erna tillåter många åtgärder som standard. Alla strängar är till exempel sökbara och kan hämtas som standard. För REST-API:er kanske du bara har attribut om du behöver inaktivera 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}
        ]
     }
  ]
}

Läsa in dokument

Att skapa och läsa in indexet är separata steg. I Azure AI Search innehåller indexet alla sökbara data och frågor som körs i söktjänsten. För REST-anrop tillhandahålls data som JSON-dokument. Använd Documents – Index REST API för den här uppgiften.

URI:n utökas till att omfatta docs samlingar och index åtgärder.

  1. Klistra in följande exempel för att ladda upp JSON-dokument till sökindexet.

    ### Upload documents
POST {{baseUrl}}/indexes/hotels-quickstart/docs/index?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

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

  2. Välj Skicka begäran. Om några sekunder bör du se ett HTTP 201-svar i den intilliggande rutan.

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

Köra frågor

Nu när dokument har lästs in kan du skicka frågor mot dem med hjälp av Dokument – Sök efter (REST).

URI:n utökas till att omfatta ett frågeuttryck som anges med hjälp av operatorn /docs/search .

  1. Klistra in följande exempel för att fråga sökindexet. Välj sedan Skicka begäran. En textsökningsbegäran innehåller alltid en search parameter. Det här exemplet innehåller en valfri searchFields parameter som begränsar textsökningen till specifika fält.

    ### Run a query
POST {{baseUrl}}/indexes/hotels-quickstart/docs/search?api-version=2023-11-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

    {
        "search": "lake view",
        "select": "HotelId, HotelName, Tags, Description",
        "searchFields": "Description, Tags",
        "count": true
    }

  2. Granska svaret i det intilliggande fönstret. Du bör ha ett antal som anger antalet matchningar som finns i indexet, en sökpoäng som anger relevans och värden för varje fält som anges i -instruktionen select .

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

Hämta indexegenskaper

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

  1. Klistra in följande exempel för att fråga sökindexet. Välj sedan Skicka begäran.

    ### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2023-11-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

  2. Läs svaret. Den här åtgärden är ett enkelt sätt att få information om indexlagring.

    {
  "@odata.context": "https://my-demo.search.windows.net/$metadata#Microsoft.Azure.Search.V2023_11_01.IndexStatistics",
  "documentCount": 4,
  "storageSize": 34707,
  "vectorIndexSize": 0
}

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 enstaka resurser eller hela resursgruppen om du vill ta bort alla resurser.

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

Du kan också prova det här DELETE kommandot:

### Delete an index
DELETE  {{baseUrl}}/indexes/hotels-quickstart?api-version=2023-11-01 HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Gå vidare

Nu när du är bekant med REST-klienten och gör REST-anrop till Azure AI Search kan du prova en annan snabbstart som visar stöd för vektorer.

Snabbstart: Vektorsökning med REST