Snelstartgids: Tekst zoeken met behulp van REST

  • Artikel

De REST API's in Azure AI Search bieden programmatische toegang tot alle mogelijkheden, waaronder preview-functies, en ze zijn een eenvoudige manier om te leren hoe functies werken. In deze quickstart leert u hoe u de Search REST API's aanroept om een zoekindex te maken, laden en er query's op uit te voeren in Azure AI Search.

Als u geen Azure-abonnement hebt, maakt u een gratis account voordat u begint.

Vereisten

Bestanden downloaden

Download een REST-voorbeeld van GitHub om de aanvragen in deze quickstart te verzenden. Zie Bestanden downloaden van GitHub voor meer informatie.

U kunt ook een nieuw bestand op uw lokale systeem starten en handmatig aanvragen maken met behulp van de instructies in dit artikel.

Een zoekservicesleutel en -URL kopiëren

REST-aanroepen vereisen het eindpunt van de zoekservice en een API-sleutel voor elke aanvraag. U kunt deze waarden ophalen uit Azure Portal.

  1. Meld u aan bij het Azure-portaal. Ga vervolgens naar de overzichtspagina van de zoekservice en kopieer de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.

  2. Selecteer Instellingen> Sleutels en kopieer vervolgens een beheerderssleutel. Beheer sleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide.

    Schermopname van de URL- en API-sleutels in Azure Portal.

Visual Studio Code instellen

Als u niet bekend bent met de REST-client voor Visual Studio Code, bevat deze sectie setup, zodat u de taken in deze quickstart kunt voltooien.

  1. Start Visual Studio Code en selecteer de tegel Extensies .

  2. Zoek de REST-client en selecteer Installeren.

    Schermopname van de knop INSTALLEREN van DE REST-client.

  3. Open of maak een nieuw bestand met de naam een .rest of .http bestandsextensie.

  4. Plak in het volgende voorbeeld. Vervang de basis-URL en API-sleutel door de waarden die u eerder hebt gekopieerd.

    @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. Selecteer Verzoek verzenden. Er moet een antwoord worden weergegeven in een aangrenzend deelvenster. Als u bestaande indexen hebt, worden deze weergegeven. Anders is de lijst leeg. Als de HTTP-code is 200 OK, bent u klaar voor de volgende stappen.

    Schermopname van een REST-client die is geconfigureerd voor een zoekserviceaanvraag.

    Belangrijke punten:

    • Parameters worden opgegeven met behulp van een @ voorvoegsel.
    • ### wijst een REST-aanroep aan. De volgende regel bevat de aanvraag, die moet bevatten HTTP/1.1.
    • Send request moet boven de aanvraag worden weergegeven.

Een index maken

Voeg een tweede aanvraag toe aan uw .rest bestand. Index maken (REST) maakt een zoekindex en stelt de fysieke gegevensstructuren in uw zoekservice in.

  1. Plak in het volgende voorbeeld om de hotels-quickstart index in uw zoekservice te maken.

    ### 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. Selecteer Verzoek verzenden. U moet een HTTP/1.1 201 Created antwoord hebben en de hoofdtekst van het antwoord moet de JSON-weergave van het indexschema bevatten.

    Als er een Header name must be a valid HTTP token ["{"] fout optreedt, controleert u of er een lege regel tussen api-key en de hoofdtekst van de aanvraag staat. Als u HTTP 504 krijgt, controleert u of de URL HTTPS opgeeft. Als de HTTP-fout 400 of 404 wordt weergegeven ziet, controleert u of de aanvraagtekst op fouten die mogelijk zijn opgetreden tijden kopiëren en plakken. Een HTTP 403 duidt meestal op een probleem met de API-sleutel. Het is een ongeldige sleutel of een syntaxisprobleem met de wijze waarop de API-sleutel wordt opgegeven.

    U hebt nu verschillende aanvragen in uw bestand. Zoals u weet, ### wordt een nieuwe aanvraag gestart en wordt elke aanvraag onafhankelijk uitgevoerd.

    Schermopname van de REST-client met meerdere aanvragen.

