Načtení dat do indexu vyhledávání ve službě Azure AI Vyhledávač

Tento článek vysvětluje, jak importovat dokumenty do předdefinovaného indexu vyhledávání pomocí rozhraní REST API, sad Azure SDK nebo webu Azure Portal.

Požadavky

• Služba Azure AI Vyhledávač (libovolná úroveň). Vytvořte službu nebo vyhledejte existující službu.

• Existující index vyhledávání. Tento článek předpokládá, že jste už vytvořili index. Pokud potřebujete vytvořit a nahrát v jednom kroku, použijte průvodce importem nebo indexátor.

• Oprávnění k načtení dokumentů:

  • Ověřování na základě klíčů: Klíč rozhraní API správce pro vaši vyhledávací službu.
  • Ověřování na základě role: Role Přispěvatel dat indexu vyhledávání ve vyhledávací službě.

• Pro vývoj sady SDK nainstalujte klientskou knihovnu Služby Azure Search:

  • .NET: Azure. Search.Documents
  • Python: azure-search-documents
  • JavaScript: @azure/search-documents
  • Java: azure-search-documents

Použití portálu Azure Portal

Na webu Azure Portal pomocí průvodce importem vytvořte a načtěte indexy v bezproblémovém pracovním postupu. Pokud chcete načíst existující index, zvolte alternativní přístup.

1. Na webu Azure Portal přejděte do vyhledávací služby.

2. Na stránce Přehled vyberte importovat data na panelu příkazů, abyste vytvořili a naplnili index vyhledávání.

   

   Následující odkazy vám umožní zkontrolovat pracovní postup: Rychlý start: Vytvoření indexu Azure AI Vyhledávač a Rychlý start: Integrovaná vektorizace.

3. Po dokončení průvodce vyhledejte výsledky pomocí Průzkumníka služby Search.

Použití rozhraní REST API

Dokumenty – Index je rozhraní REST API pro import dat do indexu vyhledávání.

Text požadavku obsahuje jeden nebo více dokumentů, které se mají indexovat. Dokumenty jsou jednoznačně identifikovány pomocí klíče citlivého na malá a velká písmena. Každý dokument je přidružený k akci: "upload", "delete", "merge" nebo "mergeOrUpload". Žádosti o nahrání musí obsahovat data dokumentu jako sadu párů klíč/hodnota.

Rozhraní REST API jsou užitečná pro počáteční testování konceptu, kde můžete testovat pracovní postupy indexování, aniž byste museli psát velké množství kódu. Parametr @search.action určuje, zda jsou dokumenty přidány v plném rozsahu, nebo částečně z hlediska nových nebo náhradních hodnot pro konkrétní pole.

Rychlý start: Fulltextové vyhledávání pomocí REST vysvětluje kroky. Následující příklad je upravená verze příkladu. Hodnota se ořízá kvůli stručnosti a první hodnota HotelId se změní, aby se zabránilo přepsání existujícího dokumentu.

1. Formulujte volání POST určující název indexu, koncový bod docs/index a text požadavku, který obsahuje @search.action parametr.

   POST https://[service name].search.windows.net/indexes/hotels-sample/docs/index?api-version=2026-04-01
   Content-Type: application/json   
   api-key: [admin key] 
   {
       "value": [
       {
       "@search.action": "upload",
       "HotelId": "1111",
       "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" ]
       },
       {
       "@search.action": "mergeOrUpload",
       "HotelId": "2",
       "HotelName": "Old Century Hotel",
       "Description": "This is description is replacing the original one for this hotel. New and changed values overwrite the previous ones. In a comma-delimited list like Tags, be sure to provide the full list because there is no merging of values within the field itself.",
       "Category": "Boutique",
       "Tags": [ "pool", "free wifi", "concierge", "my first new tag", "my second new tag" ]
       }
     ]
   }
   

