Adatok betöltése keresési indexbe az Azure AI Keresésben

Ez a cikk bemutatja, hogyan importálhat dokumentumokat egy előre definiált keresési indexbe REST API-k, Azure SDK-k vagy az Azure Portal használatával.

Előfeltételek

• Azure AI Keresés szolgáltatás (bármely szint). Hozzon létre egy szolgáltatást , vagy keressen egy meglévőt.

• Egy meglévő keresési index. Ez a cikk feltételezi, hogy már létrehozott egy indexet. Ha egy lépésben kell létrehoznia és betöltenie, használja az importálási varázslót vagy egy indexelőt.

• Dokumentumok betöltésére vonatkozó engedélyek:

  • Kulcsalapú hitelesítés: A keresési szolgáltatás rendszergazdai API-kulcsa .
  • Szerepköralapú hitelesítés: Keresési index adatszolgáltatói szerepköre a keresési szolgáltatásban.

• SDK-fejlesztéshez telepítse az Azure Search ügyfélkódtárát:

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

Az Azure Portal használata

Az Azure Portalon az importálási varázslóval hozhat létre és tölthet be indexeket egy zökkenőmentes munkafolyamatban. Ha meglévő indexet szeretne betölteni, válasszon másik módszert.

1. Nyissa meg a keresési szolgáltatást az Azure Portalon.

2. Az Áttekintés lapon válassza az Adatok importálása parancsot a parancssávon a keresési index létrehozásához és feltöltéséhez.

   

   Az alábbi hivatkozásokat követve áttekintheti a munkafolyamatot: Rövid útmutató: Azure AI Keresés-index létrehozása és rövid útmutató: Integrált vektorizáció.

3. A varázsló befejezése után a Kereséskezelővel keresse meg a találatokat.

A REST API-k használata

Dokumentumok – Az index az adatok keresési indexbe való importálására szolgáló REST API.

A kérelem törzse egy vagy több indexelendő dokumentumot tartalmaz. A dokumentumok egyedileg azonosíthatók egy kis- és nagybetűket megkülönböztető kulccsal. Minden dokumentum egy művelethez van társítva: "upload", "delete", "merge" vagy "mergeOrUpload". A feltöltési kérelmeknek tartalmazniuk kell a dokumentumadatokat kulcs-érték párok készleteként.

A REST API-k a kezdeti megvalósíthatósági vizsgálathoz hasznosak, ahol anélkül tesztelheti az indexelési munkafolyamatokat, hogy sok kódot kellene írnia. A @search.action paraméter azt határozza meg, hogy a dokumentumok teljes egészében vagy részben új vagy helyettesítő értékekben vannak-e hozzáadva adott mezőkhöz.

Rövid útmutató: A REST használatával végzett teljes szöveges keresés ismerteti a lépéseket. Az alábbi példa a példa módosított verziója. Az érték rövidség kedvéért le van rövidítve, és az első HotelId értéket módosítják annak érdekében, hogy elkerüljék egy meglévő dokumentum felülírását.