Over de indexdefinitie

In het indexschema definieert de verzameling velden de documentstructuur. Elk document dat u uploadt, moet deze velden hebben. Elk veld moet worden toegewezen aan een EDM-gegevenstype (Entity Data Model). Tekenreeksvelden worden gebruikt in zoekacties in volledige tekst. Als u wilt dat numerieke gegevens doorzoekbaar zijn, moet u ervoor zorgen dat het gegevenstype is Edm.String. Andere gegevenstypen, zoals Edm.Int32 filterbaar, sorteerbaar, facetabel en ophaalbaar, maar niet doorzoekbaar in volledige tekst.

Kenmerken in het veld bepalen toegestane acties. De REST API's staan standaard veel acties toe. Alle tekenreeksen kunnen bijvoorbeeld standaard worden doorzocht en opgehaald. Voor REST API's hebt u mogelijk alleen kenmerken als u een gedrag wilt uitschakelen.

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

Documenten laden

Het maken en laden van de index zijn afzonderlijke stappen. In Azure AI Search bevat de index alle doorzoekbare gegevens en query's die worden uitgevoerd op de zoekservice. Voor REST-aanroepen worden de gegevens verstrekt als JSON-documenten. Gebruik Documenten- INDEX REST API voor deze taak.

De URI wordt uitgebreid met de docs verzamelingen en index bewerkingen.

  1. Plak in het volgende voorbeeld om JSON-documenten te uploaden naar de zoekindex.

    ### 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. Selecteer Verzoek verzenden. Binnen een paar seconden ziet u een HTTP 201-antwoord in het aangrenzende deelvenster.

    Als u een 207-respons ontvang, is minimaal één document niet geüpload. Als u een 404-respons ontvangt, bevat de header of de hoofdtekst van de aanvraag een syntaxisfout. Controleer of u het eindpunt hebt gewijzigd zodat het wordt opgenomen /docs/index.

Query's uitvoeren

Nu documenten zijn geladen, kunt u er query's op uitvoeren met behulp van Documenten - Zoekbericht (REST).

De URI wordt uitgebreid met een query-expressie, die wordt opgegeven met behulp van de /docs/search operator.

  1. Plak in het volgende voorbeeld om een query uit te voeren op de zoekindex. Selecteer vervolgens Aanvraag verzenden. Een zoekaanvraag voor tekst bevat altijd een search parameter. Dit voorbeeld bevat een optionele searchFields parameter waarmee zoeken in tekst wordt beperkt tot specifieke velden.

    ### 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. Bekijk het antwoord in het aangrenzende deelvenster. U moet een telling hebben die het aantal overeenkomsten aangeeft dat in de index is gevonden, een zoekscore die relevantie aangeeft en waarden voor elk veld dat in de select instructie wordt vermeld.

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

Indexeigenschappen ophalen

U kunt ook Get Statistics gebruiken om query's uit te voeren op het aantal documenten en de indexgrootte.

  1. Plak in het volgende voorbeeld om een query uit te voeren op de zoekindex. Selecteer vervolgens Aanvraag verzenden.

    ### 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. Bekijk het antwoord. Deze bewerking is een eenvoudige manier om details over indexopslag op te halen.

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

Resources opschonen

Wanneer u in uw eigen abonnement werkt, is het een goed idee om aan het einde van een project te bepalen of u de gemaakte resources nog nodig hebt. Resources die actief blijven, kunnen u geld kosten. U kunt resources afzonderlijk verwijderen, maar u kunt ook de resourcegroep verwijderen als u de volledige resourceset wilt verwijderen.

U kunt resources vinden en beheren in de portal met behulp van de koppeling Alle resources of resourcegroepen in het meest linkse deelvenster.

U kunt ook deze DELETE opdracht proberen:

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

Volgende stap

Nu u bekend bent met de REST-client en REST-aanroepen uitvoert naar Azure AI Search, kunt u een andere quickstart proberen die vectorondersteuning demonstreert.

Quickstart: Vector search using REST