2. Nastavte parametr @search.action na upload pro vytvoření nebo přepsání dokumentu. Nastavte ho merge nebo uploadOrMerge pokud cílíte na aktualizace konkrétních polí v dokumentu. Předchozí příklad ukazuje obě akce.

   Akce	Účinnost
   nahrání	Podobně jako "upsert", kde se dokument vloží, pokud je nový, a pokud již existuje, je aktualizován nebo nahrazen. Pokud v dokumentu chybí hodnoty, které index vyžaduje, je hodnota pole dokumentu nastavená na hodnotu null.
   sloučení	Aktualizuje dokument, který již existuje, a selže dokument, který se nedá najít. Sloučení nahradí existující hodnoty. Z tohoto důvodu nezapomeňte zkontrolovat pole kolekce, která obsahují více hodnot, například pole typu Collection(Edm.String). Pokud například tags pole začíná hodnotou ["budget"] a provedete sloučení s ["economy", "pool"], konečná hodnota tags pole je ["economy", "pool"]. ["budget", "economy", "pool"] Není to.
   sloučitNeboNahrát	Chová se jako sloučení, pokud dokument existuje, a jako nahrání, pokud je dokument nový. Toto je nejběžnější akce pro přírůstkové aktualizace.
   odstranit	Odstranění odebere zadaný dokument z indexu. Jakékoli pole, které zadáte v operaci odstranění, kromě pole klíče, se ignoruje. Pokud chcete z dokumentu odebrat jednotlivé pole, použijte místo toho sloučení a nastavte pole explicitně na hodnotu null. Další informace najdete v tématu Odstranění dokumentů v indexu vyhledávání.

   Neexistují žádné záruky řazení, pro kterou se akce v textu požadavku spouští jako první. Nedoporučuje se mít více akcí sloučení přidružených ke stejnému dokumentu v jednom textu požadavku. Pokud pro stejný dokument vyžaduje více akcí sloučení, před aktualizací dokumentu v indexu vyhledávání proveďte sloučení na straně klienta.

   Pokud dokument v primitivních kolekcích obsahuje pole Tags typu Collection(Edm.String) s hodnotou ["budget"] a provedete sloučení s hodnotou ["economy", "pool"] pro Tags, konečná hodnota pole Tags bude ["economy", "pool"]. Není to typ ["budget", "economy", "pool"].

   Pokud dokument ve složitých kolekcích obsahuje komplexní pole kolekce s názvem Místnosti s hodnotou [{ "Typ": "Rozpočtová místnost", "BaseRate": 75.0 }] a provedete sloučení s hodnotou [{ "Typ": "Standardní pokoj" }, { "Typ": "Rozpočtová místnost", "BaseRate": 60.5 }], konečná hodnota pole Místnosti bude [{ "Typ": "Standardní pokoj" }, { "Typ": "Rozpočtová místnost", "BaseRate": 60.5 }]. Nebude to ani jedno z následujících:

   • [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }] (doplňovací prvky)

   • [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60.5 }] (slučujte prvky v pořadí a pak připojte všechny nadbytečné položky).

   Poznámka:

   Když nahrajete hodnoty DateTimeOffset s informacemi o časovém pásmu do indexu, Azure AI Vyhledávač tyto hodnoty normalizuje do standardu UTC. Například 2025-01-13T14:03:00-08:00 bude uložen jako 2025-01-13T22:03:00Z. Pokud potřebujete uložit informace o časovém pásmu, přidejte do indexu další sloupec.

3. Odešlete požadavek.

   Následující tabulka vysvětluje různé stavové kódy jednotlivých dokumentů, které lze vrátit v odpovědi. Některé stavové kódy označují problémy se samotným požadavkem, zatímco jiné označují dočasné chybové stavy. Druhý pokus byste měli opakovat po zpoždění.

   Stavový kód	Meaning	Opakovatelné	Poznámky
   200	Dokument se úspěšně upravil nebo odstranil.	není k dispozici	Operace odstranění jsou idempotentní. To znamená, že i když klíč dokumentu v indexu neexistuje, při pokusu o operaci odstranění s tímto klíčem vznikne stavový kód 200.
   201	Dokument byl úspěšně vytvořen.	není k dispozici
   400	V dokumentu došlo k chybě, která zabránila indexování.	Ne	Chybová zpráva v odpovědi označuje, co je v dokumentu špatně.
   404	Dokument nelze sloučit, protože daný klíč v indexu neexistuje.	Ne	K této chybě nedochází při nahrávání, protože vytvářejí nové dokumenty, a nedochází k ní při mazání, protože jsou idempotentní.
   409	Při pokusu o indexování dokumentu se zjistil konflikt verzí.	Ano	K tomu může dojít v případě, že se pokoušíte indexovat stejný dokument vícekrát současně.
   422	Index je dočasně nedostupný, protože se v něm aktualizoval příznak allowIndexDowntime nastavený na hodnotu true.	Ano
   429	Označuje, že jste překročili kvótu počtu dokumentů na index.	Ne	Pro vyšší limity kapacity musíte buď vytvořit nový index, nebo upgradovat.
   503	Vaše vyhledávací služba je dočasně nedostupná, pravděpodobně kvůli vysokému zatížení.	Ano	V takovém případě by váš kód měl před opakováním počkat, jinak riskujete prodloužení nedostupnosti služby.

   Poznámka:

   Pokud váš klientský kód často narazí na odpověď 207, je jedním z možných důvodů, proč je systém zatížený. Můžete to potvrdit tak, že zkontrolujete statusCode vlastnost 503. V takovém případě doporučujeme omezit požadavky na indexování. Jestliže indexovací provoz neklesne, může systém začít odmítat všechny požadavky se stavovou chybou 503.

