Delen via

Quickstart: Trefwoorden 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. Instructies vindt u bij Het downloaden van bestanden vanuit GitHub.

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

Een zoekservice-eindpunt ophalen

U vindt het eindpunt van de zoekservice in Azure Portal.

  1. Meld u aan bij Azure Portal en zoek uw zoekservice.

  2. Zoek op de startpagina Overzicht de URL. Een eindpunt ziet er bijvoorbeeld uit als https://mydemo.search.windows.net.

    Schermopname van de URL-eigenschap op de overzichtspagina.

U plakt dit eindpunt in het .rest of .http bestand in een latere stap.

Toegang configureren

Aanvragen voor het zoekeindpunt moeten worden geverifieerd en geautoriseerd. U kunt API-sleutels of -rollen voor deze taak gebruiken. Sleutels zijn gemakkelijker te beginnen, maar rollen zijn veiliger.

Voor een op rollen gebaseerde verbinding moet u met behulp van de volgende instructies verbinding maken met Azure AI Search onder uw identiteit, niet de identiteit van een client-app.

Optie 1: Sleutels gebruiken

Selecteer Instellingensleutels> en kopieer vervolgens een beheersleutel. Beheerderssleutels worden gebruikt om objecten toe te voegen, te wijzigen en te verwijderen. Er zijn twee uitwisselbare beheerderssleutels. Kopieer een van beide. Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie.

Schermopname van de API-sleutels in Azure Portal.

U plakt deze sleutel in het .rest of .http bestand in een latere stap.

Optie 2: Rollen gebruiken

Zorg ervoor dat uw zoekservice is geconfigureerd voor op rollen gebaseerde toegang. U moet vooraf geconfigureerde roltoewijzingen hebben voor toegang tot ontwikkelaars. Uw roltoewijzingen moeten machtigingen verlenen om een zoekindex te maken, laden en er query's op uit te voeren.

In deze sectie haalt u uw persoonlijke identiteitstoken op met behulp van de Azure CLI, Azure PowerShell of Azure Portal.

  1. Meld u aan bij Azure CLI.

    az login

  2. Haal uw persoonlijke identiteitstoken op.

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

In een latere stap plakt u uw persoonlijke identiteitstoken in het .rest of .http bestand.

Notitie

In deze sectie wordt ervan uitgegaan dat u een lokale client gebruikt die namens u verbinding maakt met Azure AI Search. Een alternatieve benadering is het ophalen van een token voor de client-app, ervan uitgaande dat uw toepassing is geregistreerd bij Microsoft Entra-id.

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 als u API-sleutels gebruikt. Vervang de @baseUrl tijdelijke aanduidingen door @apiKey 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=2024-07-01&$select=name  HTTP/1.1
   Content-Type: application/json
   api-key: {{apiKey}}

  5. U kunt ook in dit voorbeeld plakken als u rollen gebruikt. Vervang de @baseUrl tijdelijke aanduidingen door @token de waarden die u eerder hebt gekopieerd.

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

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

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