Snabbstart: Nyckelordssö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. Instruktioner 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.

Hämta en slutpunkt för söktjänsten

Du hittar slutpunkten för söktjänsten i Azure Portal.

  1. Logga in på Azure Portal och hitta söktjänsten.

  2. På startsidan Översikt hittar du URL:en. Här följer ett exempel på hur en slutpunkt kan se ut: https://mydemo.search.windows.net.

    Skärmbild av URL-egenskapen på översiktssidan.

Du klistrar in den här slutpunkten i .rest filen eller .http i ett senare steg.

Konfigurera åtkomst

Begäranden till sökslutpunkten måste autentiseras och auktoriseras. Du kan använda API-nycklar eller roller för den här uppgiften. Nycklar är enklare att börja med, men rollerna är säkrare.

För en rollbaserad anslutning får du följande instruktioner att ansluta till Azure AI Search under din identitet, inte identiteten för en klientapp.

Alternativ 1: Använd nycklar

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. Mer information finns i Ansluta till Azure AI Search med nyckelautentisering.

Skärmbild som visar API-nycklarna i Azure Portal.

Du klistrar in den här nyckeln i .rest filen eller .http i ett senare steg.

Alternativ 2: Använda roller

Kontrollera att söktjänsten är konfigurerad för rollbaserad åtkomst. Du måste ha förkonfigurerade rolltilldelningar för utvecklaråtkomst. Dina rolltilldelningar måste ge behörighet att skapa, läsa in och köra frågor mot ett sökindex.

I det här avsnittet hämtar du din personliga identitetstoken med antingen Azure CLI, Azure PowerShell eller Azure Portal.

  1. Logga in på Azure CLI.

    az login

  2. Hämta din personliga identitetstoken.

    az account get-access-token --scope https://search.azure.com/.default

Du klistrar in din personliga identitetstoken i .rest filen eller .http i ett senare steg.

Kommentar

Det här avsnittet förutsätter att du använder en lokal klient som ansluter till Azure AI Search åt dig. En alternativ metod är att hämta en token för klientappen, förutsatt att ditt program är registrerat med Microsoft Entra-ID.

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 om du använder API-nycklar. @baseUrl Ersätt platshållarna och @apiKey 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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. Eller klistra in i det här exemplet om du använder roller. @baseUrl Ersätt platshållarna och @token med de värden som du kopierade tidigare.

    @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}}

  6. 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=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}
                ]
            }
        ]
    }

  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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

    {
        "value": [
        {
        "@search.action": "upload",
        "HotelId": "1",
        "HotelName": "Stay-Kay City Hotel",
        "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": "Old Century Hotel",
        "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": "Gastronomic 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 Palace Hotel",
        "Description": "Sublime Palace 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 Palace 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=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
  }

  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 Palace Hotel",
      "Description": "Sublime Palace 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 Palace 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=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  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=2024-07-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