Rychlý start: Vyhledávání klíčových slov pomocí REST

Článek
11/29/2024

Rozhraní REST API ve službě Azure AI Search poskytují programový přístup ke všem jeho funkcím, včetně funkcí ve verzi Preview, a představují snadný způsob, jak zjistit, jak funkce fungují. V tomto rychlém startu se dozvíte, jak volat rozhraní REST API pro vyhledávání za účelem vytvoření, načtení a dotazování indexu vyhledávání ve službě Azure AI Search.

Pokud ještě nemáte předplatné Azure, vytvořte si napřed bezplatný účet.

Požadavky

Visual Studio Code s klientem REST
Azure AI Search. Vytvořte nebo najděte existující prostředek služby Azure AI Search v rámci vašeho aktuálního předplatného. Pro účely tohoto rychlého startu můžete použít bezplatnou službu.

Stažení souborů

Stáhněte si ukázku REST z GitHubu pro odeslání požadavků v tomto rychlém startu. Pokyny najdete na webu Stažení souborů z GitHubu.

Můžete také spustit nový soubor v místním systému a ručně vytvořit požadavky pomocí pokynů v tomto článku.

Získání koncového bodu vyhledávací služby

Koncový bod vyhledávací služby najdete na webu Azure Portal.

Přihlaste se k webu Azure Portal a vyhledejte vyhledávací službu.
Na domovské stránce Přehled vyhledejte adresu URL. Příkladem koncového bodu může být https://mydemo.search.windows.net.

Tento koncový bod vkládáte do souboru nebo .http do .rest souboru v pozdějším kroku.

Konfigurace přístupu

Požadavky na koncový bod vyhledávání musí být ověřeny a autorizované. Pro tuto úlohu můžete použít klíče rozhraní API nebo role. Klíče se snadněji spouštějí, ale role jsou bezpečnější.

V případě připojení založeného na rolích se následující pokyny připojují k Azure AI Search pod vaší identitou, ne k identitě klientské aplikace.

Možnost 1: Použití klíčů

Vyberte Klíče nastavení>a pak zkopírujte klíč správce. Klíče správce slouží k přidávání, úpravám a odstraňování objektů. Existují dva zaměnitelné klíče správce. Zkopírujte jeden z nich. Další informace najdete v tématu Připojení k Azure AI Search pomocí ověřování klíčů.

Tento klíč vkládáte do .rest souboru nebo .http do souboru v pozdějším kroku.

Možnost 2: Použití rolí

Ujistěte se, že je vyhledávací služba nakonfigurovaná pro přístup na základě role. Musíte mít předkonfigurovaná přiřazení rolí pro přístup pro vývojáře. Přiřazení rolí musí udělit oprávnění k vytvoření, načtení a dotazování indexu vyhledávání.

V této části získejte token osobní identity pomocí Azure CLI, Azure PowerShellu nebo webu Azure Portal.

Přihlaste se k Azure CLI.
```
az login
```

Získejte token osobní identity.

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

Token osobní identity vkládáte do souboru nebo .http tokenu .rest osobní identity v pozdějším kroku.

Poznámka:

V této části se předpokládá, že používáte místního klienta, který se ve vašem zastoupení připojuje ke službě Azure AI Search. Alternativním přístupem je získání tokenu pro klientskou aplikaci za předpokladu, že je vaše aplikace zaregistrovaná v Microsoft Entra ID.

Nastavit nástroj Visual Studio Code

Pokud nejste obeznámeni s klientem REST pro Visual Studio Code, tato část obsahuje nastavení, abyste mohli dokončit úlohy v tomto rychlém startu.

Spusťte Visual Studio Code a vyberte dlaždici Rozšíření .
Vyhledejte klienta REST a vyberte Nainstalovat.
Otevřete nebo vytvořte nový soubor s příponou nebo .http příponou.rest.

Pokud používáte klíče rozhraní API, vložte ho do následujícího příkladu. @baseUrl Nahraďte zástupné @apiKey symboly hodnotami, které jste zkopírovali dříve, bez uvozovek.

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

Pokud používáte role, vložte ho do tohoto příkladu. @baseUrl Nahraďte zástupné @token symboly hodnotami, které jste zkopírovali dříve, bez uvozovek.

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

Vyberte Odeslat žádost. V sousedním podokně by se měla zobrazit odpověď. Pokud máte existující indexy, jsou uvedené. V opačném případě je seznam prázdný. Pokud je 200 OKkód HTTP, jste připraveni na další kroky.

Pokud se zobrazí WWW-Authenticate: Bearer realm="Azure Cognitive Search" error="invalid_token" error_description="Authentication token failed validation.", odeberte uvozovky kolem tokenu, uložte soubor a zkuste požadavek zopakovat.

Klíčové body:
- Parametry se zadají pomocí předpony @ .
- ### označuje volání REST. Další řádek obsahuje požadavek, který musí obsahovat HTTP/1.1.
- Send request by se měla zobrazit nad požadavkem.

Vytvoření indexu

Přidejte do .rest souboru druhý požadavek. Vytvoření indexu (REST) vytvoří vyhledávací index a nastaví fyzické datové struktury ve vyhledávací službě.