1. Alakítson ki egy POST-hívást, amely megadja az index nevét, a "docs/index" végpontot és a paramétert tartalmazó @search.action kérelemtörzset.

   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. Állítsa be a @search.action paramétert upload értékre a dokumentum létrehozásához vagy felülírásához. Állítsa be, merge vagy uploadOrMerge ha a dokumentum adott mezőinek frissítéseit célozza meg. Az előző példában mindkét művelet látható.

   Művelet	Hatály
   feltölt	Hasonló ahhoz az "upsert"-hez, amelyben a dokumentum be lesz szúrva, ha új, és ha létezik, frissítve vagy lecserélve. Ha a dokumentum nem rendelkezik az index által igényelt értékekkel, a dokumentummező értéke null értékre van állítva.
   egyesít	Frissíti a már létező dokumentumot, és hibát jelez, ha a dokumentum nem található. Az egyesítés lecseréli a meglévő értékeket. Ezért mindenképpen ellenőrizze, hogy a gyűjteménymezők több értéket tartalmaznak-e, például a típusmezőket Collection(Edm.String). Ha például egy tags mező értéke ["budget"]-vel kezdődik, és egy egyesítést hajt végre ["economy", "pool"] segítségével, akkor a tags mező végső értéke ["economy", "pool"]. ["budget", "economy", "pool"]Nem az.
   összevonás vagy feltöltés	Úgy viselkedik, mint az egyesítés, ha a dokumentum létezik, és feltölti, ha a dokumentum új. Ez a növekményes frissítések leggyakoribb művelete.
   töröl	A törlés eltávolítja a megadott dokumentumot az indexből. A rendszer figyelmen kívül hagyja a törlési műveletben megadott mezőket, a kulcsmezőn kívül. Ha el szeretne távolítani egy mezőt egy dokumentumból, használja inkább a merge parancsot, és állítsa a mezőt explicit módon null értékre. További információ: Dokumentumok törlése keresési indexben.

   Nincsenek olyan végrehajtási sorrend garanciák, amelyek biztosítanák, hogy a kérelem törzsében melyik műveletet hajtják végre először. Nem ajánlott több "egyesítési" műveletet társítani ugyanahhoz a dokumentumhoz egyetlen kérelemtörzsben. Ha több "egyesítési" műveletre van szükség ugyanahhoz a dokumentumhoz, végezze el az egyesítést az ügyféloldalon, mielőtt frissítené a dokumentumot a keresési indexben.

   A primitív gyűjteményekben, ha a dokumentum egy Collection(Edm.String) típusú Címkék mezőt tartalmaz, amelynek értéke ["budget"], és egyesítést hajt végre a Tag mezővel az érték ["economy", "pool"] esetében, a Címkék mező végső értéke ["economy", "pool"] lesz. Ez nem ["költségvetés", "gazdaságos", "medence"].

   Összetett gyűjteményekben, ha a dokumentum tartalmaz egy "Szobák" nevű összetett gyűjteménymezőt[{ "Type": "Budget Room", "BaseRate": 75.0 }], és egy egyesítést hajt végre [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60,5 }] értékkel, a Szobák mező végső értéke a következő lesz: [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. A következők egyike sem lesz:

   • [{ "Type": "Budget Room", "BaseRate": 75.0 }, { "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60,5 }] (hozzáfűző elemek)

   • [{ "Type": "Standard Room", "BaseRate": 75.0 }, { "Type": "Budget Room", "BaseRate": 60,5 }] (egyesítse az elemeket sorrendben, majd fűzze hozzá az esetleges extrákat)

   Megjegyzés:

   Amikor időzóna-információkkal tölti fel a DateTimeOffset-értékeket az indexbe, az Azure AI Keresés normalizálja ezeket az értékeket UTC értékre. A 2025-01-13T14:03:00-08:00 például 2025-01-13T22:03:00Z néven lesz tárolva. Ha időzóna-adatokat kell tárolnia, adjon hozzá egy további oszlopot az indexhez.

3. Küldje el a kérést.

   Az alábbi táblázat a válaszban visszaadható dokumentumonkénti állapotkódokat ismerteti. Egyes állapotkódok a kéréssel kapcsolatos problémákat, míg mások átmeneti hibafeltételeket jeleznek. Az utóbbit egy késleltetés után újra meg kell próbálkoznia.

   Állapotkód	Meaning	Újrapróbálható	Jegyzetek
   200	A dokumentum módosítása vagy törlése sikeresen megtörtént.	nincs adat	A törlési műveletek idempotensek. Vagyis még ha egy dokumentumkulcs nem is létezik az indexben, a törlési művelet megkísérlése ezzel a kulccsal 200-as állapotkódot eredményez.
   201	A dokumentum létrehozása sikeresen megtörtént.	nincs adat
   400	Hiba történt a dokumentumban, amely megakadályozta az indexelést.	Nem	A válaszban megjelenő hibaüzenet jelzi, hogy mi a probléma a dokumentummal.
   404	A dokumentum nem egyesíthető, mert a megadott kulcs nem létezik az indexben.	Nem	Ez a hiba nem fordul elő a feltöltések esetében, mivel új dokumentumokat hoznak létre, és nem törlődnek, mert idempotensek.
   409	A rendszer verzióütközést észlelt egy dokumentum indexelésének megkísérlésekor.	Igen	Ez akkor fordulhat elő, ha ugyanazt a dokumentumot egy időben többször próbálja indexelni.
   422	Az index átmenetileg nem érhető el, mert „true” (igaz) értékű allowIndexDowntime jelölővel lett frissítve.	Igen
   429	Azt jelzi, hogy túllépte a kvótát az indexenkénti dokumentumok száma alapján.	Nem	Létre kell hoznia egy új indexet, vagy frissítenie kell a nagyobb kapacitáskorlátok érdekében.
   503	A keresési szolgáltatás átmenetileg nem érhető el, valószínűleg nagy terhelés miatt.	Igen	Ebben az esetben a kódnak várnia kell az újrapróbálkozás előtt, különben fennáll a veszélye, hogy a szolgáltatás továbbra sem lesz elérhető.

   Megjegyzés:

   Ha az ügyfélkód gyakran találkozik egy 207-ben megadott válaszsal, az egyik lehetséges ok az, hogy a rendszer terhelés alatt van. Az 503 statusCode tulajdonságának ellenőrzésével ezt megerősítheti. Ha ez a helyzet, javasoljuk az indexelési kérelmek korlátozását. Ellenkező esetben, ha a forgalom indexelése nem csökken, a rendszer 503 hibával elkezdheti elutasítani az összes kérést.

4. Keresse meg az imént hozzáadott dokumentumokat érvényesítési lépésként:

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

Referencia:Dokumentumok – Index, Dokumentumok – Lekérés

A sikeres indexkérelem http 200 (OK) értéket ad vissza egy olyan köteghez, ahol az összes dokumentum sikeres volt, vagy http 207 (többszintű állapot), ha egyes dokumentumok sikertelenek voltak. A válasz törzse az egyes dokumentumok állapotát tartalmazza:

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

Ha a dokumentumkulcs vagy -azonosító új, a null érték lesz a dokumentumban nem meghatározott mezők értéke. Meglévő dokumentumon végzett műveletek esetén a frissített értékek felülírják az előző értékeket. Az "egyesítés" vagy az "mergeUpload" mezőben nem megadott mezők érintetlenül maradnak a keresési indexben.

Az Azure SDK-k használata

A programozhatóságot az alábbi Azure SDK-k biztosítják.

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");

Az adatbetöltés ellenőrzése

A dokumentumok betöltése után ellenőrizze, hogy az adatok megfelelően indexeltek-e.

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}");

Az adatimportálás működése

A keresési szolgáltatás elfogadja az indexsémának megfelelő JSON-dokumentumokat. A keresőszolgáltatás egyszerű szöveges tartalmat és vektortartalmat importálhat és indexelhet JSON-dokumentumokban.

• A rendszer egyszerű szöveges tartalmat kér le a külső adatforrás mezőiből, metaadat-tulajdonságokból vagy egy képességkészlet által létrehozott bővített tartalomból. A készségek szöveges leírásokat nyerhetnek ki vagy vonhatnak ki képekből és strukturálatlan tartalmakból.

• A vektortartalmak lekérése egy olyan adatforrásból történik, amely biztosítja azt, vagy egy olyan képességkészlet hozza létre, amely integrált vektorizációt implementál egy Azure AI Keresés indexelő számítási feladatban.

Ezeket a dokumentumokat saját maga is előkészítheti, de ha a tartalom támogatott adatforrásban található, akkor az indexelő futtatása vagy az importálási varázsló használata automatizálhatja a dokumentumok lekérését, a JSON-szerializálást és az indexelést.

Az adatok indexelése után az index fizikai adatstruktúrái zárolva lesznek. Az útmutatásért arról, hogy mi változtatható meg és mi nem, lásd: Index frissítése és újraépítése.

Az indexelés nem háttérfolyamat. A keresési szolgáltatás kiegyensúlyozza az indexelést és a lekérdezési számítási feladatokat, de ha a lekérdezés késése túl magas, kapacitást adhat hozzá , vagy azonosíthatja az index betöltéséhez szükséges alacsony lekérdezési tevékenységeket.

További információ: Adatimportálási stratégiák.

Gyakori hibák elhárítása