4. Vyhledejte dokumenty , které jste právě přidali jako ověřovací krok:

   GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2026-04-01
   

Reference:Documents - Index, Documents - Get

Úspěšný požadavek na indexaci vrátí hodnotu HTTP 200 (OK) pro dávku, kde byly všechny dokumenty zpracovány úspěšně, nebo HTTP 207 (Více stavů), pokud některé dokumenty selhaly. Text odpovědi obsahuje stav pro každý dokument:

{
    "value": [
        { "key": "1111", "status": true, "statusCode": 201 },
        { "key": "2", "status": true, "statusCode": 200 }
    ]
}

Pokud je klíč dokumentu nebo ID nové, hodnota null se změní na hodnotu pro jakékoli pole, které není v dokumentu zadané. U akcí u existujícího dokumentu nahradí aktualizované hodnoty předchozí hodnoty. Všechna pole, která nebyla zadána v "merge" nebo "mergeUpload", zůstanou v indexu vyhledávání nedotčena.

Používejte sady Azure SDK

Programovatelnost je k dispozici v následujících sadách Azure SDK.

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Create the search client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-admin-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Define documents to upload
var documents = new[]
{
    new { HotelId = "1111", HotelName = "Stay-Kay City Hotel", Category = "Boutique" },
    new { HotelId = "1112", HotelName = "Old Century Hotel", Category = "Luxury" }
};

// Upload documents
IndexDocumentsResult result = await searchClient.IndexDocumentsAsync(
    IndexDocumentsBatch.Upload(documents));

Console.WriteLine($"Uploaded {result.Results.Count} documents");

Ověření načtení dat

Po načtení dokumentů ověřte, že se data správně indexují.

GET https://[service-name].search.windows.net/indexes/hotels-sample/docs/1111?api-version=2026-04-01
api-key: [admin-key]

// Verify document was indexed
var document = await searchClient.GetDocumentAsync<Hotel>("1111");
Console.WriteLine($"Found: {document.Value.HotelName}");

Jak funguje import dat

Vyhledávací služba přijímá dokumenty JSON, které odpovídají schématu indexu. Vyhledávací služba může importovat a indexovat obsah prostého textu a vektorový obsah v dokumentech JSON.

• Obsah ve formátu prostého textu se načítá z polí externího zdroje dat, z vlastností metadat nebo z rozšířeného obsahu generovaného sadou dovedností. Dovednosti mohou extrahovat nebo odvodit textové popisy z obrázků a nestrukturovaného obsahu.

• Vektorový obsah se načte ze zdroje dat, který ho poskytuje, nebo ho vytvoří sada dovedností, která implementuje integrovanou vektorizaci v úloze indexeru Azure AI Vyhledávač.

Tyto dokumenty můžete připravit sami, ale pokud se obsah nachází v podporovaném zdroji dat, spustí indexer nebo použije průvodce importem, může automatizovat načítání dokumentů, serializaci JSON a indexování.

Po indexování dat jsou fyzické datové struktury indexu uzamčeny. Pokyny k tomu, co se nedá změnit, najdete v tématu Aktualizace a opětovné sestavení indexu.

Indexování není proces na pozadí. Vyhledávací služba vyrovnává indexování a dotazování úloh, ale pokud je latence dotazů příliš vysoká, můžete buď přidat kapacitu , nebo identifikovat období nízké aktivity dotazů pro načtení indexu.

Další informace naleznete v tématu Strategie importu dat.

Řešení běžných chyb