Vložte následující příklad a vytvořte index ve hotels-quickstart vyhledávací službě.

### 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}
                ]
            }
        ]
    }

Vyberte Odeslat žádost. Měli byste mít HTTP/1.1 201 Created odpověď a text odpovědi by měl obsahovat reprezentaci JSON schématu indexu.

Pokud se zobrazí Header name must be a valid HTTP token ["{"] chyba, ujistěte se, že je mezi api-key textem požadavku prázdný řádek. Pokud získáte HTTP 504, ověřte, že adresa URL určuje HTTPS. Pokud se zobrazí kód HTTP 400 nebo 404, zkontrolujte, jestli v textu žádosti nejsou chyby způsobené kopírováním a vkládáním. Http 403 obvykle značí problém s klíčem rozhraní API. Jedná se o neplatný klíč nebo problém se syntaxí se zadaným klíčem rozhraní API.

Teď máte v souboru několik požadavků. Vzpomeňte si, že ### spustí nový požadavek a každý požadavek se spustí nezávisle.

O definici indexu

Kolekce polí v rámci schématu indexu definuje strukturu dokumentu. Každý dokument, který nahrajete, musí mít tato pole. Každé pole musí být přiřazeno datovému typu Entity Data Model (EDM). Pole řetězců se používají v fulltextové vyhledávání. Pokud chcete, aby byla číselná data prohledávatelná, ujistěte se, že je Edm.Stringdatový typ . Jiné datové typy, jako Edm.Int32 jsou filtrovatelné, řaditelné, facetable a zobrazitelné, ale ne fulltextové prohledávatelné.

Atributy v poli určují povolené akce. Rozhraní REST API ve výchozím nastavení umožňují mnoho akcí. Například všechny řetězce jsou ve výchozím nastavení prohledávatelné a načístelné. U rozhraní REST API můžete mít pouze atributy, pokud potřebujete vypnout chování.

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

Nahrání dokumentů

Vytvoření a načtení indexu jsou samostatné kroky. Index ve službě Azure AI Search obsahuje všechna prohledávatelná data a dotazy spuštěné ve vyhledávací službě. Pro volání REST jsou data poskytována jako dokumenty JSON. Pro tuto úlohu použijte rozhraní REST API indexu dokumentů.

Identifikátor URI je rozšířen tak, aby zahrnoval docs kolekce a index operace.

Vložte následující příklad a nahrajte dokumenty JSON do indexu vyhledávání.

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

Vyberte Odeslat žádost. Během několika sekund by se v sousedním podokně měla zobrazit odpověď HTTP 201.

Pokud se zobrazí kód 207, nejméně jeden dokument nešel nahrát. Pokud se zobrazí kód 404, hlavička nebo text žádosti obsahuje syntaktickou chybu. Ověřte, že jste změnili koncový bod tak, aby zahrnoval /docs/index.

Spouštění dotazů

Když jsou teď načítány dokumenty, můžete s nimi zadávat dotazy pomocí funkce Dokumenty – vyhledávací příspěvek (REST).

Identifikátor URI je rozšířen tak, aby zahrnoval výraz dotazu, který je určen pomocí operátoru /docs/search .

Vložte do následujícího příkladu dotaz na index vyhledávání. Pak vyberte Odeslat požadavek. Požadavek na vyhledávání textu vždy obsahuje search parametr. Tento příklad obsahuje volitelný searchFields parametr, který omezuje vyhledávání textu na konkrétní pole.

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

Zkontrolujte odpověď v sousedním podokně. Měli byste mít počet, který označuje počet shod nalezených v indexu, skóre hledání, které označuje relevanci a hodnoty pro každé pole uvedené v select příkazu.

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

Získání vlastností indexu

K dotazování na počty dokumentů a velikost indexu můžete použít také funkci Získat statistiky .

Vložte do následujícího příkladu dotaz na index vyhledávání. Pak vyberte Odeslat požadavek.

### Get index statistics
GET {{baseUrl}}/indexes/hotels-quickstart/stats?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

Prohlédněte si odpověď. Tato operace představuje snadný způsob, jak získat podrobnosti o úložišti indexů.

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

Vyčištění prostředků

Pokud pracujete s vlastním předplatným, je vhodné vždy na konci projektu zkontrolovat, jestli budete vytvořené prostředky ještě potřebovat. Prostředky, které necháte spuštěné, vás stojí peníze. Prostředky můžete odstraňovat jednotlivě nebo můžete odstranit skupinu prostředků, a odstranit tak celou sadu prostředků najednou.

Prostředky můžete najít a spravovat na webu Azure Portal pomocí odkazu Všechny prostředky nebo skupiny prostředků v levém podokně.

Můžete také vyzkoušet tento DELETE příkaz:

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

Další krok

Teď, když jste obeznámeni s klientem REST a voláním REST do služby Azure AI Search, vyzkoušejte další rychlý start, který ukazuje podporu vektorů.

Rychlý start: Vektorové vyhledávání pomocí REST

Sdílet prostřednictvím